207 lines
6.4 KiB
C
207 lines
6.4 KiB
C
/*
|
|
* A S Y N C Q U E U E
|
|
*
|
|
* This module manages communications on an asynchronous connection.
|
|
*
|
|
* Douglas Clowes, May 2007
|
|
*
|
|
*/
|
|
#ifndef SICSASYNCQUEUE
|
|
#define SICSASYNCQUEUE
|
|
|
|
#include "asyncprotocol.h"
|
|
|
|
typedef struct __AsyncQueue AsyncQueue, *pAsyncQueue;
|
|
|
|
|
|
/** \brief create an AsyncUnit attached to a named AsyncQueue.
|
|
*
|
|
* \param queueName the name of the AsyncQueue to be used
|
|
* \param unit pointer to the AsyncUnit created on positive return
|
|
* \return positive if successful
|
|
*/
|
|
int AsyncUnitCreate(const char *queueName, pAsyncUnit * unit);
|
|
/** \brief Get an AsyncUnit from a given AsyncQueue
|
|
* \param queue The AsyncQueue for which this AsyncUnit is valid
|
|
* \return a new AsyncUnit or NULL on error
|
|
*/
|
|
pAsyncUnit AsyncUnitFromQueue(pAsyncQueue queue);
|
|
|
|
/** \brief create an AsyncUnit attached to an anonymous AsyncQueue.
|
|
*
|
|
* \param host name or address of the target host
|
|
* \param port number or service name on the target host
|
|
* \param unit pointer to the AsyncUnit created on positive return
|
|
* \return positive if successful
|
|
*
|
|
* If <port> is null then <host> points to an existing queue name.
|
|
* If a queue exists for <host>/<port>, then that queue is used.
|
|
* If neither of the above hold, a new queue is created.
|
|
*/
|
|
int AsyncUnitCreateHost(const char *host,
|
|
const char *port, pAsyncUnit * unit);
|
|
|
|
/** \brief destroys an AsyncUnit
|
|
*
|
|
* \param unit pointer to the AsyncUnit to be destroyed
|
|
*/
|
|
int AsyncUnitDestroy(pAsyncUnit unit);
|
|
|
|
/** \brief Queue a transaction at the head of the associated AsyncQueue
|
|
*
|
|
* \param unit AsyncUnit
|
|
* \param pTxn pointer to transaction
|
|
*/
|
|
int AsyncUnitEnqueueHead(pAsyncUnit unit, pAsyncTxn pTxn);
|
|
|
|
/** \brief Queue a transaction at the tail of the associated AsyncQueue
|
|
*
|
|
* \param unit AsyncUnit
|
|
* \param pTxn pointer to transaction
|
|
*/
|
|
int AsyncUnitEnqueueTxn(pAsyncUnit unit, pAsyncTxn pTxn);
|
|
|
|
/** \brief prepare a transaction according to the protocol (default is CRLF)
|
|
*
|
|
* \param unit AsyncUnit
|
|
* \param command text string to be sent
|
|
* \param cmd_len length of data in command
|
|
* \param responseHandler function to handle the response
|
|
* \param context to be used by handler function
|
|
* \param resp_len maximum length to be allowed for response
|
|
*/
|
|
pAsyncTxn AsyncUnitPrepareTxn(pAsyncUnit unit,
|
|
const char *command, int cmd_len,
|
|
AsyncTxnHandler responseHandler,
|
|
void *context, int rsp_len);
|
|
|
|
/** \brief clone a pointer to the transaction - must use AsyncUnitFreeTxn
|
|
* \param txn the transaction to clone
|
|
*/
|
|
pAsyncTxn AsyncUnitHoldTxn(pAsyncTxn txn);
|
|
|
|
/** \brief free a cloned transaction
|
|
* \param txn the transaction to free (returned by AsyncUnitHoldTxn)
|
|
*/
|
|
void AsyncUnitFreeTxn(pAsyncTxn txn);
|
|
|
|
/** \brief prepare and queue a transaction
|
|
*
|
|
* \param unit AsyncUnit
|
|
* \param command text string to be sent
|
|
* \param cmd_len length of data in command
|
|
* \param responseHandler function to handle the response
|
|
* \param context to be used by handler function
|
|
* \param resp_len maximum length to be allowed for response
|
|
*/
|
|
int AsyncUnitSendTxn(pAsyncUnit unit,
|
|
const char *command, int cmd_len,
|
|
AsyncTxnHandler responseHandler, void *context,
|
|
int rsp_len);
|
|
|
|
/** \brief send a transaction and wait for the response
|
|
*
|
|
* \param unit AsyncUnit
|
|
* \param command text string to be sent
|
|
* \param cmd_len length of data in command
|
|
* \param responseHandler function to handle the response
|
|
* \param context to be used by handler function
|
|
* \param resp_len [in] maximum length to be allowed for response
|
|
* [out] actual length returned
|
|
*/
|
|
int AsyncUnitTransact(pAsyncUnit unit,
|
|
const char *command, int cmd_len,
|
|
char *response, int *rsp_len);
|
|
|
|
/** \brief write to the AsyncQueue file descriptor
|
|
*
|
|
* The data is transmitted directly to the descriptor without being queued.
|
|
* This may be used by the protocol transmit function or for retrieving error
|
|
* text associated with the current transmission.
|
|
*
|
|
* \param unit AsyncUnit
|
|
* \param data to be transmitted
|
|
* \param buflen lenght of data
|
|
*/
|
|
int AsyncUnitWrite(pAsyncUnit unit, void *buffer, int buflen);
|
|
|
|
/** \brief registers a notification callback
|
|
*
|
|
* The notification callback may notify unsolicited or unusual events
|
|
*
|
|
* \param unit AsyncUnit
|
|
* \param context passed in callback
|
|
* \param notify function to be called
|
|
*/
|
|
typedef void (*AQU_Notify) (void *context, int event);
|
|
void AsyncUnitSetNotify(pAsyncUnit unit, void *context, AQU_Notify notify);
|
|
|
|
/** \brief get the intertransaction delay in milliseconds
|
|
*/
|
|
int AsyncUnitGetDelay(pAsyncUnit unit);
|
|
|
|
/** \brief set the intertransaction delay in milliseconds
|
|
*/
|
|
void AsyncUnitSetDelay(pAsyncUnit unit, int iDelay);
|
|
|
|
/** \brief get the default transaction timeout in milliseconds
|
|
*/
|
|
int AsyncUnitGetTimeout(pAsyncUnit unit);
|
|
|
|
/** \brief set the default transaction timeout in milliseconds
|
|
*/
|
|
void AsyncUnitSetTimeout(pAsyncUnit unit, int timeout);
|
|
|
|
/** \brief get the number of retries
|
|
*/
|
|
int AsyncUnitGetRetries(pAsyncUnit unit);
|
|
|
|
/** \brief set the number of retries
|
|
*/
|
|
void AsyncUnitSetRetries(pAsyncUnit unit, int retries);
|
|
|
|
/** \brief get the associated protocol handler
|
|
*/
|
|
pAsyncProtocol AsyncUnitGetProtocol(pAsyncUnit unit);
|
|
|
|
/** \brief set the associated protocol handler
|
|
*/
|
|
void AsyncUnitSetProtocol(pAsyncUnit unit, pAsyncProtocol protocol);
|
|
|
|
/** \brief retrieves the socket/channel associated with the AsyncQueue
|
|
*
|
|
* \param unit AsyncUnit
|
|
* \return channel or NULL
|
|
*/
|
|
mkChannel *AsyncUnitGetSocket(pAsyncUnit unit);
|
|
|
|
/** \brief attempt to reconnect the socket of the associated AsyncQueue
|
|
*
|
|
* \param unit pointer to AsyncUnit
|
|
*/
|
|
int AsyncUnitReconnect(pAsyncUnit handle);
|
|
|
|
/** \brief create an AsyncQueue from the SICS command MakeAsyncQueue
|
|
*/
|
|
int AsyncQueueFactory(SConnection * pCon, SicsInterp * pSics,
|
|
void *pData, int argc, char *argv[]);
|
|
|
|
/** \brief SICS command handler for the AsyncQueue object
|
|
*/
|
|
int AsyncQueueAction(SConnection * pCon, SicsInterp * pSics,
|
|
void *pData, int argc, char *argv[]);
|
|
|
|
/** \brief store queue level context
|
|
*/
|
|
void *AsyncUnitSetQueueContext(pAsyncUnit handle, void *cntx);
|
|
|
|
/** \brief retrieve queue level context
|
|
*/
|
|
void *AsyncUnitGetQueueContext(pAsyncUnit handle);
|
|
|
|
/** \brief return one if queue is connected, zero otherwise
|
|
*/
|
|
int AsyncUnitIsQueueConnected(pAsyncUnit handle);
|
|
|
|
#endif /* SICSASYNCQUEUE */
|