166 lines
6.0 KiB
C
166 lines
6.0 KiB
C
/* This Source Code Form is subject to the terms of the Mozilla Public
|
|
* License, v. 2.0. If a copy of the MPL was not distributed with this
|
|
* file, You can obtain one at http://mozilla.org/MPL/2.0/. */
|
|
|
|
#ifndef _CPR_IPC_H_
|
|
#define _CPR_IPC_H_
|
|
|
|
#include "cpr_types.h"
|
|
|
|
__BEGIN_DECLS
|
|
|
|
/**
|
|
* Define handle for message queues
|
|
*/
|
|
typedef void* cprMsgQueue_t;
|
|
|
|
/*
|
|
* A timeout value of -1 means wait forever when
|
|
* attempting to get a message. Just #define something
|
|
* so the application code is easier to read.
|
|
*/
|
|
#define WAIT_FOREVER -1
|
|
|
|
#if defined SIP_OS_LINUX
|
|
#include "../linux/cpr_linux_ipc.h"
|
|
#elif defined SIP_OS_WINDOWS
|
|
#include "../win32/cpr_win_ipc.h"
|
|
#elif defined SIP_OS_OSX
|
|
#include "../darwin/cpr_darwin_ipc.h"
|
|
#endif
|
|
|
|
/* Function prototypes */
|
|
/**
|
|
* Creates a message queue
|
|
*
|
|
* @brief The cprCreateMessageQueue function is called to allow the OS to
|
|
* perform whatever work is needed to create a message queue.
|
|
|
|
* If the name is present, CPR should assign this name to the message queue to assist in
|
|
* debugging. The message queue depth is the second input parameter and is for
|
|
* setting the desired queue depth. This parameter may not be supported by all OS.
|
|
* Its primary intention is to set queue depth beyond the default queue depth
|
|
* limitation.
|
|
* On any OS where there is no limit on the message queue depth or
|
|
* its queue depth is sufficiently large then this parameter is ignored on that
|
|
* OS.
|
|
*
|
|
* @param[in] name - name of the message queue (optional)
|
|
* @param[in] depth - the message queue depth, optional field which should
|
|
* default if set to zero(0)
|
|
*
|
|
* @return Msg queue handle or NULL if init failed, errno should be provided
|
|
*
|
|
* @note the actual message queue depth will be bounded by the
|
|
* standard system message queue depth and CPR_MAX_MSG_Q_DEPTH.
|
|
* If 'depth' is outside of the bounds, the value will be
|
|
* reset automatically.
|
|
*/
|
|
cprMsgQueue_t
|
|
cprCreateMessageQueue(const char *name, uint16_t depth);
|
|
|
|
|
|
/**
|
|
* cprDestroyMessageQueue
|
|
* @brief Removes all messages from the queue and then destroy the message queue
|
|
*
|
|
* The cprDestroyMessageQueue function is called to destroy a message queue. The
|
|
* function drains any messages from the queue and the frees the
|
|
* message queue. Any messages on the queue are to be deleted, and not sent to the intended
|
|
* recipient. It is the application's responsibility to ensure that no threads are
|
|
* blocked on a message queue when it is destroyed.
|
|
*
|
|
* @param[in] msgQueue - message queue to destroy
|
|
*
|
|
* @return CPR_SUCCESS or CPR_FAILURE, errno should be provided in this case
|
|
*/
|
|
cprRC_t
|
|
cprDestroyMessageQueue(cprMsgQueue_t msgQueue);
|
|
|
|
#ifdef CPR_USE_SET_MESSAGE_QUEUE_THREAD
|
|
/**
|
|
* cprSetMessageQueueThread
|
|
* @brief Associate a thread with the message queue
|
|
*
|
|
* This method is used by pSIPCC to associate a thread and a message queue.
|
|
* @param[in] msgQueue - msg queue to set
|
|
* @param[in] thread - CPR thread to associate with queue
|
|
*
|
|
* @return CPR_SUCCESS or CPR_FAILURE
|
|
*
|
|
* @note Nothing is done to prevent overwriting the thread ID
|
|
* when the value has already been set.
|
|
*/
|
|
cprRC_t
|
|
cprSetMessageQueueThread(cprMsgQueue_t msgQueue, cprThread_t thread);
|
|
#endif
|
|
|
|
|
|
/**
|
|
* cprGetMessage
|
|
* @brief Retrieve a message from a particular message queue
|
|
*
|
|
* The cprGetMessage function retrieves the first message from the message queue
|
|
* specified and returns a void pointer to that message.
|
|
*
|
|
* @param[in] msgQueue - msg queue from which to retrieve the message. This
|
|
* is the handle returned from cprCreateMessageQueue.
|
|
* @param[in] waitForever - boolean to either wait forever (TRUE) or not
|
|
* wait at all (FALSE) if the msg queue is empty.
|
|
* @param[out] ppUserData - pointer to a pointer to user defined data. This
|
|
* will be NULL if no user data was present.
|
|
*
|
|
* @return Retrieved message buffer or NULL if failure occurred or
|
|
* the waitForever flag was set to false and no messages were
|
|
* on the queue.
|
|
*
|
|
* @note If ppUserData is defined, the value will be initialized to NULL
|
|
*/
|
|
void *
|
|
cprGetMessage(cprMsgQueue_t msgQueue,
|
|
boolean waitForever,
|
|
void** usrPtr);
|
|
|
|
/**
|
|
* cprSendMessage
|
|
* @brief Place a message on a particular queue. Note that caller may
|
|
* block (see comments below)
|
|
*
|
|
* @param[in] msgQueue - msg queue on which to place the message
|
|
* @param[in] msg - pointer to the msg to place on the queue
|
|
* @param[in] ppUserData - pointer to a pointer to user defined data
|
|
*
|
|
* @return CPR_SUCCESS or CPR_FAILURE, errno should be provided
|
|
*
|
|
* @note 1. Messages queues are set to be non-blocking, those cases
|
|
* where the system call fails with a would-block error code
|
|
* (EAGAIN) the function will attempt other mechanisms described
|
|
* below.
|
|
* @note 2. If enabled with an extended message queue, either via a
|
|
* call to cprCreateMessageQueue with depth value or a call to
|
|
* cprSetExtendMessageQueueDepth() (when unit testing), the message
|
|
* will be added to the extended message queue and the call will
|
|
* return successfully. When room becomes available on the
|
|
* system's message queue, those messages will be added.
|
|
* @note 3. If the message queue becomes full and no space is availabe
|
|
* on the extended message queue, then the function will attempt
|
|
* to resend the message up to CPR_ATTEMPTS_TO_SEND and the
|
|
* calling thread will *BLOCK* CPR_SND_TIMEOUT_WAIT_INTERVAL
|
|
* milliseconds after each failed attempt. If unsuccessful
|
|
* after all attempts then EGAIN error code is returned.
|
|
* @note 4. This applies to all CPR threads, including the timer thread.
|
|
* So it is possible that the timer thread would be forced to
|
|
* sleep which would have the effect of delaying all active
|
|
* timers. The work to fix this rare situation is not considered
|
|
* worth the effort to fix....so just leaving as is.
|
|
*/
|
|
cprRC_t
|
|
cprSendMessage(cprMsgQueue_t msgQueue,
|
|
void* msg,
|
|
void** usrPtr);
|
|
|
|
__END_DECLS
|
|
|
|
#endif
|
|
|