localipc.h revision d0bfeda1ec3b09006e066521c5ed15207decee8f
0ba2cbe97e0678a691742f98d2532caed0a2c4aaxc * IPRT - TCP/IP.
0ba2cbe97e0678a691742f98d2532caed0a2c4aaxc * Copyright (C) 2006-2013 Oracle Corporation
0ba2cbe97e0678a691742f98d2532caed0a2c4aaxc * This file is part of VirtualBox Open Source Edition (OSE), as
0ba2cbe97e0678a691742f98d2532caed0a2c4aaxc * available from http://www.virtualbox.org. This file is free software;
0ba2cbe97e0678a691742f98d2532caed0a2c4aaxc * you can redistribute it and/or modify it under the terms of the GNU
0ba2cbe97e0678a691742f98d2532caed0a2c4aaxc * General Public License (GPL) as published by the Free Software
0ba2cbe97e0678a691742f98d2532caed0a2c4aaxc * Foundation, in version 2 as it comes in the "COPYING" file of the
0ba2cbe97e0678a691742f98d2532caed0a2c4aaxc * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
0ba2cbe97e0678a691742f98d2532caed0a2c4aaxc * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
0ba2cbe97e0678a691742f98d2532caed0a2c4aaxc * The contents of this file may alternatively be used under the terms
0ba2cbe97e0678a691742f98d2532caed0a2c4aaxc * of the Common Development and Distribution License Version 1.0
0ba2cbe97e0678a691742f98d2532caed0a2c4aaxc * (CDDL) only, as it comes in the "COPYING.CDDL" file of the
0ba2cbe97e0678a691742f98d2532caed0a2c4aaxc * VirtualBox OSE distribution, in which case the provisions of the
0ba2cbe97e0678a691742f98d2532caed0a2c4aaxc * CDDL are applicable instead of those of the GPL.
e2cf88ac9d753a00c17aa235f6afdc76574fe3a6Quaker Fang * You may elect to license modified versions of this file under the
0ba2cbe97e0678a691742f98d2532caed0a2c4aaxc * terms and conditions of either the GPL or the CDDL or both.
0ba2cbe97e0678a691742f98d2532caed0a2c4aaxc# error "There are no RTFile APIs available Ring-0 Host Context!"
0ba2cbe97e0678a691742f98d2532caed0a2c4aaxc/** @defgroup grp_rt_localipc RTLocalIpc - Local IPC
0ba2cbe97e0678a691742f98d2532caed0a2c4aaxc * @ingroup grp_rt
0ba2cbe97e0678a691742f98d2532caed0a2c4aaxc/** Handle to a local IPC server instance. */
0ba2cbe97e0678a691742f98d2532caed0a2c4aaxc/** Pointer to a local IPC server handle. */
0ba2cbe97e0678a691742f98d2532caed0a2c4aaxc/** Local IPC server handle nil value. */
0ba2cbe97e0678a691742f98d2532caed0a2c4aaxc/** Handle to a local ICP session instance. */
0ba2cbe97e0678a691742f98d2532caed0a2c4aaxc/** Pointer to a local ICP session handle. */
0ba2cbe97e0678a691742f98d2532caed0a2c4aaxc/** Local ICP session handle nil value. */
0ba2cbe97e0678a691742f98d2532caed0a2c4aaxc * Create a local IPC server.
0ba2cbe97e0678a691742f98d2532caed0a2c4aaxc * @returns IPRT status code.
e2cf88ac9d753a00c17aa235f6afdc76574fe3a6Quaker Fang * @retval VINF_SUCCESS on success and *phServer containing the instance handle.
0ba2cbe97e0678a691742f98d2532caed0a2c4aaxc * @param phServer Where to put the server instance handle.
0ba2cbe97e0678a691742f98d2532caed0a2c4aaxc * @param pszName The servier name. This must be unique and not
0ba2cbe97e0678a691742f98d2532caed0a2c4aaxc * include any special chars or slashes. It will
0ba2cbe97e0678a691742f98d2532caed0a2c4aaxc * be morphed into a unique platform specific
0ba2cbe97e0678a691742f98d2532caed0a2c4aaxc * identifier.
0ba2cbe97e0678a691742f98d2532caed0a2c4aaxc * @param fFlags Flags, see RTLOCALIPC_FLAGS_*.
0ba2cbe97e0678a691742f98d2532caed0a2c4aaxcRTDECL(int) RTLocalIpcServerCreate(PRTLOCALIPCSERVER phServer, const char *pszName, uint32_t fFlags);
0ba2cbe97e0678a691742f98d2532caed0a2c4aaxc/** @name RTLocalIpcServerCreate flags
0ba2cbe97e0678a691742f98d2532caed0a2c4aaxc/** The server can handle multiple sessions. */
0ba2cbe97e0678a691742f98d2532caed0a2c4aaxc/** The mask of valid flags. */
0ba2cbe97e0678a691742f98d2532caed0a2c4aaxc * Destroys a local IPC server.
0ba2cbe97e0678a691742f98d2532caed0a2c4aaxc * @returns IPRT status code.
0ba2cbe97e0678a691742f98d2532caed0a2c4aaxc * @param hServer The server handle. The nil value is quietly ignored (VINF_SUCCESS).
0ba2cbe97e0678a691742f98d2532caed0a2c4aaxcRTDECL(int) RTLocalIpcServerDestroy(RTLOCALIPCSERVER hServer);
0ba2cbe97e0678a691742f98d2532caed0a2c4aaxc * Listen for clients.
0ba2cbe97e0678a691742f98d2532caed0a2c4aaxc * @returns IPRT status code.
0ba2cbe97e0678a691742f98d2532caed0a2c4aaxc * @retval VINF_SUCCESS on success and *phClientSession containing the session handle.
0ba2cbe97e0678a691742f98d2532caed0a2c4aaxc * @retval VERR_CANCELLED if the listening was interrupted by RTLocalIpcServerCancel().
0ba2cbe97e0678a691742f98d2532caed0a2c4aaxc * @param hServer The server handle.
0ba2cbe97e0678a691742f98d2532caed0a2c4aaxc * @param phClientSession Where to store the client session handle on success.
0ba2cbe97e0678a691742f98d2532caed0a2c4aaxcRTDECL(int) RTLocalIpcServerListen(RTLOCALIPCSERVER hServer, PRTLOCALIPCSESSION phClientSession);
0ba2cbe97e0678a691742f98d2532caed0a2c4aaxc * Cancel the current or subsequent RTLocalIpcServerListen call.
0ba2cbe97e0678a691742f98d2532caed0a2c4aaxc * @returns IPRT status code.
0ba2cbe97e0678a691742f98d2532caed0a2c4aaxc * @param hServer The server handle. The nil value is quietly ignored (VINF_SUCCESS).
0ba2cbe97e0678a691742f98d2532caed0a2c4aaxcRTDECL(int) RTLocalIpcServerCancel(RTLOCALIPCSERVER hServer);
0ba2cbe97e0678a691742f98d2532caed0a2c4aaxc * Connects to a local IPC server.
0ba2cbe97e0678a691742f98d2532caed0a2c4aaxc * This is used a client process (or thread).
0ba2cbe97e0678a691742f98d2532caed0a2c4aaxc * @returns IPRT status code.
0ba2cbe97e0678a691742f98d2532caed0a2c4aaxc * @retval VINF_SUCCESS on success and *phSession holding the session handle.
0ba2cbe97e0678a691742f98d2532caed0a2c4aaxc * @param phSession Where to store the sesson handle on success.
0ba2cbe97e0678a691742f98d2532caed0a2c4aaxc * @param pszName The server name (see RTLocalIpcServerCreate for details).
0ba2cbe97e0678a691742f98d2532caed0a2c4aaxc * @param fFlags Flags. Current undefined, pass 0.
0ba2cbe97e0678a691742f98d2532caed0a2c4aaxcRTDECL(int) RTLocalIpcSessionConnect(PRTLOCALIPCSESSION phSession, const char *pszName, uint32_t fFlags);
0ba2cbe97e0678a691742f98d2532caed0a2c4aaxc * Closes the local IPC session.
0ba2cbe97e0678a691742f98d2532caed0a2c4aaxc * This can be used with sessions created by both RTLocalIpcSessionConnect
0ba2cbe97e0678a691742f98d2532caed0a2c4aaxc * and RTLocalIpcServerListen.
0ba2cbe97e0678a691742f98d2532caed0a2c4aaxc * @returns IPRT status code.
0ba2cbe97e0678a691742f98d2532caed0a2c4aaxc * @param hSession The session handle. The nil value is quietly ignored (VINF_SUCCESS).
0ba2cbe97e0678a691742f98d2532caed0a2c4aaxcRTDECL(int) RTLocalIpcSessionClose(RTLOCALIPCSESSION hSession);
0ba2cbe97e0678a691742f98d2532caed0a2c4aaxc * Receive data from the other end of an local IPC session.
0ba2cbe97e0678a691742f98d2532caed0a2c4aaxc * This will block if there isn't any data.
0ba2cbe97e0678a691742f98d2532caed0a2c4aaxc * @returns IPRT status code.
0ba2cbe97e0678a691742f98d2532caed0a2c4aaxc * @retval VERR_CANCELLED if the operation was cancelled by RTLocalIpcSessionCancel.
0ba2cbe97e0678a691742f98d2532caed0a2c4aaxc * @param hSession The session handle.
0ba2cbe97e0678a691742f98d2532caed0a2c4aaxc * @param pvBuffer Where to store the data.
0ba2cbe97e0678a691742f98d2532caed0a2c4aaxc * @param cbBuffer If pcbRead is non-NULL this indicates the maximum number of
0ba2cbe97e0678a691742f98d2532caed0a2c4aaxc * bytes to read. If pcbRead is NULL then this is the exact number
0ba2cbe97e0678a691742f98d2532caed0a2c4aaxc * of bytes to read.
0ba2cbe97e0678a691742f98d2532caed0a2c4aaxc * @param pcbRead Optional argument for indicating a partial read and returning
0ba2cbe97e0678a691742f98d2532caed0a2c4aaxc * the number of bytes actually read.
0ba2cbe97e0678a691742f98d2532caed0a2c4aaxc * This may return 0 on some implementations?
0ba2cbe97e0678a691742f98d2532caed0a2c4aaxcRTDECL(int) RTLocalIpcSessionRead(RTLOCALIPCSESSION hSession, void *pvBuffer, size_t cbBuffer, size_t *pcbRead);
0ba2cbe97e0678a691742f98d2532caed0a2c4aaxc * Send data to the other end of an local IPC session.
0ba2cbe97e0678a691742f98d2532caed0a2c4aaxc * This may or may not block until the data is received by the other party,
0ba2cbe97e0678a691742f98d2532caed0a2c4aaxc * this is an implementation detail. If you want to make sure that the data
0ba2cbe97e0678a691742f98d2532caed0a2c4aaxc * has been received you should always call RTLocalIpcSessionFlush().
0ba2cbe97e0678a691742f98d2532caed0a2c4aaxc * @returns IPRT status code.
0ba2cbe97e0678a691742f98d2532caed0a2c4aaxc * @retval VERR_CANCELLED if the operation was cancelled by RTLocalIpcSessionCancel.
0ba2cbe97e0678a691742f98d2532caed0a2c4aaxc * @param hSession The session handle.
0ba2cbe97e0678a691742f98d2532caed0a2c4aaxc * @param pvBuffer The data to write.
0ba2cbe97e0678a691742f98d2532caed0a2c4aaxc * @param cbBuffer The number of bytes to write.
0ba2cbe97e0678a691742f98d2532caed0a2c4aaxcRTDECL(int) RTLocalIpcSessionWrite(RTLOCALIPCSESSION hSession, const void *pvBuffer, size_t cbBuffer);
0ba2cbe97e0678a691742f98d2532caed0a2c4aaxc * Flush any buffered data and (perhaps) wait for the other party to receive it.
0ba2cbe97e0678a691742f98d2532caed0a2c4aaxc * The waiting for the other party to receive the data is
0ba2cbe97e0678a691742f98d2532caed0a2c4aaxc * implementation dependent.
0ba2cbe97e0678a691742f98d2532caed0a2c4aaxc * @returns IPRT status code.
0ba2cbe97e0678a691742f98d2532caed0a2c4aaxc * @retval VERR_CANCELLED if the operation was cancelled by RTLocalIpcSessionCancel.
0ba2cbe97e0678a691742f98d2532caed0a2c4aaxc * @param hSession The session handle.
0ba2cbe97e0678a691742f98d2532caed0a2c4aaxcRTDECL(int) RTLocalIpcSessionFlush(RTLOCALIPCSESSION hSession);
0ba2cbe97e0678a691742f98d2532caed0a2c4aaxc * Wait for data to become ready for reading or for the
0ba2cbe97e0678a691742f98d2532caed0a2c4aaxc * session to be disconnected.
0ba2cbe97e0678a691742f98d2532caed0a2c4aaxc * @returns IPRT status code.
0ba2cbe97e0678a691742f98d2532caed0a2c4aaxc * @retval VINF_SUCCESS when there is data to read.
0ba2cbe97e0678a691742f98d2532caed0a2c4aaxc * @retval VERR_TIMEOUT if no data became available within the specified period (@a cMillies)
0ba2cbe97e0678a691742f98d2532caed0a2c4aaxc * @retval VERR_BROKEN_PIPE if the session was disconnected.
0ba2cbe97e0678a691742f98d2532caed0a2c4aaxc * @retval VERR_CANCELLED if the operation was cancelled by RTLocalIpcSessionCancel.
0ba2cbe97e0678a691742f98d2532caed0a2c4aaxc * @param hSession The session handle.
0ba2cbe97e0678a691742f98d2532caed0a2c4aaxc * @param cMillies The number of milliseconds to wait. Use RT_INDEFINITE_WAIT
0ba2cbe97e0678a691742f98d2532caed0a2c4aaxc * to wait forever.
0ba2cbe97e0678a691742f98d2532caed0a2c4aaxc * @remark VERR_INTERRUPTED will not be returned. If this is desired at some later point
0ba2cbe97e0678a691742f98d2532caed0a2c4aaxc * add a RTLocalIpcSessionWaitForDataNoResume() variant like we're using elsewhere.
0ba2cbe97e0678a691742f98d2532caed0a2c4aaxcRTDECL(int) RTLocalIpcSessionWaitForData(RTLOCALIPCSESSION hSession, uint32_t cMillies);
0ba2cbe97e0678a691742f98d2532caed0a2c4aaxc * Cancells a pending or subsequent operation.
0ba2cbe97e0678a691742f98d2532caed0a2c4aaxc * Not all methods are cancellable, only those which are specfied
0ba2cbe97e0678a691742f98d2532caed0a2c4aaxc * returning VERR_CANCELLED. The others are assumed to not be blocking
0ba2cbe97e0678a691742f98d2532caed0a2c4aaxc * for ever and ever.
0ba2cbe97e0678a691742f98d2532caed0a2c4aaxc * @returns IPRT status code.
0ba2cbe97e0678a691742f98d2532caed0a2c4aaxc * @param hSession The session handle.
0ba2cbe97e0678a691742f98d2532caed0a2c4aaxcRTDECL(int) RTLocalIpcSessionCancel(RTLOCALIPCSESSION hSession);
0ba2cbe97e0678a691742f98d2532caed0a2c4aaxc * Query the process ID of the other party.
0ba2cbe97e0678a691742f98d2532caed0a2c4aaxc * This is an optional feature which may not be implemented, so don't
0ba2cbe97e0678a691742f98d2532caed0a2c4aaxc * depend on it and check for VERR_NOT_SUPPORTED.
0ba2cbe97e0678a691742f98d2532caed0a2c4aaxc * @returns IPRT status code.
0ba2cbe97e0678a691742f98d2532caed0a2c4aaxc * @retval VINF_SUCCESS and *pProcess on success.
e2cf88ac9d753a00c17aa235f6afdc76574fe3a6Quaker Fang * @retval VERR_CANCELLED if the operation was cancelled by RTLocalIpcSessionCancel.
e2cf88ac9d753a00c17aa235f6afdc76574fe3a6Quaker Fang * @retval VERR_NOT_SUPPORTED and *pProcess = NIL_RTPROCESS if not supported.
e2cf88ac9d753a00c17aa235f6afdc76574fe3a6Quaker Fang * @param hSession The session handle.
e2cf88ac9d753a00c17aa235f6afdc76574fe3a6Quaker Fang * @param pProcess Where to store the process ID.
e2cf88ac9d753a00c17aa235f6afdc76574fe3a6Quaker FangRTDECL(int) RTLocalIpcSessionQueryProcess(RTLOCALIPCSESSION hSession, PRTPROCESS pProcess);
a399b7655a1d835aa8606c2b29e4e777baac8635zf * Query the user ID of the other party.
a399b7655a1d835aa8606c2b29e4e777baac8635zf * This is an optional feature which may not be implemented, so don't
0ba2cbe97e0678a691742f98d2532caed0a2c4aaxc * depend on it and check for VERR_NOT_SUPPORTED.
0ba2cbe97e0678a691742f98d2532caed0a2c4aaxc * @returns IPRT status code.
0ba2cbe97e0678a691742f98d2532caed0a2c4aaxc * @retval VINF_SUCCESS and *pUid on success.
0ba2cbe97e0678a691742f98d2532caed0a2c4aaxc * @retval VERR_CANCELLED if the operation was cancelled by RTLocalIpcSessionCancel.
0ba2cbe97e0678a691742f98d2532caed0a2c4aaxc * @retval VERR_NOT_SUPPORTED and *pUid = NIL_RTUID if not supported.
a399b7655a1d835aa8606c2b29e4e777baac8635zf * @param hSession The session handle.
a399b7655a1d835aa8606c2b29e4e777baac8635zf * @param pUid Where to store the user ID on success.
a399b7655a1d835aa8606c2b29e4e777baac8635zfRTDECL(int) RTLocalIpcSessionQueryUserId(RTLOCALIPCSESSION hSession, PRTUID pUid);
a399b7655a1d835aa8606c2b29e4e777baac8635zf * Query the group ID of the other party.
a399b7655a1d835aa8606c2b29e4e777baac8635zf * This is an optional feature which may not be implemented, so don't
a399b7655a1d835aa8606c2b29e4e777baac8635zf * depend on it and check for VERR_NOT_SUPPORTED.
0ba2cbe97e0678a691742f98d2532caed0a2c4aaxc * @returns IPRT status code.
0ba2cbe97e0678a691742f98d2532caed0a2c4aaxc * @retval VINF_SUCCESS and *pUid on success.
0ba2cbe97e0678a691742f98d2532caed0a2c4aaxc * @retval VERR_CANCELLED if the operation was cancelled by RTLocalIpcSessionCancel.
0ba2cbe97e0678a691742f98d2532caed0a2c4aaxc * @retval VERR_NOT_SUPPORTED and *pGid = NIL_RTUID if not supported.
0ba2cbe97e0678a691742f98d2532caed0a2c4aaxc * @param hSession The session handle.
0ba2cbe97e0678a691742f98d2532caed0a2c4aaxc * @param pGid Where to store the group ID on success.