VirtualBox

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

Last change on this file since 58297 was 58297, checked in by vboxsync, 9 years ago

RTLocalIpc: Added flag to the server and connection creation functions to accept native paths (default is a portable name that gets prefixed with platform specific path).

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 11.0 KB
Line 
1/** @file
2 * IPRT - Local IPC Server & Client.
3 */
4
5/*
6 * Copyright (C) 2006-2015 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/** The server can handle multiple sessions. */
78#define RTLOCALIPC_FLAGS_MULTI_SESSION RT_BIT_32(0)
79/** Native name, as apposed to a portable one. */
80#define RTLOCALIPC_FLAGS_NATIVE_NAME RT_BIT_32(1)
81/** The mask of valid flags. */
82#define RTLOCALIPC_FLAGS_VALID_MASK UINT32_C(0x00000003)
83/** @} */
84
85/**
86 * Destroys a local IPC server.
87 *
88 * @returns IPRT status code.
89 * @retval VINF_SUCCESS if still other references or NIL.
90 * @retval VINF_OBJECT_DESTROYED if actually destroyed.
91 *
92 * @param hServer The server handle. The nil value is quietly ignored (VINF_SUCCESS).
93 */
94RTDECL(int) RTLocalIpcServerDestroy(RTLOCALIPCSERVER hServer);
95
96/**
97 * Listen for clients.
98 *
99 * @returns IPRT status code.
100 * @retval VINF_SUCCESS on success and *phClientSession containing the session handle.
101 * @retval VERR_CANCELLED if the listening was interrupted by RTLocalIpcServerCancel().
102 *
103 * @param hServer The server handle.
104 * @param phClientSession Where to store the client session handle on success.
105 *
106 */
107RTDECL(int) RTLocalIpcServerListen(RTLOCALIPCSERVER hServer, PRTLOCALIPCSESSION phClientSession);
108
109/**
110 * Cancel the current or subsequent RTLocalIpcServerListen call.
111 *
112 * @returns IPRT status code.
113 * @param hServer The server handle. The nil value is quietly ignored (VINF_SUCCESS).
114 */
115RTDECL(int) RTLocalIpcServerCancel(RTLOCALIPCSERVER hServer);
116
117
118/**
119 * Connects to a local IPC server.
120 *
121 * This is used a client process (or thread).
122 *
123 * @returns IPRT status code.
124 * @retval VINF_SUCCESS on success and *phSession holding the session handle.
125 *
126 * @param phSession Where to store the sesson handle on success.
127 * @param pszName The server name (see RTLocalIpcServerCreate for details).
128 * @param fFlags Flags, RTLOCALIPC_C_FLAGS_XXX.
129 */
130RTDECL(int) RTLocalIpcSessionConnect(PRTLOCALIPCSESSION phSession, const char *pszName, uint32_t fFlags);
131
132/** @name RTLOCALIPC_C_FLAGS_XXX - RTLocalIpcSessionConnect flags
133 * @{ */
134/** Native name, as apposed to a portable one. */
135#define RTLOCALIPC_C_FLAGS_NATIVE_NAME RT_BIT_32(0)
136/** The mask of valid flags. */
137#define RTLOCALIPC_C_FLAGS_VALID_MASK UINT32_C(0x00000001)
138/** @} */
139
140
141/**
142 * Closes the local IPC session.
143 *
144 * This can be used with sessions created by both RTLocalIpcSessionConnect
145 * and RTLocalIpcServerListen.
146 *
147 * @returns IPRT status code.
148 * @retval VINF_SUCCESS if still other references or NIL.
149 * @retval VINF_OBJECT_DESTROYED if session destroyed.
150 *
151 * @param hSession The session handle. The nil value is quietly ignored (VINF_SUCCESS).
152 */
153RTDECL(int) RTLocalIpcSessionClose(RTLOCALIPCSESSION hSession);
154
155/**
156 * Receive data from the other end of an local IPC session.
157 *
158 * This will block if there isn't any data.
159 *
160 * @returns IPRT status code.
161 * @retval VERR_CANCELLED if the operation was cancelled by RTLocalIpcSessionCancel.
162 *
163 * @param hSession The session handle.
164 * @param pvBuf Where to store the data.
165 * @param cbToRead How much to read. This is exact request if
166 * pcbRead is NULL, otherwise it's an upper limit.
167 * @param pcbRead Optional argument for indicating a partial read
168 * and returning the number of bytes actually read.
169 */
170RTDECL(int) RTLocalIpcSessionRead(RTLOCALIPCSESSION hSession, void *pvBuf, size_t cbToRead, size_t *pcbRead);
171
172/**
173 * Receive pending data from the other end of an local IPC session.
174 *
175 * This will not block to wait for data.
176 *
177 * @returns IPRT status code.
178 * @retval VINF_TRY_AGAIN if no pending data (*pcbRead is set to 0).
179 * @retval VERR_CANCELLED if a previous operation was cancelled by
180 * RTLocalIpcSessionCancel (this operation isn't cancellable).
181 *
182 * @param hSession The session handle.
183 * @param pvBuf Where to store the data.
184 * @param cbToRead How much to read (upper limit).
185 * @param pcbRead Where to return exactly how much was read.
186 */
187RTDECL(int) RTLocalIpcSessionReadNB(RTLOCALIPCSESSION hSession, void *pvBuf, size_t cbToRead, size_t *pcbRead);
188
189/**
190 * Send data to the other end of an local IPC session.
191 *
192 * This may or may not block until the data is received by the other party,
193 * this is an implementation detail. If you want to make sure that the data
194 * has been received you should always call RTLocalIpcSessionFlush().
195 *
196 * @returns IPRT status code.
197 * @retval VERR_CANCELLED if the operation was cancelled by RTLocalIpcSessionCancel.
198 *
199 * @param hSession The session handle.
200 * @param pvBuf The data to write.
201 * @param cbToWrite How much to write.
202 */
203RTDECL(int) RTLocalIpcSessionWrite(RTLOCALIPCSESSION hSession, const void *pvBuf, size_t cbToWrite);
204
205/**
206 * Flush any buffered data and (perhaps) wait for the other party to receive it.
207 *
208 * The waiting for the other party to receive the data is
209 * implementation dependent.
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 */
216RTDECL(int) RTLocalIpcSessionFlush(RTLOCALIPCSESSION hSession);
217
218/**
219 * Wait for data to become ready for reading or for the session to be
220 * disconnected.
221 *
222 * @returns IPRT status code.
223 * @retval VINF_SUCCESS when there is data to read.
224 * @retval VERR_TIMEOUT if no data became available within the specified period (@a cMillies)
225 * @retval VERR_BROKEN_PIPE if the session was disconnected.
226 * @retval VERR_CANCELLED if the operation was cancelled by RTLocalIpcSessionCancel.
227 *
228 * @param hSession The session handle.
229 * @param cMillies The number of milliseconds to wait. Use RT_INDEFINITE_WAIT
230 * to wait forever.
231 *
232 * @remark VERR_INTERRUPTED will not be returned. If this is desired at some later point
233 * add a RTLocalIpcSessionWaitForDataNoResume() variant like we're using elsewhere.
234 */
235RTDECL(int) RTLocalIpcSessionWaitForData(RTLOCALIPCSESSION hSession, uint32_t cMillies);
236
237/**
238 * Cancells a pending or subsequent operation.
239 *
240 * Not all methods are cancellable, only those which are specfied
241 * returning VERR_CANCELLED. The others are assumed to not be blocking
242 * for ever and ever. However, the cancel is sticky, so the session must
243 * basically be trashed (closed) after calling this method.
244 *
245 * @returns IPRT status code.
246 *
247 * @param hSession The session handle.
248 */
249RTDECL(int) RTLocalIpcSessionCancel(RTLOCALIPCSESSION hSession);
250
251/**
252 * Query the process ID of the other party.
253 *
254 * This is an optional feature which may not be implemented, so don't
255 * depend on it and check for VERR_NOT_SUPPORTED.
256 *
257 * @returns IPRT status code.
258 * @retval VINF_SUCCESS and *pProcess on success.
259 * @retval VERR_CANCELLED if the operation was cancelled by RTLocalIpcSessionCancel.
260 * @retval VERR_NOT_SUPPORTED and *pProcess = NIL_RTPROCESS if not supported.
261 *
262 * @param hSession The session handle.
263 * @param pProcess Where to store the process ID.
264 */
265RTDECL(int) RTLocalIpcSessionQueryProcess(RTLOCALIPCSESSION hSession, PRTPROCESS pProcess);
266
267/**
268 * Query the user ID of the other party.
269 *
270 * This is an optional feature which may not be implemented, so don't
271 * depend on it and check for VERR_NOT_SUPPORTED.
272 *
273 * @returns IPRT status code.
274 * @retval VINF_SUCCESS and *pUid on success.
275 * @retval VERR_CANCELLED if the operation was cancelled by RTLocalIpcSessionCancel.
276 * @retval VERR_NOT_SUPPORTED and *pUid = NIL_RTUID if not supported.
277 *
278 * @param hSession The session handle.
279 * @param pUid Where to store the user ID on success.
280 */
281RTDECL(int) RTLocalIpcSessionQueryUserId(RTLOCALIPCSESSION hSession, PRTUID pUid);
282
283/**
284 * Query the group ID of the other party.
285 *
286 * This is an optional feature which may not be implemented, so don't
287 * depend on it and check for VERR_NOT_SUPPORTED.
288 *
289 * @returns IPRT status code.
290 * @retval VINF_SUCCESS and *pUid on success.
291 * @retval VERR_CANCELLED if the operation was cancelled by RTLocalIpcSessionCancel.
292 * @retval VERR_NOT_SUPPORTED and *pGid = NIL_RTUID if not supported.
293 *
294 * @param hSession The session handle.
295 * @param pGid Where to store the group ID on success.
296 */
297RTDECL(int) RTLocalIpcSessionQueryGroupId(RTLOCALIPCSESSION hSession, PRTGID pGid);
298
299/** @} */
300RT_C_DECLS_END
301
302#endif
303
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