1// Copyright 2014 The Chromium Authors. All rights reserved.
2// Use of this source code is governed by a BSD-style license that can be
3// found in the LICENSE file.
4
5#ifndef MOJO_PUBLIC_CPP_BINDINGS_INTERFACE_PTR_H_
6#define MOJO_PUBLIC_CPP_BINDINGS_INTERFACE_PTR_H_
7
8#include <algorithm>
9
10#include "mojo/public/cpp/bindings/error_handler.h"
11#include "mojo/public/cpp/bindings/lib/interface_ptr_internal.h"
12#include "mojo/public/cpp/environment/environment.h"
13#include "mojo/public/cpp/system/macros.h"
14
15namespace mojo {
16class ErrorHandler;
17
18// InterfacePtr represents a proxy to a remote instance of an interface.
19template <typename Interface>
20class InterfacePtr {
21  MOJO_MOVE_ONLY_TYPE_FOR_CPP_03(InterfacePtr, RValue)
22 public:
23  InterfacePtr() {}
24
25  InterfacePtr(RValue other) {
26    internal_state_.Swap(&other.object->internal_state_);
27  }
28  InterfacePtr& operator=(RValue other) {
29    reset();
30    internal_state_.Swap(&other.object->internal_state_);
31    return *this;
32  }
33
34  ~InterfacePtr() {}
35
36  Interface* get() const {
37    return internal_state_.instance();
38  }
39  Interface* operator->() const { return get(); }
40  Interface& operator*() const { return *get(); }
41
42  void reset() {
43    State doomed;
44    internal_state_.Swap(&doomed);
45  }
46
47  // Blocks the current thread for the first incoming method call, i.e., either
48  // a call to a client method or a callback method. Returns |true| if a method
49  // has been called, |false| in case of error. It must only be called on a
50  // bound object.
51  bool WaitForIncomingMethodCall() {
52    return internal_state_.WaitForIncomingMethodCall();
53  }
54
55  // This method configures the InterfacePtr<..> to be a proxy to a remote
56  // object on the other end of the given pipe.
57  //
58  // The proxy is bound to the current thread, which means its methods may
59  // only be called on the current thread.
60  //
61  // To move a bound InterfacePtr<..> to another thread, call PassMessagePipe().
62  // Then create a new InterfacePtr<..> on another thread, and bind the new
63  // InterfacePtr<..> to the message pipe on that thread.
64  void Bind(
65      ScopedMessagePipeHandle handle,
66      const MojoAsyncWaiter* waiter = Environment::GetDefaultAsyncWaiter()) {
67    reset();
68    internal_state_.Bind(handle.Pass(), waiter);
69  }
70
71  // The client interface may only be set after this InterfacePtr<..> is bound.
72  void set_client(typename Interface::Client* client) {
73    internal_state_.set_client(client);
74  }
75
76  // This method may be called to query if the underlying pipe has encountered
77  // an error. If true, this means method calls made on this interface will be
78  // dropped (and may have already been dropped) on the floor.
79  bool encountered_error() const {
80    return internal_state_.encountered_error();
81  }
82
83  // This method may be called to register an ErrorHandler to observe a
84  // connection error on the underlying pipe. It must only be called on a bound
85  // object.
86  // The callback runs asynchronously from the current message loop.
87  void set_error_handler(ErrorHandler* error_handler) {
88    internal_state_.set_error_handler(error_handler);
89  }
90
91  // Returns the underlying message pipe handle (if any) and resets the
92  // InterfacePtr<..> to its uninitialized state. This method is helpful if you
93  // need to move a proxy to another thread. See related notes for Bind.
94  ScopedMessagePipeHandle PassMessagePipe() {
95    State state;
96    internal_state_.Swap(&state);
97    return state.PassMessagePipe();
98  }
99
100  // DO NOT USE. Exposed only for internal use and for testing.
101  internal::InterfacePtrState<Interface>* internal_state() {
102    return &internal_state_;
103  }
104
105  // Allow InterfacePtr<> to be used in boolean expressions, but not
106  // implicitly convertible to a real bool (which is dangerous).
107 private:
108  typedef internal::InterfacePtrState<Interface> InterfacePtr::*Testable;
109
110 public:
111  operator Testable() const {
112    return internal_state_.is_bound() ? &InterfacePtr::internal_state_ : NULL;
113  }
114
115 private:
116  typedef internal::InterfacePtrState<Interface> State;
117  mutable State internal_state_;
118};
119
120// Takes a handle to the proxy end-point of a pipe. On the other end is
121// presumed to be an interface implementation of type |Interface|. Returns a
122// generated proxy to that interface, which may be used on the current thread.
123// It is valid to call set_client on the returned InterfacePtr<..> to set an
124// instance of Interface::Client.
125template <typename Interface>
126InterfacePtr<Interface> MakeProxy(
127    ScopedMessagePipeHandle handle,
128    const MojoAsyncWaiter* waiter = Environment::GetDefaultAsyncWaiter()) {
129  InterfacePtr<Interface> ptr;
130  if (handle.is_valid())
131    ptr.Bind(handle.Pass(), waiter);
132  return ptr.Pass();
133}
134
135}  // namespace mojo
136
137#endif  // MOJO_PUBLIC_CPP_BINDINGS_INTERFACE_PTR_H_
138