summaryrefslogtreecommitdiffstats
path: root/include/iprt/localipc.h
blob: 2ce8e4698069161fe3a9d2f832e54349c043e685 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
/** @file
 * IPRT - Local IPC Server & Client.
 */

/*
 * Copyright (C) 2006-2023 Oracle and/or its affiliates.
 *
 * This file is part of VirtualBox base platform packages, as
 * available from https://www.virtualbox.org.
 *
 * This program is free software; you can redistribute it and/or
 * modify it under the terms of the GNU General Public License
 * as published by the Free Software Foundation, in version 3 of the
 * License.
 *
 * This program is distributed in the hope that it will be useful, but
 * WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, see <https://www.gnu.org/licenses>.
 *
 * The contents of this file may alternatively be used under the terms
 * of the Common Development and Distribution License Version 1.0
 * (CDDL), a copy of it is provided in the "COPYING.CDDL" file included
 * in the VirtualBox distribution, in which case the provisions of the
 * CDDL are applicable instead of those of the GPL.
 *
 * You may elect to license modified versions of this file under the
 * terms and conditions of either the GPL or the CDDL or both.
 *
 * SPDX-License-Identifier: GPL-3.0-only OR CDDL-1.0
 */

#ifndef IPRT_INCLUDED_localipc_h
#define IPRT_INCLUDED_localipc_h
#ifndef RT_WITHOUT_PRAGMA_ONCE
# pragma once
#endif

#include <iprt/cdefs.h>
#include <iprt/types.h>
#include <iprt/thread.h>

#ifdef IN_RING0
# error "There are no RTLocalIpc APIs available Ring-0 Host Context!"
#endif


RT_C_DECLS_BEGIN

/** @defgroup grp_rt_localipc   RTLocalIpc - Local IPC
 * @ingroup grp_rt
 * @{
 */

/** Handle to a local IPC server instance. */
typedef struct RTLOCALIPCSERVERINT     *RTLOCALIPCSERVER;
/** Pointer to a local IPC server handle. */
typedef RTLOCALIPCSERVER               *PRTLOCALIPCSERVER;
/** Local IPC server handle nil value. */
#define NIL_RTLOCALIPCSERVER            ((RTLOCALIPCSERVER)0)

/** Handle to a local ICP session instance. */
typedef struct RTLOCALIPCSESSIONINT    *RTLOCALIPCSESSION;
/** Pointer to a local ICP session handle. */
typedef RTLOCALIPCSESSION              *PRTLOCALIPCSESSION;
/** Local ICP session handle nil value. */
#define NIL_RTLOCALIPCSESSION           ((RTLOCALIPCSESSION)0)



/**
 * Create a local IPC server.
 *
 * @returns IPRT status code.
 * @retval  VINF_SUCCESS on success and *phServer containing the instance handle.
 *
 * @param   phServer    Where to put the server instance handle.
 * @param   pszName     The server name.  This must be unique and not include
 *                      any special chars or slashes. It will be morphed into a
 *                      unique platform specific identifier.
 * @param   fFlags      Flags, see RTLOCALIPC_FLAGS_*.
 */
RTDECL(int) RTLocalIpcServerCreate(PRTLOCALIPCSERVER phServer, const char *pszName, uint32_t fFlags);

/** @name RTLocalIpcServerCreate flags
 * @{ */
/** Native name, as apposed to a portable one. */
#define RTLOCALIPC_FLAGS_NATIVE_NAME        RT_BIT_32(0)
/** The mask of valid flags. */
#define RTLOCALIPC_FLAGS_VALID_MASK         UINT32_C(0x00000001)
/** @} */

/**
 * Destroys a local IPC server.
 *
 * @returns IPRT status code.
 * @retval  VINF_SUCCESS if still other references or NIL.
 * @retval  VINF_OBJECT_DESTROYED if actually destroyed.
 *
 * @param   hServer     The server handle. The nil value is quietly ignored (VINF_SUCCESS).
 */
RTDECL(int) RTLocalIpcServerDestroy(RTLOCALIPCSERVER hServer);

/**
 * Grant the specified group access to the local IPC server socket.
 *
 * @returns IPRT status code.
 * @param   hServer     The server handle.
 * @param   gid         Group ID.
 */
RTDECL(int) RTLocalIpcServerGrantGroupAccess(RTLOCALIPCSERVER hServer, RTGID gid);

/**
 * Set access mode for IPC server socket.
 *
 * @returns IPRT status code.
 * @param   hServer     The server handle.
 * @param   fMode       Access mode.
 */
RTDECL(int) RTLocalIpcServerSetAccessMode(RTLOCALIPCSERVER hServer, RTFMODE fMode);

