1 #ifndef ANDROID_PDX_ENDPOINT_H_ 2 #define ANDROID_PDX_ENDPOINT_H_ 3 4 #include <pdx/channel_handle.h> 5 #include <pdx/file_handle.h> 6 #include <pdx/status.h> 7 8 struct iovec; 9 10 namespace android { 11 namespace pdx { 12 13 class Service; 14 class Channel; 15 class Message; 16 17 struct MessageInfo { 18 int pid{0}; 19 int tid{0}; 20 int cid{0}; 21 int mid{0}; 22 int euid{0}; 23 int egid{0}; 24 int32_t op{0}; 25 uint32_t flags{0}; 26 Service* service{nullptr}; 27 Channel* channel{nullptr}; 28 size_t send_len{0}; 29 size_t recv_len{0}; 30 size_t fd_count{0}; 31 uint64_t impulse[4] = {}; 32 }; 33 34 // Wrapper around transport endpoint. Abstracts the underlying transport APIs in 35 // a way, that the underlying IPC can be substituted for another technology 36 // without changing the Service, Client and Message classes of this library. 37 class Endpoint { 38 public: 39 virtual ~Endpoint() = default; 40 41 // Returns a tag that uniquely identifies a specific underlying IPC transport. 42 virtual uint32_t GetIpcTag() const = 0; 43 44 // Associates a Service instance with an endpoint by setting the service 45 // context pointer to the address of the Service. Only one Service may be 46 // associated with a given endpoint. 47 virtual Status<void> SetService(Service* service) = 0; 48 49 // Set the channel context for the given channel. 50 virtual Status<void> SetChannel(int channel_id, Channel* channel) = 0; 51 52 // Close a channel, signaling the client file object and freeing the channel 53 // id. Once closed, the client side of the channel always returns the error 54 // ESHUTDOWN and signals the poll/epoll events POLLHUP and POLLFREE. 55 virtual Status<void> CloseChannel(int channel_id) = 0; 56 57 // Update the event bits for the given channel (given by id), using the 58 // given clear and set masks. 59 virtual Status<void> ModifyChannelEvents(int channel_id, int clear_mask, 60 int set_mask) = 0; 61 62 // Create a new channel and push it as a file descriptor to the process 63 // sending the |message|. |flags| may be set to O_NONBLOCK and/or 64 // O_CLOEXEC to control the initial behavior of the new file descriptor (the 65 // sending process may change these later using fcntl()). The internal Channel 66 // instance associated with this channel is set to |channel|, which may be 67 // nullptr. The new channel id allocated for this channel is returned in 68 // |channel_id|, which may also be nullptr if not needed. 69 virtual Status<RemoteChannelHandle> PushChannel(Message* message, int flags, 70 Channel* channel, 71 int* channel_id) = 0; 72 73 // Check whether the |ref| is a reference to a channel to the service 74 // represented by the |endpoint|. If the channel reference in question is 75 // valid, the Channel object is returned in |channel| when non-nullptr and 76 // the channel ID is returned through the Status object. 77 virtual Status<int> CheckChannel(const Message* message, ChannelReference ref, 78 Channel** channel) = 0; 79 80 // Receives a message on the given endpoint file descriptor. 81 virtual Status<void> MessageReceive(Message* message) = 0; 82 83 // Replies to the message with a return code. 84 virtual Status<void> MessageReply(Message* message, int return_code) = 0; 85 86 // Replies to the message with a file descriptor. 87 virtual Status<void> MessageReplyFd(Message* message, 88 unsigned int push_fd) = 0; 89 90 // Replies to the message with a local channel handle. 91 virtual Status<void> MessageReplyChannelHandle( 92 Message* message, const LocalChannelHandle& handle) = 0; 93 94 // Replies to the message with a borrowed local channel handle. 95 virtual Status<void> MessageReplyChannelHandle( 96 Message* message, const BorrowedChannelHandle& handle) = 0; 97 98 // Replies to the message with a remote channel handle. 99 virtual Status<void> MessageReplyChannelHandle( 100 Message* message, const RemoteChannelHandle& handle) = 0; 101 102 // Reads message data into an array of memory buffers. 103 virtual Status<size_t> ReadMessageData(Message* message, const iovec* vector, 104 size_t vector_length) = 0; 105 106 // Sends reply data for message. 107 virtual Status<size_t> WriteMessageData(Message* message, const iovec* vector, 108 size_t vector_length) = 0; 109 110 // Records a file descriptor into the message buffer and returns the remapped 111 // reference to be sent to the remote process. 112 virtual Status<FileReference> PushFileHandle(Message* message, 113 const LocalHandle& handle) = 0; 114 virtual Status<FileReference> PushFileHandle( 115 Message* message, const BorrowedHandle& handle) = 0; 116 virtual Status<FileReference> PushFileHandle(Message* message, 117 const RemoteHandle& handle) = 0; 118 virtual Status<ChannelReference> PushChannelHandle( 119 Message* message, const LocalChannelHandle& handle) = 0; 120 virtual Status<ChannelReference> PushChannelHandle( 121 Message* message, const BorrowedChannelHandle& handle) = 0; 122 virtual Status<ChannelReference> PushChannelHandle( 123 Message* message, const RemoteChannelHandle& handle) = 0; 124 125 // Obtains a file descriptor/channel handle from a message for the given 126 // reference. 127 virtual LocalHandle GetFileHandle(Message* message, 128 FileReference ref) const = 0; 129 virtual LocalChannelHandle GetChannelHandle(Message* message, 130 ChannelReference ref) const = 0; 131 132 // Transport-specific message state management. 133 virtual void* AllocateMessageState() = 0; 134 virtual void FreeMessageState(void* state) = 0; 135 136 // Cancels the endpoint, unblocking any receiver threads waiting for a 137 // message. 138 virtual Status<void> Cancel() = 0; 139 140 // Returns an fd that can be used with epoll() to wait for incoming messages 141 // from this endpoint. 142 virtual int epoll_fd() const = 0; 143 }; 144 145 } // namespace pdx 146 } // namespace android 147 148 #endif // ANDROID_PDX_ENDPOINT_H_ 149