VirtualBox

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

Last change on this file since 28615 was 25645, checked in by vboxsync, 15 years ago

IPRT,DoxyFile.Core: Mopped up the errors in the IPRT doxygen run.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 9.9 KB
Line 
1/** @file
2 * IPRT - TCP/IP.
3 */
4
5/*
6 * Copyright (C) 2006-2007 Sun Microsystems, Inc.
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 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
26 * Clara, CA 95054 USA or visit http://www.sun.com if you need
27 * additional information or have any questions.
28 */
29
30#ifndef ___iprt_tcp_h
31#define ___iprt_tcp_h
32
33#include <iprt/cdefs.h>
34#include <iprt/types.h>
35#include <iprt/thread.h>
36
37#ifdef IN_RING0
38# error "There are no RTFile APIs available Ring-0 Host Context!"
39#endif
40
41
42RT_C_DECLS_BEGIN
43
44/** @defgroup grp_rt_localipc RTLocalIpc - Local IPC
45 * @ingroup grp_rt
46 * @{
47 */
48
49/** Handle to a local IPC server instance. */
50typedef struct RTLOCALIPCSERVERINT *RTLOCALIPCSERVER;
51/** Pointer to a local IPC server handle. */
52typedef RTLOCALIPCSERVER *PRTLOCALIPCSERVER;
53/** Local IPC server handle nil value. */
54#define NIL_RTLOCALIPCSERVER ((RTLOCALIPCSERVER)0)
55
56/** Handle to a local ICP session instance. */
57typedef struct RTLOCALIPCSESSIONINT *RTLOCALIPCSESSION;
58/** Pointer to a local ICP session handle. */
59typedef RTLOCALIPCSESSION *PRTLOCALIPCSESSION;
60/** Local ICP session handle nil value. */
61#define NIL_RTLOCALIPCSESSION ((RTLOCALIPCSESSION)0)
62
63
64
65/**
66 * Create a local IPC server.
67 *
68 * @returns IPRT status code.
69 * @retval VINF_SUCCESS on success and *phServer containg the instance handle.
70 *
71 * @param phServer Where to put the server instance handle.
72 * @param pszName The servier name. This must be unique and not
73 * include any special chars or slashes. It will
74 * be morphed into a unique platform specific
75 * identifier.
76 * @param fFlags Flags, see RTLOCALIPC_FLAGS_*.
77 */
78RTDECL(int) RTLocalIpcServerCreate(PRTLOCALIPCSERVER phServer, const char *pszName, uint32_t fFlags);
79
80/** @name RTLocalIpcServerCreate flags
81 * @{ */
82/** The server can handle multiple session. */
83#define RTLOCALIPC_FLAGS_MULTI_SESSION RT_BIT_32(0)
84/** The mask of valid flags. */
85#define RTLOCALIPC_FLAGS_VALID_MASK UINT32_C(0x00000001)
86/** @} */
87
88/**
89 * Destroys a local IPC server.
90 *
91 * @returns IPRT status code.
92 *
93 * @param hServer The server handle. The nil value is quietly ignored (VINF_SUCCESS).
94 */
95RTDECL(int) RTLocalIpcServerDestroy(RTLOCALIPCSERVER hServer);
96
97/**
98 * Listen for clients.
99 *
100 * @returns IPRT status code.
101 * @retval VINF_SUCCESS on success and *phClientSession containing the session handle.
102 * @retval VERR_CANCELLED if the listening was interrupted by RTLocalIpcServerCancel().
103 *
104 * @param hServer The server handle.
105 * @param phClientSession Where to store the client session handle on success.
106 *
107 */
108RTDECL(int) RTLocalIpcServerListen(RTLOCALIPCSERVER hServer, PRTLOCALIPCSESSION phClientSession);
109
110/**
111 * Cancel the current or subsequent RTLocalIpcServerListen call.
112 *
113 * @returns IPRT status code.
114 * @param hServer The server handle. The nil value is quietly ignored (VINF_SUCCESS).
115 */
116RTDECL(int) RTLocalIpcServerCancel(RTLOCALIPCSERVER hServer);
117
118
119/**
120 * Connects to a local IPC server.
121 *
122 * This is used a client process (or thread).
123 *
124 * @returns IPRT status code.
125 * @retval VINF_SUCCESS on success and *phSession holding the session handle.
126 *
127 * @param phSession Where to store the sesson handle on success.
128 * @param pszName The server name (see RTLocalIpcServerCreate for details).
129 * @param fFlags Flags. Current undefined, pass 0.
130 */
131RTDECL(int) RTLocalIpcSessionConnect(PRTLOCALIPCSESSION phSession, const char *pszName, uint32_t fFlags);
132
133
134/**
135 * Closes the local IPC session.
136 *
137 * This can be used with sessions created by both RTLocalIpcSessionConnect
138 * and RTLocalIpcServerListen.
139 *
140 * @returns IPRT status code.
141 *
142 * @param hSession The session handle. The nil value is quietly ignored (VINF_SUCCESS).
143 */
144RTDECL(int) RTLocalIpcSessionClose(RTLOCALIPCSESSION hSession);
145
146/**
147 * Receive data from the other end of an local IPC session.
148 *
149 * This will block if there isn't any data.
150 *
151 * @returns IPRT status code.
152 * @retval VERR_CANCELLED if the operation was cancelled by RTLocalIpcSessionCancel.
153 *
154 * @param hSession The session handle.
155 * @param pvBuffer Where to store the data.
156 * @param cbBuffer If pcbRead is non-NULL this indicates the maximum number of
157 * bytes to read. If pcbRead is NULL the this is the exact number
158 * of bytes to read.
159 * @param pcbRead Optional argument for indicating a partial read and returning
160 * the number of bytes actually read.
161 * This may return 0 on some implementations?
162 */
163RTDECL(int) RTLocalIpcSessionRead(RTLOCALIPCSESSION hSession, void *pvBuffer, size_t cbBuffer, size_t *pcbRead);
164
165/**
166 * Send data to the other end of an local IPC session.
167 *
168 * This may or may not block until the data is received by the other party,
169 * this is an implementation detail. If you want to make sure that the data
170 * has been received you should allways call RTLocalIpcSessionFlush().
171 *
172 * @returns IPRT status code.
173 * @retval VERR_CANCELLED if the operation was cancelled by RTLocalIpcSessionCancel.
174 *
175 * @param hSession The session handle.
176 * @param pvBuffer The data to write.
177 * @param cbBuffer The number of bytes to write.
178 */
179RTDECL(int) RTLocalIpcSessionWrite(RTLOCALIPCSESSION hSession, const void *pvBuffer, size_t cbBuffer);
180
181/**
182 * Flush any buffered data and (perhaps) wait for the other party to receive it.
183 *
184 * The waiting for the other party to receive the data is
185 * implementation dependent.
186 *
187 * @returns IPRT status code.
188 * @retval VERR_CANCELLED if the operation was cancelled by RTLocalIpcSessionCancel.
189 *
190 * @param hSession The session handle.
191 */
192RTDECL(int) RTLocalIpcSessionFlush(RTLOCALIPCSESSION hSession);
193
194/**
195 * Wait for data to become read for reading or for the
196 * session to be disconnected.
197 *
198 * @returns IPRT status code.
199 * @retval VINF_SUCCESS when there is data to read.
200 * @retval VERR_TIMEOUT if no data became available within the specified period (@a cMillies)
201 * @retval VERR_BROKEN_PIPE if the session was disconnected.
202 * @retval VERR_CANCELLED if the operation was cancelled by RTLocalIpcSessionCancel.
203 *
204 * @param hSession The session handle.
205 * @param cMillies The number of milliseconds to wait. Use RT_INDEFINITE_WAIT
206 * to wait forever.
207 *
208 * @remark VERR_INTERRUPTED will not be returned. If this is desired at some later point
209 * add a RTLocalIpcSessionWaitForDataNoResume() variant like we're using elsewhere.
210 */
211RTDECL(int) RTLocalIpcSessionWaitForData(RTLOCALIPCSESSION hSession, uint32_t cMillies);
212
213/**
214 * Cancells a pending or subsequent operation.
215 *
216 * Not all methods are cancellable, only those which are specfied
217 * returning VERR_CANCELLED. The others are assumed to not be blocking
218 * for ever and ever.
219 *
220 * @returns IPRT status code.
221 *
222 * @param hSession The session handle.
223 */
224RTDECL(int) RTLocalIpcSessionCancel(RTLOCALIPCSESSION hSession);
225
226/**
227 * Query the process ID of the other party.
228 *
229 * This is an optional feature which may not be implemented, so don't
230 * depend on it and check for VERR_NOT_SUPPORTED.
231 *
232 * @returns IPRT status code.
233 * @retval VINF_SUCCESS and *pProcess on success.
234 * @retval VERR_CANCELLED if the operation was cancelled by RTLocalIpcSessionCancel.
235 * @retval VERR_NOT_SUPPORTED and *pProcess = NIL_RTPROCESS if not supported.
236 *
237 * @param hSession The session handle.
238 * @param pProcess Where to store the process ID.
239 */
240RTDECL(int) RTLocalIpcSessionQueryProcess(RTLOCALIPCSESSION hSession, PRTPROCESS pProcess);
241
242/**
243 * Query the user ID of the other party.
244 *
245 * This is an optional feature which may not be implemented, so don't
246 * depend on it and check for VERR_NOT_SUPPORTED.
247 *
248 * @returns IPRT status code.
249 * @retval VINF_SUCCESS and *pUid on success.
250 * @retval VERR_CANCELLED if the operation was cancelled by RTLocalIpcSessionCancel.
251 * @retval VERR_NOT_SUPPORTED and *pUid = NIL_RTUID if not supported.
252 *
253 * @param hSession The session handle.
254 * @param pUid Where to store the user ID on success.
255 */
256RTDECL(int) RTLocalIpcSessionQueryUserId(RTLOCALIPCSESSION hSession, PRTUID pUid);
257
258/**
259 * Query the group ID of the other party.
260 *
261 * This is an optional feature which may not be implemented, so don't
262 * depend on it and check for VERR_NOT_SUPPORTED.
263 *
264 * @returns IPRT status code.
265 * @retval VINF_SUCCESS and *pUid on success.
266 * @retval VERR_CANCELLED if the operation was cancelled by RTLocalIpcSessionCancel.
267 * @retval VERR_NOT_SUPPORTED and *pGid = NIL_RTUID if not supported.
268 *
269 * @param hSession The session handle.
270 * @param pGid Where to store the group ID on success.
271 */
272RTDECL(int) RTLocalIpcSessionQueryGroupId(RTLOCALIPCSESSION hSession, PRTGID pGid);
273
274/** @} */
275RT_C_DECLS_END
276
277#endif
278
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