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
8struct iovec;
9
10namespace android {
11namespace pdx {
12
13class Service;
14class Channel;
15class Message;
16
17struct 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.
37class 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
141}  // namespace pdx
142}  // namespace android
143
144#endif  // ANDROID_PDX_ENDPOINT_H_
145