rvselect.h

基于h323协议的软phone

/***********************************************************************
Filename   : rvselect.h
Description: select interface (select, poll, /dev/poll, etc.)
************************************************************************
        Copyright (c) 2001 RADVISION Inc. and RADVISION Ltd.
************************************************************************
NOTICE:
This document contains information that is confidential and proprietary
to RADVISION Inc. and RADVISION Ltd.. No part of this document may be
reproduced in any form whatsoever without written prior approval by
RADVISION Inc. or RADVISION Ltd..

RADVISION Inc. and RADVISION Ltd. reserve the right to revise this
publication and make changes without obligation to notify any person of
such revisions or changes.
***********************************************************************/
#ifndef _RV_FD_SELECT_H
#define _RV_FD_SELECT_H

#include "rvccore.h"
#include "rvlock.h"
#include "rvsocket.h"



/* Error checks to make sure configuration has been done properly */
#if !defined(RV_SELECT_TYPE) || ((RV_SELECT_TYPE != RV_SELECT_SELECT) && \
    (RV_SELECT_TYPE != RV_SELECT_POLL) && (RV_SELECT_TYPE != RV_SELECT_DEVPOLL) && \
    (RV_SELECT_TYPE != RV_SELECT_WIN32_WSA) && (RV_SELECT_TYPE != RV_SELECT_WIN32_COMPLETION) )
#error RV_SELECT_TYPE not set properly
#endif
#if (RV_SELECT_TYPE == RV_SELECT_WIN32_COMPLETION)
#error RV_SELECT_WIN32_COMPLETION is not supported in this version
#endif
/* End of configuration error checks */


/* Module specific error codes (-512..-1023). See rverror.h dor more details */
#define RV_SELECT_ERROR_GETRLIMIT -512 /* Can't get the resource limit from the operating system */
#define RV_SELECT_ERROR_PIPE -513 /* Can't create a pipe for preemption */



#if defined(__cplusplus)
extern "C" {
#endif


typedef struct RvSelectEngineInternal RvSelectEngine;


/* File descriptor type */
typedef struct RvSelectFdInternal RvSelectFd;

/* Type declaration of events we can wait for on file descriptors */
typedef RvUint16 RvSelectEvents;


/********************************************************************************************
 * RvSelectCb
 *
 * purpose : Callback that is executed when an event occurs on a file descriptor
 * input   : selectEngine   - Events engine of this fd
 *           fd             - File descriptor that this event occured on
 *           selectEvent    - Event that happened
 *           error          - TRUE if an error occured
 * output  : None
 * return  : None
 * remarks :
 * - RvSelectRead is received whenever there are messages waiting on the given connection.
 *   Applications must be prepared to get WOULDBLOCK events when actually trying to read
 *   from the connection.
 *   Multiple recv() calls are possible. The event will only be activated again once this
 *   callback returns.
 * - RvSelectWrite is received when the application can send messages on the connection
 *   without being blocked (again, they must be prepared to get WOULDBLOCK).
 *   After this event is received, applications are encouraged to remove this event once they
 *   get it and enable it again when you get blocked trying to send messages - this works
 *   both on Unix and Windows systems.
 ********************************************************************************************/
typedef void
    (* RvSelectCb)(
        IN RvSelectEngine*  selectEngine,
        IN RvSelectFd*      fd,
        IN RvSelectEvents   selectEvent,
        IN RvBool           error);


#include "rvselectinternal.h"



/********************************************************************************************
 * Possible fd events
 * Not all operating systems support all of these events. In these cases, it's up to the
 * user of this module to resolve the actual event from the events he got.
 * The events that are supported by all are read and write events.
 * Note the fact that CLOSE events might not be returned by some OS's (mostly Unix). In such
 * cases, receiving a READ event, and actually trying to read will cause an error, which can
 * be interpreted as close event.
 ********************************************************************************************/
#define RvSelectRead        RV_SELECT_READ
#define RvSelectWrite       RV_SELECT_WRITE
#define RvSelectAccept      RV_SELECT_ACCEPT
#define RvSelectConnect     RV_SELECT_CONNECT
#define RvSelectClose       RV_SELECT_CLOSE



/* Prototypes and macros */

RvStatus RvSelectInit(void);
RvStatus RvSelectEnd(void);


RVCOREAPI RvStatus RVCALLCONV RvSelectSetMaxFileDescriptors(IN RvUint32 maxFileDescriptors);
RVCOREAPI RvUint32 RVCALLCONV RvSelectGetMaxFileDescriptors(void);


/********************************************************************************************
 * RvSelectConstruct
 *
 * purpose : Create a new file descriptor engine
 * input   : selectEngine       - Events engine to construct
 *           maxHashSize        - Hash size used by the engine
 *
 * output  : None
 * return  : RV_OK on success, other on failure
 ********************************************************************************************/
RVCOREAPI
RvStatus RVCALLCONV RvSelectConstruct(
    OUT RvSelectEngine*         selectEngine,
    IN  RvUint32                maxHashSize);


/********************************************************************************************
 * RvSelectDestruct
 *
 * purpose : Destruct a file descriptor engine
 * input   : selectEngine   - Events engine to destruct
 * output  : None
 * return  : RV_OK on success, other on failure
 ********************************************************************************************/
RVCOREAPI
RvStatus RVCALLCONV RvSelectDestruct(IN RvSelectEngine* selectEngine);


/********************************************************************************************
 * RvFdConstruct
 *
 * purpose : Construct a file descriptor for a given socket
 * input   : fd - File descriptor to construct
 *           s  - Socket to use for this file descriptor
 * output  : None
 * return  : RV_OK on success, other on failure
 ********************************************************************************************/
RVCOREAPI
RvStatus RVCALLCONV RvFdConstruct(
    IN RvSelectFd*  fd,
    IN RvSocket*    s);


/********************************************************************************************
 * RvFdDestruct
 *
 * purpose : Destruct a file descriptor of a given socket
 * input   : fd - File descriptor to destruct
 * output  : None
 * return  : RV_OK on success, other on failure
 ********************************************************************************************/
RVCOREAPI
RvStatus RVCALLCONV RvFdDestruct(
    IN RvSelectFd*  fd);


/********************************************************************************************
 * RvFdGetSocket
 *
 * purpose : Get the socket associated with the file descriptor struct
 * input   : fd - File descriptor
 * output  : None
 * return  : Socket associated with the file descriptor on success
 *           NULL on failure
 ********************************************************************************************/
RVCOREAPI
RvSocket* RVCALLCONV RvFdGetSocket(IN RvSelectFd* fd);


/********************************************************************************************
 * RvSelectGetEvents
 *
 * purpose : Return the list of events we're waiting on for a given file descriptor
 * input   : fd - File descriptor
 * output  : None
 * return  : Events we're waiting on
 ********************************************************************************************/
RVCOREAPI
RvSelectEvents RVCALLCONV RvSelectGetEvents(IN RvSelectFd* fd);


/********************************************************************************************
 * RvSelectFindFd
 *
 * purpose : Find the RvSelectFd object by the socket/file descriptor it's connected to.
 *           This one is used by H.323 to allow calls to seliCallOn() from the stack's
 *           API.
 * input   : selectEngine   - Events engine to look in
 *           s              - Socket/file descriptor object to find
 * output  : None
 * return  : RvSelectFd object if one exists, NULL otherwise.
 ********************************************************************************************/
RVCOREAPI
RvSelectFd* RVCALLCONV RvSelectFindFd(
    IN RvSelectEngine*  selectEngine,
    IN RvSocket*        s);


/********************************************************************************************
 * RvSelectAdd
 *
 * purpose : Add a new file descriptor to those being checked
 * input   : selectEngine   - Events engine of this fd
 *           fd             - File descriptor to check
 *           selectEvents   - Events to check
 *           eventsCb       - Callback to use when these events occur
 * output  : None
 * return  : RV_OK on success, other on failure
 ********************************************************************************************/
RVCOREAPI
RvStatus RVCALLCONV RvSelectAdd(
    IN RvSelectEngine*      selectEngine,
    IN RvSelectFd*          fd,
    IN RvSelectEvents       selectEvents,
    IN RvSelectCb           eventsCb);


/********************************************************************************************
 * RvSelectRemove
 *
 * purpose : Remove a file descriptor that is being checked by this engine
 * input   : selectEngine   - Events engine of this fd
 *           fd             - File descriptor to remove
 * output  : None
 * return  : RV_OK on success, other on failure
 * notes   : This function should only be called directly when the user wants the file
 *           descriptor to remain valid and active, but use it with a different events
 *           engine.
 *           Calling this function just before calling RvFdDestruct() on the same file
 *           descriptor will cause RvFdDestruct() to log an error message.
 ********************************************************************************************/
RVCOREAPI
RvStatus RVCALLCONV RvSelectRemove(
    IN RvSelectEngine*  selectEngine,
    IN RvSelectFd*      fd);


/********************************************************************************************
 * RvSelectUpdate
 *
 * purpose : Update the events of callback used for a given file descriptor
 * input   : selectEngine   - Events engine of this fd
 *           fd             - File descriptor to update
 *           selectEvents   - Events to check
 *           eventsCb       - Callback to use when these events occur
 * output  : None
 * return  : RV_OK on success, other on failure
 ********************************************************************************************/
RVCOREAPI
RvStatus RVCALLCONV RvSelectUpdate(
    IN RvSelectEngine*      selectEngine,
    IN RvSelectFd*          fd,
    IN RvSelectEvents       selectEvents,
    IN RvSelectCb           eventsCb);


/********************************************************************************************
 * RvSelectWaitAndBlock
 *
 * purpose : Wait for events to occur on this engine and block the current running thread
 *           for a given amount of time, or until events occur.
 * input   : selectEngine   - Events engine to wait for
 *           nsecTimeout    - Timeout to wait in nanoseconds
 *                            A 0-value will not block - just check for events
 * output  : None
 * return  : RV_OK on success, other on failure
 * notes   : This function must be called from the thread that called RvSelectConstruct().
 ********************************************************************************************/
RVCOREAPI
RvStatus RVCALLCONV RvSelectWaitAndBlock(
    IN RvSelectEngine*      selectEngine,
    IN RvUint64             nsecTimeout);


/********************************************************************************************
 * RvSelectStopWaiting
 *
 * purpose : Stop waiting for events on the given events engine. This function is called
 *           from threads other than the one that called RvSelectWaitAndBlock() in order
 *           to preempt it.
 * input   : selectEngine   - Events engine to stop from blocking
 * output  : None
 * return  : RV_OK on success, other on failure
 * notes   : This function doesn't wait for the other thread to stop executing, it just
 *           makes sure the other thread returns from the call to RvSelectWaitAndBlock().
 ********************************************************************************************/
RVCOREAPI
RvStatus RVCALLCONV RvSelectStopWaiting(
    IN RvSelectEngine*      selectEngine);


#if defined(__cplusplus)
}
#endif

#endif /* _RV_FD_SELECT_H */