354 lines
13 KiB
C
354 lines
13 KiB
C
/** @file
|
|
* IPRT - Local IPC Server & Client.
|
|
*/
|
|
|
|
/*
|
|
* Copyright (C) 2006-2023 Oracle and/or its affiliates.
|
|
*
|
|
* This file is part of VirtualBox base platform packages, as
|
|
* available from https://www.virtualbox.org.
|
|
*
|
|
* This program is free software; you can redistribute it and/or
|
|
* modify it under the terms of the GNU General Public License
|
|
* as published by the Free Software Foundation, in version 3 of the
|
|
* License.
|
|
*
|
|
* This program is distributed in the hope that it will be useful, but
|
|
* WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
|
|
* General Public License for more details.
|
|
*
|
|
* You should have received a copy of the GNU General Public License
|
|
* along with this program; if not, see <https://www.gnu.org/licenses>.
|
|
*
|
|
* The contents of this file may alternatively be used under the terms
|
|
* of the Common Development and Distribution License Version 1.0
|
|
* (CDDL), a copy of it is provided in the "COPYING.CDDL" file included
|
|
* in the VirtualBox distribution, in which case the provisions of the
|
|
* CDDL are applicable instead of those of the GPL.
|
|
*
|
|
* You may elect to license modified versions of this file under the
|
|
* terms and conditions of either the GPL or the CDDL or both.
|
|
*
|
|
* SPDX-License-Identifier: GPL-3.0-only OR CDDL-1.0
|
|
*/
|
|
|
|
#ifndef IPRT_INCLUDED_localipc_h
|
|
#define IPRT_INCLUDED_localipc_h
|
|
#ifndef RT_WITHOUT_PRAGMA_ONCE
|
|
# pragma once
|
|
#endif
|
|
|
|
#include <iprt/cdefs.h>
|
|
#include <iprt/types.h>
|
|
#include <iprt/thread.h>
|
|
|
|
#ifdef IN_RING0
|
|
# error "There are no RTLocalIpc APIs available Ring-0 Host Context!"
|
|
#endif
|
|
|
|
|
|
RT_C_DECLS_BEGIN
|
|
|
|
/** @defgroup grp_rt_localipc RTLocalIpc - Local IPC
|
|
* @ingroup grp_rt
|
|
* @{
|
|
*/
|
|
|
|
/** Handle to a local IPC server instance. */
|
|
typedef struct RTLOCALIPCSERVERINT *RTLOCALIPCSERVER;
|
|
/** Pointer to a local IPC server handle. */
|
|
typedef RTLOCALIPCSERVER *PRTLOCALIPCSERVER;
|
|
/** Local IPC server handle nil value. */
|
|
#define NIL_RTLOCALIPCSERVER ((RTLOCALIPCSERVER)0)
|
|
|
|
/** Handle to a local ICP session instance. */
|
|
typedef struct RTLOCALIPCSESSIONINT *RTLOCALIPCSESSION;
|
|
/** Pointer to a local ICP session handle. */
|
|
typedef RTLOCALIPCSESSION *PRTLOCALIPCSESSION;
|
|
/** Local ICP session handle nil value. */
|
|
#define NIL_RTLOCALIPCSESSION ((RTLOCALIPCSESSION)0)
|
|
|
|
|
|
|
|
/**
|
|
* Create a local IPC server.
|
|
*
|
|
* @returns IPRT status code.
|
|
* @retval VINF_SUCCESS on success and *phServer containing the instance handle.
|
|
*
|
|
* @param phServer Where to put the server instance handle.
|
|
* @param pszName The server name. This must be unique and not include
|
|
* any special chars or slashes. It will be morphed into a
|
|
* unique platform specific identifier.
|
|
* @param fFlags Flags, see RTLOCALIPC_FLAGS_*.
|
|
*/
|
|
RTDECL(int) RTLocalIpcServerCreate(PRTLOCALIPCSERVER phServer, const char *pszName, uint32_t fFlags);
|
|
|
|
/** @name RTLocalIpcServerCreate flags
|
|
* @{ */
|
|
/** Native name, as apposed to a portable one. */
|
|
#define RTLOCALIPC_FLAGS_NATIVE_NAME RT_BIT_32(0)
|
|
/** The mask of valid flags. */
|
|
#define RTLOCALIPC_FLAGS_VALID_MASK UINT32_C(0x00000001)
|
|
/** @} */
|
|
|
|
/**
|
|
* Destroys a local IPC server.
|
|
*
|
|
* @returns IPRT status code.
|
|
* @retval VINF_SUCCESS if still other references or NIL.
|
|
* @retval VINF_OBJECT_DESTROYED if actually destroyed.
|
|
*
|
|
* @param hServer The server handle. The nil value is quietly ignored (VINF_SUCCESS).
|
|
*/
|
|
RTDECL(int) RTLocalIpcServerDestroy(RTLOCALIPCSERVER hServer);
|
|
|
|
/**
|
|
* Grant the specified group access to the local IPC server socket.
|
|
*
|
|
* @returns IPRT status code.
|
|
* @param hServer The server handle.
|
|
* @param gid Group ID.
|
|
*/
|
|
RTDECL(int) RTLocalIpcServerGrantGroupAccess(RTLOCALIPCSERVER hServer, RTGID gid);
|
|
|
|
/**
|
|
* Set access mode for IPC server socket.
|
|
*
|
|
* @returns IPRT status code.
|
|
* @param hServer The server handle.
|
|
* @param fMode Access mode.
|
|
*/
|
|
RTDECL(int) RTLocalIpcServerSetAccessMode(RTLOCALIPCSERVER hServer, RTFMODE fMode);
|
|
|
|
/**
|
|
* Listen for clients.
|
|
*
|
|
* @returns IPRT status code.
|
|
* @retval VINF_SUCCESS on success and *phClientSession containing the session handle.
|
|
* @retval VERR_CANCELLED if the listening was interrupted by RTLocalIpcServerCancel().
|
|
*
|
|
* @param hServer The server handle.
|
|
* @param phClientSession Where to store the client session handle on success.
|
|
*
|
|
*/
|
|
RTDECL(int) RTLocalIpcServerListen(RTLOCALIPCSERVER hServer, PRTLOCALIPCSESSION phClientSession);
|
|
|
|
/**
|
|
* Cancel the current or subsequent RTLocalIpcServerListen call.
|
|
*
|
|
* @returns IPRT status code.
|
|
* @param hServer The server handle. The nil value is quietly ignored (VINF_SUCCESS).
|
|
*/
|
|
RTDECL(int) RTLocalIpcServerCancel(RTLOCALIPCSERVER hServer);
|
|
|
|
|
|
/**
|
|
* Connects to a local IPC server.
|
|
*
|
|
* This is used a client process (or thread).
|
|
*
|
|
* @returns IPRT status code.
|
|
* @retval VINF_SUCCESS on success and *phSession holding the session handle.
|
|
*
|
|
* @param phSession Where to store the sesson handle on success.
|
|
* @param pszName The server name (see RTLocalIpcServerCreate for details).
|
|
* @param fFlags Flags, RTLOCALIPC_C_FLAGS_XXX.
|
|
*/
|
|
RTDECL(int) RTLocalIpcSessionConnect(PRTLOCALIPCSESSION phSession, const char *pszName, uint32_t fFlags);
|
|
|
|
/** @name RTLOCALIPC_C_FLAGS_XXX - RTLocalIpcSessionConnect flags
|
|
* @{ */
|
|
/** Native name, as apposed to a portable one. */
|
|
#define RTLOCALIPC_C_FLAGS_NATIVE_NAME RT_BIT_32(0)
|
|
/** The mask of valid flags. */
|
|
#define RTLOCALIPC_C_FLAGS_VALID_MASK UINT32_C(0x00000001)
|
|
/** @} */
|
|
|
|
/**
|
|
* Closes the local IPC session.
|
|
*
|
|
* This can be used with sessions created by both RTLocalIpcSessionConnect
|
|
* and RTLocalIpcServerListen. It will release one cancel pending I/O and
|
|
* relase one reference (typically the implict reference from the create API).
|
|
*
|
|
* @returns IPRT status code.
|
|
* @retval VINF_SUCCESS if still other references or NIL.
|
|
* @retval VINF_OBJECT_DESTROYED if session destroyed.
|
|
*
|
|
* @param hSession The session handle. The nil value is quietly ignored (VINF_SUCCESS).
|
|
*/
|
|
RTDECL(int) RTLocalIpcSessionClose(RTLOCALIPCSESSION hSession);
|
|
|
|
/**
|
|
* Retain a refence to the given session.
|
|
*
|
|
* @returns New reference count, UINT32_MAX if the handle is invalid.
|
|
* @param hSession The session handle.
|
|
*/
|
|
RTDECL(uint32_t) RTLocalIpcSessionRetain(RTLOCALIPCSESSION hSession);
|
|
|
|
/**
|
|
* Releases a refence to the given session.
|
|
*
|
|
* This differs from RTLocalIpcSessionClose in that it won't cancel any pending
|
|
* I/O. So, better call RTLocalIpcSessionClose if you want to terminate the
|
|
* session.
|
|
*
|
|
* @returns New reference count, 0 if NIL handle, UINT32_MAX if the handle is
|
|
* invalid.
|
|
* @param hSession The session handle.
|
|
*/
|
|
RTDECL(uint32_t) RTLocalIpcSessionRelease(RTLOCALIPCSESSION hSession);
|
|
|
|
|
|
/**
|
|
* Receive data from the other end of an local IPC session.
|
|
*
|
|
* This will block if there isn't any data.
|
|
*
|
|
* @returns IPRT status code.
|
|
* @retval VERR_CANCELLED if the operation was cancelled by RTLocalIpcSessionCancel.
|
|
*
|
|
* @param hSession The session handle.
|
|
* @param pvBuf Where to store the data.
|
|
* @param cbToRead How much to read. This is exact request if
|
|
* pcbRead is NULL, otherwise it's an upper limit.
|
|
* @param pcbRead Optional argument for indicating a partial read
|
|
* and returning the number of bytes actually read.
|
|
*/
|
|
RTDECL(int) RTLocalIpcSessionRead(RTLOCALIPCSESSION hSession, void *pvBuf, size_t cbToRead, size_t *pcbRead);
|
|
|
|
/**
|
|
* Receive pending data from the other end of an local IPC session.
|
|
*
|
|
* This will not block to wait for data.
|
|
*
|
|
* @returns IPRT status code.
|
|
* @retval VINF_TRY_AGAIN if no pending data (*pcbRead is set to 0).
|
|
* @retval VERR_CANCELLED if a previous operation was cancelled by
|
|
* RTLocalIpcSessionCancel (this operation isn't cancellable).
|
|
*
|
|
* @param hSession The session handle.
|
|
* @param pvBuf Where to store the data.
|
|
* @param cbToRead How much to read (upper limit).
|
|
* @param pcbRead Where to return exactly how much was read.
|
|
*/
|
|
RTDECL(int) RTLocalIpcSessionReadNB(RTLOCALIPCSESSION hSession, void *pvBuf, size_t cbToRead, size_t *pcbRead);
|
|
|
|
/**
|
|
* Send data to the other end of an local IPC session.
|
|
*
|
|
* This may or may not block until the data is received by the other party,
|
|
* this is an implementation detail. If you want to make sure that the data
|
|
* has been received you should always call RTLocalIpcSessionFlush().
|
|
*
|
|
* @returns IPRT status code.
|
|
* @retval VERR_CANCELLED if the operation was cancelled by RTLocalIpcSessionCancel.
|
|
*
|
|
* @param hSession The session handle.
|
|
* @param pvBuf The data to write.
|
|
* @param cbToWrite How much to write.
|
|
*/
|
|
RTDECL(int) RTLocalIpcSessionWrite(RTLOCALIPCSESSION hSession, const void *pvBuf, size_t cbToWrite);
|
|
|
|
/**
|
|
* Flush any buffered data and (perhaps) wait for the other party to receive it.
|
|
*
|
|
* The waiting for the other party to receive the data is
|
|
* implementation dependent.
|
|
*
|
|
* @returns IPRT status code.
|
|
* @retval VERR_CANCELLED if the operation was cancelled by RTLocalIpcSessionCancel.
|
|
*
|
|
* @param hSession The session handle.
|
|
*/
|
|
RTDECL(int) RTLocalIpcSessionFlush(RTLOCALIPCSESSION hSession);
|
|
|
|
/**
|
|
* Wait for data to become ready for reading or for the session to be
|
|
* disconnected.
|
|
*
|
|
* @returns IPRT status code.
|
|
* @retval VINF_SUCCESS when there is data to read.
|
|
* @retval VERR_TIMEOUT if no data became available within the specified period (@a cMillies)
|
|
* @retval VERR_BROKEN_PIPE if the session was disconnected.
|
|
* @retval VERR_CANCELLED if the operation was cancelled by RTLocalIpcSessionCancel.
|
|
*
|
|
* @param hSession The session handle.
|
|
* @param cMillies The number of milliseconds to wait. Use RT_INDEFINITE_WAIT
|
|
* to wait forever.
|
|
*
|
|
* @remark VERR_INTERRUPTED will not be returned. If this is desired at some later point
|
|
* add a RTLocalIpcSessionWaitForDataNoResume() variant like we're using elsewhere.
|
|
*/
|
|
RTDECL(int) RTLocalIpcSessionWaitForData(RTLOCALIPCSESSION hSession, uint32_t cMillies);
|
|
|
|
/**
|
|
* Cancells a pending or subsequent operation.
|
|
*
|
|
* Not all methods are cancellable, only those which are specfied
|
|
* returning VERR_CANCELLED. The others are assumed to not be blocking
|
|
* for ever and ever. However, the cancel is sticky, so the session must
|
|
* basically be trashed (closed) after calling this method.
|
|
*
|
|
* @returns IPRT status code.
|
|
*
|
|
* @param hSession The session handle.
|
|
*/
|
|
RTDECL(int) RTLocalIpcSessionCancel(RTLOCALIPCSESSION hSession);
|
|
|
|
/**
|
|
* Query the process ID of the other party.
|
|
*
|
|
* This is an optional feature which may not be implemented, so don't
|
|
* depend on it and check for VERR_NOT_SUPPORTED.
|
|
*
|
|
* @returns IPRT status code.
|
|
* @retval VINF_SUCCESS and *pProcess on success.
|
|
* @retval VERR_CANCELLED if the operation was cancelled by RTLocalIpcSessionCancel.
|
|
* @retval VERR_NOT_SUPPORTED and *pProcess = NIL_RTPROCESS if not supported.
|
|
*
|
|
* @param hSession The session handle.
|
|
* @param pProcess Where to store the process ID.
|
|
*/
|
|
RTDECL(int) RTLocalIpcSessionQueryProcess(RTLOCALIPCSESSION hSession, PRTPROCESS pProcess);
|
|
|
|
/**
|
|
* Query the user ID of the other party.
|
|
*
|
|
* This is an optional feature which may not be implemented, so don't
|
|
* depend on it and check for VERR_NOT_SUPPORTED.
|
|
*
|
|
* @returns IPRT status code.
|
|
* @retval VINF_SUCCESS and *pUid on success.
|
|
* @retval VERR_CANCELLED if the operation was cancelled by RTLocalIpcSessionCancel.
|
|
* @retval VERR_NOT_SUPPORTED and *pUid = NIL_RTUID if not supported.
|
|
*
|
|
* @param hSession The session handle.
|
|
* @param pUid Where to store the user ID on success.
|
|
*/
|
|
RTDECL(int) RTLocalIpcSessionQueryUserId(RTLOCALIPCSESSION hSession, PRTUID pUid);
|
|
|
|
/**
|
|
* Query the group ID of the other party.
|
|
*
|
|
* This is an optional feature which may not be implemented, so don't
|
|
* depend on it and check for VERR_NOT_SUPPORTED.
|
|
*
|
|
* @returns IPRT status code.
|
|
* @retval VINF_SUCCESS and *pUid on success.
|
|
* @retval VERR_CANCELLED if the operation was cancelled by RTLocalIpcSessionCancel.
|
|
* @retval VERR_NOT_SUPPORTED and *pGid = NIL_RTUID if not supported.
|
|
*
|
|
* @param hSession The session handle.
|
|
* @param pGid Where to store the group ID on success.
|
|
*/
|
|
RTDECL(int) RTLocalIpcSessionQueryGroupId(RTLOCALIPCSESSION hSession, PRTGID pGid);
|
|
|
|
/** @} */
|
|
RT_C_DECLS_END
|
|
|
|
#endif /* !IPRT_INCLUDED_localipc_h */
|
|
|