/**
 * Listen for clients.
 *
 * @returns IPRT status code.
 * @retval  VINF_SUCCESS on success and *phClientSession containing the session handle.
 * @retval  VERR_CANCELLED if the listening was interrupted by RTLocalIpcServerCancel().
 *
 * @param   hServer             The server handle.
 * @param   phClientSession     Where to store the client session handle on success.
 *
 */
RTDECL(int) RTLocalIpcServerListen(RTLOCALIPCSERVER hServer, PRTLOCALIPCSESSION phClientSession);

/**
 * Cancel the current or subsequent RTLocalIpcServerListen call.
 *
 * @returns IPRT status code.
 * @param   hServer     The server handle. The nil value is quietly ignored (VINF_SUCCESS).
 */
RTDECL(int) RTLocalIpcServerCancel(RTLOCALIPCSERVER hServer);


/**
 * Connects to a local IPC server.
 *
 * This is used a client process (or thread).
 *
 * @returns IPRT status code.
 * @retval  VINF_SUCCESS on success and *phSession holding the session handle.
 *
 * @param   phSession           Where to store the sesson handle on success.
 * @param   pszName             The server name (see RTLocalIpcServerCreate for details).
 * @param   fFlags              Flags, RTLOCALIPC_C_FLAGS_XXX.
 */
RTDECL(int) RTLocalIpcSessionConnect(PRTLOCALIPCSESSION phSession, const char *pszName, uint32_t fFlags);

/** @name RTLOCALIPC_C_FLAGS_XXX - RTLocalIpcSessionConnect flags
 * @{ */
/** Native name, as apposed to a portable one. */
#define RTLOCALIPC_C_FLAGS_NATIVE_NAME      RT_BIT_32(0)
/** The mask of valid flags. */
#define RTLOCALIPC_C_FLAGS_VALID_MASK       UINT32_C(0x00000001)
/** @} */

/**
 * Closes the local IPC session.
 *
 * This can be used with sessions created by both RTLocalIpcSessionConnect
 * and RTLocalIpcServerListen.  It will release one cancel pending I/O and
 * relase one reference (typically the implict reference from the create API).
 *
 * @returns IPRT status code.
 * @retval  VINF_SUCCESS if still other references or NIL.
 * @retval  VINF_OBJECT_DESTROYED if session destroyed.
 *
 * @param   hSession            The session handle. The nil value is quietly ignored (VINF_SUCCESS).
 */
RTDECL(int) RTLocalIpcSessionClose(RTLOCALIPCSESSION hSession);

/**
 * Retain a refence to the given session.
 *
 * @returns New reference count, UINT32_MAX if the handle is invalid.
 * @param   hSession            The session handle.
 */
RTDECL(uint32_t) RTLocalIpcSessionRetain(RTLOCALIPCSESSION hSession);

/**
 * Releases a refence to the given session.
 *
 * This differs from RTLocalIpcSessionClose in that it won't cancel any pending
 * I/O.  So, better call RTLocalIpcSessionClose if you want to terminate the
 * session.
 *
 * @returns New reference count, 0 if NIL handle, UINT32_MAX if the handle is
 *          invalid.
 * @param   hSession            The session handle.
 */
RTDECL(uint32_t) RTLocalIpcSessionRelease(RTLOCALIPCSESSION hSession);


/**
 * Receive data from the other end of an local IPC session.
 *
 * This will block if there isn't any data.
 *
 * @returns IPRT status code.
 * @retval  VERR_CANCELLED if the operation was cancelled by RTLocalIpcSessionCancel.
 *
 * @param   hSession            The session handle.
 * @param   pvBuf               Where to store the data.
 * @param   cbToRead            How much to read.  This is exact request if
 *                              pcbRead is NULL, otherwise it's an upper limit.
 * @param   pcbRead             Optional argument for indicating a partial read
 *                              and returning the number of bytes actually read.
 */
RTDECL(int) RTLocalIpcSessionRead(RTLOCALIPCSESSION hSession, void *pvBuf, size_t cbToRead, size_t *pcbRead);

/**
 * Receive pending data from the other end of an local IPC session.
 *
 * This will not block to wait for data.
 *
 * @returns IPRT status code.
 * @retval  VINF_TRY_AGAIN if no pending data (*pcbRead is set to 0).
 * @retval  VERR_CANCELLED if a previous operation was cancelled by
 *          RTLocalIpcSessionCancel (this operation isn't cancellable).
 *
 * @param   hSession            The session handle.
 * @param   pvBuf               Where to store the data.
 * @param   cbToRead            How much to read (upper limit).
 * @param   pcbRead             Where to return exactly how much was read.
 */
RTDECL(int) RTLocalIpcSessionReadNB(RTLOCALIPCSESSION hSession, void *pvBuf, size_t cbToRead, size_t *pcbRead);

