VirtualBox

source: vbox/trunk/include/iprt/localipc.h@ 93941

Last change on this file since 93941 was 93451, checked in by vboxsync, 3 years ago

IPRT: Local IPC Server: add interface to set server socket access mode directly, bugref:10134.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 12.3 KB
Line 
1/** @file
2 * IPRT - Local IPC Server & Client.
3 */
4
5/*
6 * Copyright (C) 2006-2022 Oracle Corporation
7 *
8 * This file is part of VirtualBox Open Source Edition (OSE), as
9 * available from http://www.virtualbox.org. This file is free software;
10 * you can redistribute it and/or modify it under the terms of the GNU
11 * General Public License (GPL) as published by the Free Software
12 * Foundation, in version 2 as it comes in the "COPYING" file of the
13 * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
14 * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
15 *
16 * The contents of this file may alternatively be used under the terms
17 * of the Common Development and Distribution License Version 1.0
18 * (CDDL) only, as it comes in the "COPYING.CDDL" file of the
19 * VirtualBox OSE distribution, in which case the provisions of the
20 * CDDL are applicable instead of those of the GPL.
21 *
22 * You may elect to license modified versions of this file under the
23 * terms and conditions of either the GPL or the CDDL or both.
24 */
25
26#ifndef IPRT_INCLUDED_localipc_h
27#define IPRT_INCLUDED_localipc_h
28#ifndef RT_WITHOUT_PRAGMA_ONCE
29# pragma once
30#endif
31
32#include <iprt/cdefs.h>
33#include <iprt/types.h>
34#include <iprt/thread.h>
35
36#ifdef IN_RING0
37# error "There are no RTLocalIpc APIs available Ring-0 Host Context!"
38#endif
39
40
41RT_C_DECLS_BEGIN
42
43/** @defgroup grp_rt_localipc RTLocalIpc - Local IPC
44 * @ingroup grp_rt
45 * @{
46 */
47
48/** Handle to a local IPC server instance. */
49typedef struct RTLOCALIPCSERVERINT *RTLOCALIPCSERVER;
50/** Pointer to a local IPC server handle. */
51typedef RTLOCALIPCSERVER *PRTLOCALIPCSERVER;
52/** Local IPC server handle nil value. */
53#define NIL_RTLOCALIPCSERVER ((RTLOCALIPCSERVER)0)
54
55/** Handle to a local ICP session instance. */
56typedef struct RTLOCALIPCSESSIONINT *RTLOCALIPCSESSION;
57/** Pointer to a local ICP session handle. */
58typedef RTLOCALIPCSESSION *PRTLOCALIPCSESSION;
59/** Local ICP session handle nil value. */
60#define NIL_RTLOCALIPCSESSION ((RTLOCALIPCSESSION)0)
61
62
63
64/**
65 * Create a local IPC server.
66 *
67 * @returns IPRT status code.
68 * @retval VINF_SUCCESS on success and *phServer containing the instance handle.
69 *
70 * @param phServer Where to put the server instance handle.
71 * @param pszName The server name. This must be unique and not include
72 * any special chars or slashes. It will be morphed into a
73 * unique platform specific identifier.
74 * @param fFlags Flags, see RTLOCALIPC_FLAGS_*.
75 */
76RTDECL(int) RTLocalIpcServerCreate(PRTLOCALIPCSERVER phServer, const char *pszName, uint32_t fFlags);
77
78/** @name RTLocalIpcServerCreate flags
79 * @{ */
80/** Native name, as apposed to a portable one. */
81#define RTLOCALIPC_FLAGS_NATIVE_NAME RT_BIT_32(0)
82/** The mask of valid flags. */
83#define RTLOCALIPC_FLAGS_VALID_MASK UINT32_C(0x00000001)
84/** @} */
85
86/**
87 * Destroys a local IPC server.
88 *
89 * @returns IPRT status code.
90 * @retval VINF_SUCCESS if still other references or NIL.
91 * @retval VINF_OBJECT_DESTROYED if actually destroyed.
92 *
93 * @param hServer The server handle. The nil value is quietly ignored (VINF_SUCCESS).
94 */
95RTDECL(int) RTLocalIpcServerDestroy(RTLOCALIPCSERVER hServer);
96
97/**
98 * Grant the specified group access to the local IPC server socket.
99 *
100 * @returns IPRT status code.
101 * @param hServer The server handle.
102 * @param gid Group ID.
103 */
104RTDECL(int) RTLocalIpcServerGrantGroupAccess(RTLOCALIPCSERVER hServer, RTGID gid);
105
106/**
107 * Set access mode for IPC server socket.
108 *
109 * @returns IPRT status code.
110 * @param hServer The server handle.
111 * @param fMode Access mode.
112 */
113RTDECL(int) RTLocalIpcServerSetAccessMode(RTLOCALIPCSERVER hServer, RTFMODE fMode);
114
115/**
116 * Listen for clients.
117 *
118 * @returns IPRT status code.
119 * @retval VINF_SUCCESS on success and *phClientSession containing the session handle.
120 * @retval VERR_CANCELLED if the listening was interrupted by RTLocalIpcServerCancel().
121 *
122 * @param hServer The server handle.
123 * @param phClientSession Where to store the client session handle on success.
124 *
125 */
126RTDECL(int) RTLocalIpcServerListen(RTLOCALIPCSERVER hServer, PRTLOCALIPCSESSION phClientSession);
127
128/**
129 * Cancel the current or subsequent RTLocalIpcServerListen call.
130 *
131 * @returns IPRT status code.
132 * @param hServer The server handle. The nil value is quietly ignored (VINF_SUCCESS).
133 */
134RTDECL(int) RTLocalIpcServerCancel(RTLOCALIPCSERVER hServer);
135
136
137/**
138 * Connects to a local IPC server.
139 *
140 * This is used a client process (or thread).
141 *
142 * @returns IPRT status code.
143 * @retval VINF_SUCCESS on success and *phSession holding the session handle.
144 *
145 * @param phSession Where to store the sesson handle on success.
146 * @param pszName The server name (see RTLocalIpcServerCreate for details).
147 * @param fFlags Flags, RTLOCALIPC_C_FLAGS_XXX.
148 */
149RTDECL(int) RTLocalIpcSessionConnect(PRTLOCALIPCSESSION phSession, const char *pszName, uint32_t fFlags);
150
151/** @name RTLOCALIPC_C_FLAGS_XXX - RTLocalIpcSessionConnect flags
152 * @{ */
153/** Native name, as apposed to a portable one. */
154#define RTLOCALIPC_C_FLAGS_NATIVE_NAME RT_BIT_32(0)
155/** The mask of valid flags. */
156#define RTLOCALIPC_C_FLAGS_VALID_MASK UINT32_C(0x00000001)
157/** @} */
158
159/**
160 * Closes the local IPC session.
161 *
162 * This can be used with sessions created by both RTLocalIpcSessionConnect
163 * and RTLocalIpcServerListen. It will release one cancel pending I/O and
164 * relase one reference (typically the implict reference from the create API).
165 *
166 * @returns IPRT status code.
167 * @retval VINF_SUCCESS if still other references or NIL.
168 * @retval VINF_OBJECT_DESTROYED if session destroyed.
169 *
170 * @param hSession The session handle. The nil value is quietly ignored (VINF_SUCCESS).
171 */
172RTDECL(int) RTLocalIpcSessionClose(RTLOCALIPCSESSION hSession);
173
174/**
175 * Retain a refence to the given session.
176 *
177 * @returns New reference count, UINT32_MAX if the handle is invalid.
178 * @param hSession The session handle.
179 */
180RTDECL(uint32_t) RTLocalIpcSessionRetain(RTLOCALIPCSESSION hSession);
181
182/**
183 * Releases a refence to the given session.
184 *
185 * This differs from RTLocalIpcSessionClose in that it won't cancel any pending
186 * I/O. So, better call RTLocalIpcSessionClose if you want to terminate the
187 * session.
188 *
189 * @returns New reference count, 0 if NIL handle, UINT32_MAX if the handle is
190 * invalid.
191 * @param hSession The session handle.
192 */
193RTDECL(uint32_t) RTLocalIpcSessionRelease(RTLOCALIPCSESSION hSession);
194
195
196/**
197 * Receive data from the other end of an local IPC session.
198 *
199 * This will block if there isn't any data.
200 *
201 * @returns IPRT status code.
202 * @retval VERR_CANCELLED if the operation was cancelled by RTLocalIpcSessionCancel.
203 *
204 * @param hSession The session handle.
205 * @param pvBuf Where to store the data.
206 * @param cbToRead How much to read. This is exact request if
207 * pcbRead is NULL, otherwise it's an upper limit.
208 * @param pcbRead Optional argument for indicating a partial read
209 * and returning the number of bytes actually read.
210 */
211RTDECL(int) RTLocalIpcSessionRead(RTLOCALIPCSESSION hSession, void *pvBuf, size_t cbToRead, size_t *pcbRead);
212
213/**
214 * Receive pending data from the other end of an local IPC session.
215 *
216 * This will not block to wait for data.
217 *
218 * @returns IPRT status code.
219 * @retval VINF_TRY_AGAIN if no pending data (*pcbRead is set to 0).
220 * @retval VERR_CANCELLED if a previous operation was cancelled by
221 * RTLocalIpcSessionCancel (this operation isn't cancellable).
222 *
223 * @param hSession The session handle.
224 * @param pvBuf Where to store the data.
225 * @param cbToRead How much to read (upper limit).
226 * @param pcbRead Where to return exactly how much was read.
227 */
228RTDECL(int) RTLocalIpcSessionReadNB(RTLOCALIPCSESSION hSession, void *pvBuf, size_t cbToRead, size_t *pcbRead);
229
230/**
231 * Send data to the other end of an local IPC session.
232 *
233 * This may or may not block until the data is received by the other party,
234 * this is an implementation detail. If you want to make sure that the data
235 * has been received you should always call RTLocalIpcSessionFlush().
236 *
237 * @returns IPRT status code.
238 * @retval VERR_CANCELLED if the operation was cancelled by RTLocalIpcSessionCancel.
239 *
240 * @param hSession The session handle.
241 * @param pvBuf The data to write.
242 * @param cbToWrite How much to write.
243 */
244RTDECL(int) RTLocalIpcSessionWrite(RTLOCALIPCSESSION hSession, const void *pvBuf, size_t cbToWrite);
245
246/**
247 * Flush any buffered data and (perhaps) wait for the other party to receive it.
248 *
249 * The waiting for the other party to receive the data is
250 * implementation dependent.
251 *
252 * @returns IPRT status code.
253 * @retval VERR_CANCELLED if the operation was cancelled by RTLocalIpcSessionCancel.
254 *
255 * @param hSession The session handle.
256 */
257RTDECL(int) RTLocalIpcSessionFlush(RTLOCALIPCSESSION hSession);
258
259/**
260 * Wait for data to become ready for reading or for the session to be
261 * disconnected.
262 *
263 * @returns IPRT status code.
264 * @retval VINF_SUCCESS when there is data to read.
265 * @retval VERR_TIMEOUT if no data became available within the specified period (@a cMillies)
266 * @retval VERR_BROKEN_PIPE if the session was disconnected.
267 * @retval VERR_CANCELLED if the operation was cancelled by RTLocalIpcSessionCancel.
268 *
269 * @param hSession The session handle.
270 * @param cMillies The number of milliseconds to wait. Use RT_INDEFINITE_WAIT
271 * to wait forever.
272 *
273 * @remark VERR_INTERRUPTED will not be returned. If this is desired at some later point
274 * add a RTLocalIpcSessionWaitForDataNoResume() variant like we're using elsewhere.
275 */
276RTDECL(int) RTLocalIpcSessionWaitForData(RTLOCALIPCSESSION hSession, uint32_t cMillies);
277
278/**
279 * Cancells a pending or subsequent operation.
280 *
281 * Not all methods are cancellable, only those which are specfied
282 * returning VERR_CANCELLED. The others are assumed to not be blocking
283 * for ever and ever. However, the cancel is sticky, so the session must
284 * basically be trashed (closed) after calling this method.
285 *
286 * @returns IPRT status code.
287 *
288 * @param hSession The session handle.
289 */
290RTDECL(int) RTLocalIpcSessionCancel(RTLOCALIPCSESSION hSession);
291
292/**
293 * Query the process ID of the other party.
294 *
295 * This is an optional feature which may not be implemented, so don't
296 * depend on it and check for VERR_NOT_SUPPORTED.
297 *
298 * @returns IPRT status code.
299 * @retval VINF_SUCCESS and *pProcess on success.
300 * @retval VERR_CANCELLED if the operation was cancelled by RTLocalIpcSessionCancel.
301 * @retval VERR_NOT_SUPPORTED and *pProcess = NIL_RTPROCESS if not supported.
302 *
303 * @param hSession The session handle.
304 * @param pProcess Where to store the process ID.
305 */
306RTDECL(int) RTLocalIpcSessionQueryProcess(RTLOCALIPCSESSION hSession, PRTPROCESS pProcess);
307
308/**
309 * Query the user ID of the other party.
310 *
311 * This is an optional feature which may not be implemented, so don't
312 * depend on it and check for VERR_NOT_SUPPORTED.
313 *
314 * @returns IPRT status code.
315 * @retval VINF_SUCCESS and *pUid on success.
316 * @retval VERR_CANCELLED if the operation was cancelled by RTLocalIpcSessionCancel.
317 * @retval VERR_NOT_SUPPORTED and *pUid = NIL_RTUID if not supported.
318 *
319 * @param hSession The session handle.
320 * @param pUid Where to store the user ID on success.
321 */
322RTDECL(int) RTLocalIpcSessionQueryUserId(RTLOCALIPCSESSION hSession, PRTUID pUid);
323
324/**
325 * Query the group ID of the other party.
326 *
327 * This is an optional feature which may not be implemented, so don't
328 * depend on it and check for VERR_NOT_SUPPORTED.
329 *
330 * @returns IPRT status code.
331 * @retval VINF_SUCCESS and *pUid on success.
332 * @retval VERR_CANCELLED if the operation was cancelled by RTLocalIpcSessionCancel.
333 * @retval VERR_NOT_SUPPORTED and *pGid = NIL_RTUID if not supported.
334 *
335 * @param hSession The session handle.
336 * @param pGid Where to store the group ID on success.
337 */
338RTDECL(int) RTLocalIpcSessionQueryGroupId(RTLOCALIPCSESSION hSession, PRTGID pGid);
339
340/** @} */
341RT_C_DECLS_END
342
343#endif /* !IPRT_INCLUDED_localipc_h */
344
Note: See TracBrowser for help on using the repository browser.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette