VirtualBox

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

Last change on this file since 103224 was 98103, checked in by vboxsync, 21 months ago

Copyright year updates by scm.

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