rvsocket.h

基于h323协议的软phone

 * output  : None
 * return  : RV_OK on success, other on failure
 ********************************************************************************************/
RVCOREAPI
RvStatus RVCALLCONV RvSocketJoinMulticastGroup(
    IN RvSocket*    socket,
    IN RvAddress*   multicastAddress,
    IN RvAddress*   interfaceAddress);


/********************************************************************************************
 * RvSocketLeaveMulticastGroup
 *
 * purpose : Leave a multicast group
 * input   : socket             - Socket to modify
 *           multicastAddress   - Multicast address to leave
 *           interfaceAddress   - Interface address to use on the local host.
 *                                Setting this to NULL chooses an arbitrary interface
 * output  : None
 * return  : RV_OK on success, other on failure
 ********************************************************************************************/
RVCOREAPI
RvStatus RVCALLCONV RvSocketLeaveMulticastGroup(
    IN RvSocket*    socket,
    IN RvAddress*   multicastAddress,
    IN RvAddress*   interfaceAddress);


/* =========================== */
/* ==== functions for TCP ==== */
/* =========================== */

RVCOREAPI
RvStatus RVCALLCONV RvSocketConnect(IN RvSocket *socket, IN RvAddress* address);

/********************************************************************************************
 * RvSocketAccept
 *
 * purpose : Accept an incoming socket request
 * input   : socket         - Listening socket receiving the incoming connection
 * output  : newSocket      - Accepted socket information
 *           remoteAddress  - Address of remote side of connection
 *                            Can be passed as NULL if not needed
 * return  : RV_OK on success, other on failure
 ********************************************************************************************/
RVCOREAPI
RvStatus RVCALLCONV RvSocketAccept(
    IN  RvSocket*       socket,
    OUT RvSocket*       newSocket,
    OUT RvAddress*      remoteAddress);

/********************************************************************************************
 * RvSocketListen
 *
 * purpose : Waits for an incoming connection.
 * input   : sock           - Listening socket receiving the incoming connection
 *           queuelen       -
 * output  : None.
 * return  : RV_OK on success, other on failure
 ********************************************************************************************/
RVCOREAPI
RvStatus RVCALLCONV RvSocketListen(IN RvSocket *socket, IN RvUint32 queuelen);

/********************************************************************************************
 * RvSocketShutdown
 *
 * purpose : Shutdown a TCP socket. This function should be called before calling
 *           RvSocketDestruct() for TCP sockets.
 * input   : socket         - Socket to shutdown
 *           cleanSocket    - RV_TRUE if you want to clean the socket before shutting it down.
 *                            this will try to receive from the socket some buffers.
 *                            It is suggested to set this value to RV_TRUE.
 * output  : None
 * return  : RV_OK on success, other on failure
 ********************************************************************************************/
RVCOREAPI
RvStatus RVCALLCONV RvSocketShutdown(
    IN RvSocket*    socket,
    IN RvBool       cleanSocket);

/********************************************************************************************
 * RvSocketDestruct
 *
 * purpose : Close a socket.
 * input   : socket         - Socket to shutdown
 *           cleanSocket    - RV_TRUE if you want to clean the socket before shutting it down.
 *                            this will try to receive from the socket some buffers.
 *                            It is suggested to set this value to RV_TRUE for TCP sockets.
 *                            It should be set to RV_FALSE for UDP sockets.
 *           portRange      - Port range to return this socket's port to. If NULL, the
 *                            socket's port will not be added to any port range object.
 * output  : None
 * return  : RV_OK on success, other on failure
 ********************************************************************************************/
RVCOREAPI
RvStatus RVCALLCONV RvSocketDestruct(
    IN RvSocket*    socket,
    IN RvBool       cleanSocket,
    IN RvPortRange* portRange);


/* ================================ */
/* ==== Send/receive functions ==== */
/* ================================ */

/********************************************************************************************
 * RvSocketSendBuffer
 *
 * purpose : Send a buffer on a connection
 * input   : socket         - Socket to send the buffer on
 *           buffer         - Buffer to send
 *           bytesToSend    - Number of bytes to send from buffer
 *           remoteAddress  - Address to send the buffer to.
 *                            Can be NULL on connection-oriented sockets (TCP).
 * output  : bytesSent      - Number of bytes we sent
 *                            If less than bytesToSend, then we would block if we tried on a
 *                            blocking socket. The application in this case should wait for a
 *                            WRITE event before trying again.
 * return  : RV_OK on success, other on failure
 * notes   : A blocked socket returns RV_OK with bytesSent=0
 ********************************************************************************************/