/**
 * Send data to the other end of an local IPC session.
 *
 * This may or may not block until the data is received by the other party,
 * this is an implementation detail.  If you want to make sure that the data
 * has been received you should always call RTLocalIpcSessionFlush().
 *
 * @returns IPRT status code.
 * @retval  VERR_CANCELLED if the operation was cancelled by RTLocalIpcSessionCancel.
 *
 * @param   hSession            The session handle.
 * @param   pvBuf               The data to write.
 * @param   cbToWrite           How much to write.
 */
RTDECL(int) RTLocalIpcSessionWrite(RTLOCALIPCSESSION hSession, const void *pvBuf, size_t cbToWrite);

/**
 * Flush any buffered data and (perhaps) wait for the other party to receive it.
 *
 * The waiting for the other party to receive the data is
 * implementation dependent.
 *
 * @returns IPRT status code.
 * @retval  VERR_CANCELLED if the operation was cancelled by RTLocalIpcSessionCancel.
 *
 * @param   hSession            The session handle.
 */
RTDECL(int) RTLocalIpcSessionFlush(RTLOCALIPCSESSION hSession);

/**
 * Wait for data to become ready for reading or for the session to be
 * disconnected.
 *
 * @returns IPRT status code.
 * @retval  VINF_SUCCESS when there is data to read.
 * @retval  VERR_TIMEOUT if no data became available within the specified period (@a cMillies)
 * @retval  VERR_BROKEN_PIPE if the session was disconnected.
 * @retval  VERR_CANCELLED if the operation was cancelled by RTLocalIpcSessionCancel.
 *
 * @param   hSession            The session handle.
 * @param   cMillies            The number of milliseconds to wait. Use RT_INDEFINITE_WAIT
 *                              to wait forever.
 *
 * @remark  VERR_INTERRUPTED will not be returned. If this is desired at some later point
 *          add a RTLocalIpcSessionWaitForDataNoResume() variant like we're using elsewhere.
 */
RTDECL(int) RTLocalIpcSessionWaitForData(RTLOCALIPCSESSION hSession, uint32_t cMillies);

/**
 * Cancells a pending or subsequent operation.
 *
 * Not all methods are cancellable, only those which are specfied
 * returning VERR_CANCELLED.  The others are assumed to not be blocking
 * for ever and ever.  However, the cancel is sticky, so the session must
 * basically be trashed (closed) after calling this method.
 *
 * @returns IPRT status code.
 *
 * @param   hSession            The session handle.
 */
RTDECL(int) RTLocalIpcSessionCancel(RTLOCALIPCSESSION hSession);

/**
 * Query the process ID of the other party.
 *
 * This is an optional feature which may not be implemented, so don't
 * depend on it and check for VERR_NOT_SUPPORTED.
 *
 * @returns IPRT status code.
 * @retval  VINF_SUCCESS and *pProcess on success.
 * @retval  VERR_CANCELLED if the operation was cancelled by RTLocalIpcSessionCancel.
 * @retval  VERR_NOT_SUPPORTED and *pProcess = NIL_RTPROCESS if not supported.
 *
 * @param   hSession            The session handle.
 * @param   pProcess            Where to store the process ID.
 */
RTDECL(int) RTLocalIpcSessionQueryProcess(RTLOCALIPCSESSION hSession, PRTPROCESS pProcess);

/**
 * Query the user ID of the other party.
 *
 * This is an optional feature which may not be implemented, so don't
 * depend on it and check for VERR_NOT_SUPPORTED.
 *
 * @returns IPRT status code.
 * @retval  VINF_SUCCESS and *pUid on success.
 * @retval  VERR_CANCELLED if the operation was cancelled by RTLocalIpcSessionCancel.
 * @retval  VERR_NOT_SUPPORTED and *pUid = NIL_RTUID if not supported.
 *
 * @param   hSession            The session handle.
 * @param   pUid                Where to store the user ID on success.
 */
RTDECL(int) RTLocalIpcSessionQueryUserId(RTLOCALIPCSESSION hSession, PRTUID pUid);

/**
 * Query the group ID of the other party.
 *
 * This is an optional feature which may not be implemented, so don't
 * depend on it and check for VERR_NOT_SUPPORTED.
 *
 * @returns IPRT status code.
 * @retval  VINF_SUCCESS and *pUid on success.
 * @retval  VERR_CANCELLED if the operation was cancelled by RTLocalIpcSessionCancel.
 * @retval  VERR_NOT_SUPPORTED and *pGid = NIL_RTUID if not supported.
 *
 * @param   hSession            The session handle.
 * @param   pGid                Where to store the group ID on success.
 */
RTDECL(int) RTLocalIpcSessionQueryGroupId(RTLOCALIPCSESSION hSession, PRTGID pGid);

/** @} */
RT_C_DECLS_END

#endif /* !IPRT_INCLUDED_localipc_h */