VirtualBox

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

Last change on this file since 66601 was 64291, checked in by vboxsync, 8 years ago

Reverted r111300 and subsequent changes since the fix is to use RTLOCALIPC_FLAGS_NATIVE_NAME.

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