RVCOREAPI
RvStatus RVCALLCONV RvSocketSendBuffer(
    IN  RvSocket*   socket,
    IN  RvUint8*    buffer,
    IN  RvSize_t    bytesToSend,
    IN  RvAddress*  remoteAddress,
    OUT RvSize_t*   bytesSent);


/********************************************************************************************
 * RvSocketReceiveBuffer
 *
 * purpose : Receive a buffer from a connection
 * input   : socket         - Socket to receive the buffer from
 *           buffer         - Buffer to use for received data
 *           bytesToReceive - Number of bytes available on the given buffer
 * output  : bytesReceived  - Number of bytes that were actually received
 *           remoteAddress  - Address buffer was received from
 *                            Can be given as NULL on connection-oriented sockets (TCP).
 *                            This address is constructed by this function and should be
 *                            destructed by the caller to this function
 * return  : RV_OK on success, other on failure
 * notes   : A blocked socket returns RV_OK with bytesReceived=0
 ********************************************************************************************/
RVCOREAPI
RvStatus RVCALLCONV RvSocketReceiveBuffer(
    IN  RvSocket*   socket,
    IN  RvUint8*    buffer,
    IN  RvSize_t    bytesToReceive,
    OUT RvSize_t*   bytesReceived,
    OUT RvAddress*  remoteAddress);


/* =========================== */
/* ==== Utility functions ==== */
/* =========================== */

/********************************************************************************************
 * RvSocketGetBytesAvailable
 *
 * purpose : Get the number of bytes that are in the receive buffer of the socket.
 *           This number might be larger than the return result of a single recv() operation.
 *           This is important when dealing with data-gram types of connections (such as UDP).
 * input   : socket         - Socket to check
 * output  : bytesAvailable - Number of bytes in the receive buffer of the socket
 * return  : RV_OK on success, other on failure
 ********************************************************************************************/
RVCOREAPI
RvStatus RVCALLCONV RvSocketGetBytesAvailable(IN RvSocket* socket, OUT RvSize_t* bytesAvailable);


/********************************************************************************************
 * RvSocketGetLastError
 *
 * purpose : Get the last error that occured on a socket.
 *           This function works for synchronous sockets only.
 *           The return value is OS-specific. A value of 0 means no error occured.
 * input   : socket     - Socket to check
 * output  : lastError  - Error that occured. 0 means no error.
 * return  : RV_OK on success, other on failure
 ********************************************************************************************/
RVCOREAPI
RvStatus RVCALLCONV RvSocketGetLastError(IN RvSocket* socket, OUT RvInt32* lastError);


/********************************************************************************************
 * RvSocketGetLocalAddress
 *
 * purpose : Get the local address used by this socket.
 * input   : socket     - Socket to check
 * output  : address    - Local address
 *                        Must be destructed by the caller to this function
 * return  : RV_OK on success, other on failure
 ********************************************************************************************/
RVCOREAPI
RvStatus RVCALLCONV RvSocketGetLocalAddress(IN RvSocket *socket, OUT RvAddress* address);


/********************************************************************************************
 * RvSocketGetRemoteAddress
 *
 * purpose : Get the remote address used by this socket.
 * input   : socket     - Socket to check
 * output  : address    - Remote address
 *                        Must be destructed by the caller to this function
 * return  : RV_OK on success, other on failure
 ********************************************************************************************/
RVCOREAPI
RvStatus RVCALLCONV RvSocketGetRemoteAddress(IN RvSocket *socket, OUT RvAddress* address);


#if (RV_OS_TYPE == RV_OS_TYPE_NUCLEUS)
/********************************************************************************************
 * RvSocketSetSelectEngine
 *
 ********************************************************************************************/
RvStatus RvSocketSetSelectEngine(RvSocket socket, void* selectEngine);
#endif

#if defined(__cplusplus)
}
#endif

#endif /* RV_SOCKET_H */