radlib Library Reference

Version 2.12.0

 

Index


Buffers (radbuffers.h)

Buffer sizes are determined by the following three macros defined in radsysdefs.h. Buffer sizes start at SYS_BUFFER_SMALLEST_SIZE (+4) and are increased by powers of 2 up to SYS_BUFFER_LARGEST_SIZE (+4), with SYS_BUFFER_NUMBER_OF_SIZES different sizes. The definition of counts for each buffer size is in the array sysBufferCounts, defined in radsysdefs.c. These can be tailored to system buffer requirements and available memory.

radBuffersInit
radBufferGet
radBufferRls
radBuffersExit
radBuffersExitAndDestroy
radBuffersGetTotal
radBuffersGetAvailable


Config Files (radconffile.h)

radCfOpen
radCfClose
radCfFlush
radCfPutComment
radCfPutCommentBefore
radCfIsCommentBefore
radCfIsCommentAfter
radCfGetFirstEntry
radCfGetNextEntry
radCfGetEntry
radCfPutEntry


CRC Utilities (radcrc.h)

CCITT CRC utilities.

radCRC16Calculate
radCRC32Calculate


SQL Database Interface (raddatabase.h)

Optional MySQL or PostGreSQL database library which may be included when radlib is configured via the "--enable-mysql" or "--enable-pgresql" argument to the configure script. Requires a running MySQL or PostgreSQL server and the mysqlclient or pq library (libmysqlclient.a or libpq.a). Other database servers can be supported - all engine-specific source code is segregated in .../database/mysql or .../database/postgresql. Databases, users and user access privileges must be setup outside of the radlib interface - radlib can create/delete tables/rows and manipulate them for given databases and users. Local or remote servers can be accessed.

Database Methods
raddatabaseOpen
raddatabaseClose
raddatabaseQuery
raddatabaseGetResults
raddatabaseRefreshResults
raddatabaseReleaseResults

Table Methods
raddatabaseTableIfExists
raddatabaseTableCreate
raddatabaseTableDelete
raddatabaseTableTruncate
raddatabaseTableDescriptionGet
raddatabaseTableQueryRow
raddatabaseTableInsertRow
raddatabaseTableModifyRows
raddatabaseTableDeleteRows

Result Set Methods
raddatabaseResultsGetFirst
raddatabaseResultsGetNext
raddatabaseResultsGetPrev
raddatabaseResultsGetLast

Row Description Methods
raddatabaseRowDescriptionCreate
raddatabaseRowDescriptionAddField
raddatabaseRowDescriptionRemoveField
raddatabaseRowDescriptionDelete

Field Manipulation Methods
raddatabaseFieldGet
raddatabaseFieldGetType
raddatabaseFieldGetIntValue
raddatabaseFieldGetBigIntValue
raddatabaseFieldGetFloatValue
raddatabaseFieldGetDoubleValue
raddatabaseFieldGetTimeDateValue
raddatabaseFieldGetCharValue
raddatabaseFieldGetCharLength
raddatabaseFieldSetTypeInt
raddatabaseFieldSetTypeBigInt
raddatabaseFieldSetTypeFloat
raddatabaseFieldSetTypeDouble
raddatabaseFieldSetTypeDateTime
raddatabaseFieldSetTypeChar
raddatabaseFieldSetToNull
raddatabaseFieldSetToNotNull
raddatabaseFieldSetIntValue
raddatabaseFieldSetBigIntValue
raddatabaseFieldSetFloatValue
raddatabaseFieldSetDoubleValue
raddatabaseFieldSetDateTimeValue
raddatabaseFieldSetCharValue


Events (radevents.h)

radEventsInit
radEventsExit
radEventsAdd
radEventsRemove
radEventsGetMask
radEventsSend
radEventsProcess


Doubly-Linked Lists (radlist.h)

To use the list utility, one first creates (or resets) the list. Subsequent calls to this utility take the RADLIST_ID as the first parameter. In order for a structure to be an item or "node" on the list, the structure must include the NODE structure as it's first member. This allows different types of objects to be stored on the same list.

radListCreate
radListReset
radListDelete
radListInsertAfter
radListInsertBefore
radListAddToFront
radListAddToEnd
radListRemove
radListRemoveFirst
radListRemoveLast
radListGetNumberOfNodes
radListGetFirst
radListGetLast
radListGetNext
radListGetPrevious


System Logging (radmsgLog.h)

The message logging utility uses the syslog system facility. Messages can have the following priorities:
enum MsgLogPriorities
{
PRI_STATUS = LOG_INFO,
PRI_MEDIUM = LOG_WARNING,
PRI_HIGH = LOG_CRIT,
PRI_CATASTROPHIC = LOG_ALERT
};

radMsgLogInit
radMsgLogExit
radMsgLog
radMsgLogData


Message ID-Based Message Router and API (radmsgRouter.h)

Message ID-based messaging requires the radlib message router to be run prior to any application processes. The message router is installed at $prefix/bin/radmrouted. See radmsgRouter.h for start up details. This API supports sending and receiving messages through the radmrouted daemon.
Message routing can be done across processors using a common message ID namespace. The radmrouted instance running on each processor "associates" to his peer(s) using TCP/IP sockets. A radmrouted instance may be a server and/or client. Messages routed on one processor are routed to all associated processors and delivered to all consumers on each processor for that message type. It makes interprocessor communications transparent. See "radmrouted Daemon Usage" below for command line options which enable multiprocessor communications.

radMsgRouterInit
radMsgRouterExit
radMsgRouterProcessExit
radMsgRouterMessageRegister
radMsgRouterMessageDeregister
radMsgRouterMessageIsRegistered
radMsgRouterMessageSend
radMsgRouterStatsDump
radmrouted Daemon Usage


Process Framework (radprocess.h)

This utility brings together many of the radlib concepts into one set of APIs. This is the preferred API for implementing radlib processes and applications. It greatly simplifies the asynchronous capabilities of a well constructed radlib application.

radProcessInit
radProcessExit
radProcessSetExitFlag
radProcessWait
radProcessGetName
radProcessGetPid
radProcessIORegisterDescriptor
radProcessIODeRegisterDescriptor
radProcessIORegisterSTDIN
radProcessSignalCatchAll
radProcessSignalCatch
radProcessSignalRelease
radProcessSignalIgnore
radProcessSignalGetHandler
radProcessQueueGetName
radProcessQueueAttach
radProcessQueueDettach
radProcessQueueJoinGroup
radProcessQueueQuitGroup
radProcessQueueSend
radProcessQueueSendGroup
radProcessQueueIsAttached
radProcessQueueKeepBuffer
radProcessQueueStopHandlerList
radProcessQueuePrependHandler
radProcessQueueRemoveHandler
radProcessTimerCreate
radProcessTimerDelete
radProcessTimerStart
radProcessTimerStop
radProcessTimerStatus
radProcessTimerSetUserParm
radProcessEventsAdd
radProcessEventsRemove
radProcessEventsGetEnabled
radProcessEventsSend


Process List Management (radproclist.h)

radPlistCreate
radPlistDestroy
radPlistAdd
radPlistStart
radPlistGetNumberRunning
radPlistExecByEntryPoint
radPlistExecAll
radPlistAddPid
radPlistRemovePid
radPlistAddandStart
radPlistProcessReady
radPlistFindByEntryPoint


Process Utilities (radprocutils.h)

radStartProcess


Message Queues (radqueue.h)

Process message queues are implemented using named pipes. Therefore, "queue names" should be the full path name to a pipe device file, which will be created by radQueueInit if it does not exist. This utility is best used as part of the radProcess framework.

radQueueSystemInit
radQueueSystemExit
radQueueInit
radQueueExit
radQueueGetFD
radQueueGetName
radQueueAttach
radQueueDettach
radQueueJoinGroup
radQueueQuitGroup
radQueueRecv
radQueueSend
radQueueSendGroup
radQueueIsAttached


Semaphores (radsemaphores.h)

radSemProcessInit
radSemSetDestroy
radSemCreate
radSemTake
radSemGive
radSemGiveMultiple
radSemTest
radSemDelete
radSemDebug


SHA-1 and SHA-256 Secure Hashing Utilities (radsha.h)

The SHA algorithms were designed by the National Security Agency (NSA) and published as US government standards. The SHA-256 implementation is derived from the FreeBSD implementation. Host endianness is determined when radlib is configured and the SHA utilities work properly on big or little endian hosts.

radSHA1ComputeBlock
radSHA1ComputeFile
radSHA256ComputeBlock
radSHA256ComputeFile


Shared Memory (radshmem.h)

Shared memory is the lynch pin of radlib interprocess communications. System buffers and message queues depend upon the existence (and robustness) of shared memory.

radShmemIfExist
radShmemInit
radShmemGet
radShmemLock
radShmemUnlock
radShmemExit
radShmemExitAndDestroy


TCP Stream Sockets (radsocket.h)

radSocketServerCreate
radSocketServerAcceptConnection
radSocketClientCreate
radSocketClientCreateAny
radSocketDestroy
radSocketGetDescriptor
radSocketGetHost
radSocketGetPort
radSocketReadExact
radSocketWriteExact
radSocketSetBlocking
radSocketSetDebug


Sorted Lists (radsortlist.h)

radSortListInit
radSortListExit
radSortListInsert
radSortListRemove
radSortListFind


SQLite Database Interface (radsqlite.h)

Optional SQLite database library which may be included when radlib is configured via the "--enable-sqlite" argument to the configure script. Requires the SQLite development library (libsqlite.a). Preserves much of the raddatabase.h API but is simplified for the SQLite capabilities and API design. Can be enabled in parallel with raddatabase-supported database engines.

Database Methods
radsqliteOpen
radsqliteClose
radsqliteQuery
radsqliteGetResults
radsqliteRefreshResults
radsqliteReleaseResults

Table Methods
radsqliteTableIfExists
radsqliteTableCreate
radsqliteTableDelete
radsqliteTableTruncate
radsqliteTableDescriptionGet
radsqliteTableQueryRow
radsqliteTableInsertRow
radsqliteTableModifyRows
radsqliteTableDeleteRows

Result Set Methods
radsqliteResultsGetFirst
radsqliteResultsGetNext
radsqliteResultsGetPrev
radsqliteResultsGetLast

Row Description Methods
radsqliteRowDescriptionCreate
radsqliteRowDescriptionAddField
radsqliteRowDescriptionRemoveField
radsqliteRowDescriptionDelete

Field Manipulation Methods
radsqliteFieldGet
radsqliteFieldGetType
radsqliteFieldGetBigIntValue
radsqliteFieldGetDoubleValue
radsqliteFieldGetCharValue
radsqliteFieldGetCharLength
radsqliteFieldSetTypeBigInt
radsqliteFieldSetTypeDouble
radsqliteFieldSetTypeChar
radsqliteFieldSetToNull
radsqliteFieldSetToNotNull
radsqliteFieldSetBigIntValue
radsqliteFieldSetDoubleValue
radsqliteFieldSetCharValue


Stacks (First In-Last Out) (radstack.h)

Stacks are implemented as a special case of the radlist utility. STACK_NODEs should be included as the first element of object definitions (structures) in the same way NODEs are for the list utility.

radStackInit
radStackExit
radStackPush
radStackPop
radStackCount


State Machines (radstates.h)

State machines are composed of an array of state handlers and a mechanism to "stimulate" the current state. State transitions occur when the current state's handler returns a new state value. The return value of a given state handler is thus stored as the new current state. The use of radStatesSetState is strongly discouraged, except to set the initial state during initialization.

radStatesInit
radStatesExit
radStatesAddHandler
radStatesRemHandler
radStatesProcess
radStatesSetState
radStatesGetState
radStatesReset


radlib System Control (radsystem.h)

This utility prepares radlib system facilities so that radProcessInit can be invoked. By specifying a system ID to these functions, it allows unrelated radlib "systems" (sets of processes) to run concurrently.

radSystemInit
radSystemExit
radSystemGetUpTimeMS
radSystemGetUpTimeSEC
radSystemGetUpTimeSTR


radlib System Utilities (radsysutils.h)

radUtilsSetIntervalTimer
radUtilsGetIntervalTimer
radUtilsEnableSignal
radUtilsDisableSignal
radUtilsBecomeDaemon
radUtilsSleep


Red-Black Text Search (radtextsearch.h)

This utility provides fast text string search given a well-known set of text strings (the universe). An ordinal value is stored with each text string in a red-black binary tree. Once the tree is populated with the universe of possible text strings and corresponding ordinal values, the find method can be used to retrieve the corresponding ordinal if a matching text string is found.

radtextsearchInit
radtextsearchExit
radtextsearchInsert
radtextsearchRemove
radtextsearchFind


Thread Utilities (radthread.h)

Provide a uniform way to create and destroy utility threads from radlib processes.

Communication between the parent and thread can be accomplished in three ways:
1) Using the radthread internal queues via radthreadSendToThread, radthreadReceiveFromThread, radthreadSendToParent, raddthreadReceiveFromParent.
2) If the parent is using radProcessWait to receive messages and wait on file descriptor IO, the producer threads can use radMsgRouterMessageSend to send data to the Consumer (parent). The parent thread must have registered with radMsgRouterInit and for the message the thread sends via radMsgRouterMessageRegister. The thread can send messages not intended for the parent process as well.
3) Modifying shared data directly. Parents and threads should use the radthreadLock and radthreadUnlock functions if modifying any shared data. This should be done with great caution. In particular, radMsgRouterMessageSend locks and unlocks the thread mutex directly so the mutex cannot be held when calling it.

All threads should periodically test for an exit request from the parent using the radthreadShouldExit function. Parents calling radthreadWaitExit will block until the thread terminates. If the parent needs to know when the thread exits, the thread should send a message via radMsgRouterMessageSend to indicate it is exiting.

Parent Actions:
radthreadCreate
radthreadWaitExit
radthreadSendToThread
radthreadReceiveFromThread

Thread Actions:
radthreadSendToParent
radthreadReceiveFromParent
radthreadShouldExit

Parent or Thread Actions:
radthreadLock
radthreadUnlock


Timers (radtimers.h)

radTimerListCreate
radTimerListDelete
radTimerCreate
radTimerDelete
radTimerStart
radTimerStop
radTimerStatus
radTimerSetUserParm


Time Utilities (radtimeutils.h)

radTimeGetMSSinceEpoch
radTimeGetSECSinceEpoch


UDP Datagram Sockets (radUDPsocket.h)

radUDPSocketCreate
radUDPSocketDestroy
radUDPSocketGetDescriptor
radUDPSocketBind
radUDPSocketSetBroadcast
radUDPSocketSetMulticastTXInterface
radUDPSocketSetMulticastTTL
radUDPSocketSetMulticastLoopback
radUDPSocketAddMulticastMembership
radUDPSocketDropMulticastMembership
radUDPSocketRecvFrom
radUDPSocketSendTo
radUDPSocketSetBlocking
radUDPSocketSetDebug





Descriptions



radBuffersInit()

int radBuffersInit (int minBufferSize, int maxBufferSize, int *numberOfEachSize)


Description

Called from process initialization (normally by radSystemInit). Not normally called directly by application methods. Creates the system buffer pool.

Return Value

OK or ERROR

Notes

radSemProcessInit must be called before this method (also usually called from radSystemInit).

Parameters

Type Name Description
int minBufferSize smallest buffer size in the pool
int maxBufferSize largest buffer size in pool
int * numberOfEachSize array of buffer counts


radBufferGet()

void *radBufferGet (int size);


Description

Request a system buffer of size "size".

Return Value

The buffer pointer or NULL if none available.

Notes

 

Parameters

Type Name Description
int size The length in bytes of the buffer requested


radBufferRls()

int radBufferRls (void *buffer);


Description

Release a system buffer back into the free pool.

Return Value

OK or ERROR

Notes

 

Parameters

Type Name Description
void * buffer Buffer pointer obtained from a successful radBufferGet call.


radBuffersExit()

void radBuffersExit (void);


Description

Detach from the system buffer pool. Does NOT destroy the system buffer pool. Not normally called from application methods (called from radSystemExit).

Return Value

None



radBuffersExitAndDestroy()

void radBuffersExitAndDestroy (void);


Description

Detach from the system buffer pool. DOES mark the system buffer pool for destroy. Not normally called from application methods (called from radSystemExit).



radBuffersGetTotal()

ULONG radBuffersGetTotal (void);


Description

Retrieve the total number of buffers (all sizes, free and allocated) in the system.

Return Value

The total free and allocated buffers in the system.



radBuffersGetAvailable()

ULONG radBuffersGetAvailable (void);


Description

Retrieve the number of available (free) buffers in the system.

Return Value

The number of free buffers of any size in the system.



radCfOpen()

CF_ID radCfOpen (char *file);


Description

Creates a lock on the file, opens the given config file, creating local record keeping about the file. If the file does not already exist, a new file is created. Returns the CF_ID or NULL indicating an error. The file will remain locked until radCfClose is called.

Return Value

If successful, a valid CF_ID to be used with all subsequent radCF methods. NULL is returned if there is an error.

Notes

This function reads the entire file into a RAM copy for use by the rest of the radCF utilities. Any changes made to the config file via these methods will NOT take effect until the application calls radCfFlush!

Parameters

Type Name Description
char * file Full path name of the config file


radCfClose()

void radCfClose (CF_ID file);


Description

Releases the lock on the file, closes the file and cleans up local information about it.

Return Value

None

Parameters

Type Name Description
CF_ID file radCF ID


radCfFlush()

int radCfFlush (CF_ID file);


Description

Flushes the file to disk.

Return Value

OK or ERROR

Notes

This call MUST be made for any changes to config files to be saved to the disk file itself.

Parameters

Type Name Description
CF_ID file radCF ID


radCfPutComment()

int radCfPutComment (CF_ID file, char *text);


Description

Creates a comment line at the end of the config file.

Return Value

OK or ERROR

Parameters

Type Name Description
CF_ID file radCF ID
char * text Text string to add as a comment


radCfPutCommentBefore()

int radCfPutCommentBefore (CF_ID file, char *id, char *instance, char *commentText);


Description

Inserts a comment before the given entry.

Return Value

OK or ERROR

Parameters

Type Name Description
CF_ID file radCF ID
char * id ID value string
char * instance Instance string (can be NULL)
char * commentText Text string to add as a comment


radCfIsCommentBefore()

int radCfIsCommentBefore (CF_ID file, char *id, char *instance, char *commentText);


Description

Checks for a comment before the given entry.

Return Value

TRUE or FALSE

Parameters

Type Name Description
CF_ID file radCF ID
char * id ID value string
char * instance Instance string (can be NULL)
char * commentText Text string to add as a comment


radCfIsCommentAfter()

int radCfIsCommentAfter (CF_ID file, char *id, char *instance, char *commentText);


Description

Checks for a comment after the given entry.

Return Value

TRUE or FALSE

Parameters

Type Name Description
CF_ID file radCF ID
char * id ID value string
char * instance Instance string (can be NULL)
char * commentText Text string to add as a comment


radCfGetFirstEntry()

int radCfGetFirstEntry (CF_ID file, char *id, char *instance, char *value);


Description

Retrieves the first entry for a particular ID. instance and value are both filled with the appropriate information when an entry is found.

Return Value

OK or ERROR

Parameters

Type Name Description
CF_ID file radCF ID
char * id ID value string
char * instance Instance string (can be NULL)
char * value Value string if found


radCfGetNextEntry()

int radCfGetNextEntry (CF_ID file, char *id, char *instance, char *value);


Description

Gets the next entry for a particular ID. instance and value are both filled with the appropriate information when a new entry is found.

Return Value

OK or ERROR

Parameters

Type Name Description
CF_ID file radCF ID
char * id ID value string
char * instance Instance string (can be NULL)
char * value Value string if found


radCfGetEntry()

int radCfGetEntry (CF_ID file, char *id, char *instance, char *value);


Description

Retrieves a particular config file entry specified by the "id" and "instance" inputs.

Return Value

OK or ERROR

Parameters

Type Name Description
CF_ID file radCF ID
char * id ID value string
char * instance Instance string (can be NULL)
char * commentText Value string if found


radCfPutEntry()

int radCfPutEntry (CF_ID file, char *id, char *instance, char *value, char *comment);


Description

Creates/Updates a configuration entry in the file given the id, instance, and value. New entries will be placed at the end of the file.

Return Value

OK or ERROR

Parameters

Type Name Description
CF_ID file radCF ID
char * id ID value string
char * instance Instance string (can be NULL)
char * value Value string
char * comment Comment string


radCRC16Calculate()

USHORT radCRC16Calculate (void *block, int byteLength);


Description

Calculate the 16-bit CRC-CCITT for the given memory block.

Return Value

The USHORT CRC value.

Notes

The 16-bit CRC uses the standard CCITT polynomial: x^16+x^12+x^5+1. Uses "all bits set" as the seed value, i.e. 0xFFFF.

Parameters

Type Name Description
void * block memory block to calculate the 16 bit CRC over
int byteLength byte length of the memory block


radCRC32Calculate()

ULONG radCRC32Calculate (void *block, int byteLength);


Description

Calculate the 32-bit CRC-CCITT for the given memory block.

Return Value

The ULONG CRC value.

Notes

The 32-bit CRC uses the standard polynomial: x^32+x^26+x^23+x^22+x^16+x^12+x^11+x^10+x^8+x^7+x^5+x^4+x^2+x+1. Uses "all bits set" as the seed value, i.e. 0xFFFFFFFF.

Parameters

Type Name Description
void * block memory block to calculate the 16 bit CRC over
int byteLength byte length of the memory block


raddatabaseOpen()

DATABASE_ID raddatabaseOpen
(
const char *host,
const char *username,
const char *password,
const char *dbName
);


Description

Connect to a database server.

Return Value

Returns the DATABASE_ID or NULL

Notes

The database (dbName), user (userName), password (password) and access permissions for the database must be setup in the database server prior to use by the radlib database utilities.

Parameters

Type Name Description
const char * host FQDN or IP address of database server; if NULL, 'localhost' is used
const char * userName database username (cannot be NULL)
const char * password database user password (cannot be NULL)
const char * dbName database name - if NULL, no specific database is opened and all tableNames in calls below MUST be of the form 'dbName.tableName'


raddatabaseClose()

void raddatabaseClose
(
DATABASE_ID dbId
);


Description

Close the connection to a database server.

Return Value

None

Parameters

Type Name Description
DATABASE_ID dbId Value returned from successful raddatabaseOpen call


raddatabaseQuery()

int raddatabaseQuery
(
DATABASE_ID dbId,
const char *query,
int createResults
);


Description

Issue an SQL query to the database server.

Return Value

Returns OK or ERROR if there is a db server error, query error, or 'createResults' is set to TRUE and no result set is generated by the 'query'.

Notes

If results are generated it can be VERY slow and eat up a lot of heap space; the good news is that once the RESULT_SET_ID is retrieved using raddatabaseTableGetResults, it can persist as long as the user needs to keep it without adverse effects on the database server or the radlib host system.

Parameters

Type Name Description
DATABASE_ID dbId Value returned from successful raddatabaseOpen call
const char * query Well-formed SQL query statement
int createResults flag indicating if a result set should be generated


raddatabaseGetResults()

RESULT_SET_ID raddatabaseGetResults
(
DATABASE_ID dbId
);


Description

Retrieve the result set (if there is one) - should be called immediately after raddatabaseTableQuery if the query was intended to generate a result set (SELECT, SHOW, etc.).

Return Value

Returns RESULT_SET_ID or NULL

Notes

RESULT_SET_ID should be released via raddatabaseTableResultsRelease once the user is finished with it.

Parameters

Type Name Description
DATABASE_ID dbId Value returned from successful raddatabaseOpen call


raddatabaseRefreshResults()

RESULT_SET_ID raddatabaseRefreshResults
(
DATABASE_ID dbId,
RESULT_SET_ID origResultSet
);


Description

Refresh a result set based on the original query.

Return Value

Returns RESULT_SET_ID or NULL

Notes

RESULT_SET_ID should be released via raddatabaseTableResultsRelease once the user is finished with it.

Parameters

Type Name Description
DATABASE_ID dbId Value returned from successful raddatabaseOpen call
RESULT_SET_ID origResultSet original result set returned by raddatabaseGetResults


raddatabaseReleaseResults()

void raddatabaseReleaseResults
(
DATABASE_ID dbId,
RESULT_SET_ID resultSet
);


Description

Release a result set.

Return Value

None

Parameters

Type Name Description
DATABASE_ID dbId Value returned from successful raddatabaseOpen call
RESULT_SET_ID resultSet result set returned by raddatabaseGetResults


raddatabaseTableIfExists()

int raddatabaseTableIfExists
(
DATABASE_ID dbId,
const char tableName );


Description

Does 'tableName' table exist?

Return Value

Returns TRUE or FALSE

Notes

If raddatabaseOpen was called with a NULL database name, then this and all references to tableName in this API should be of the form 'Database.tableName'.

Parameters

Type Name Description
DATABASE_ID dbId Value returned from successful raddatabaseOpen call
const char * tableName name of table to check for existence


raddatabaseTableCreate()

int raddatabaseTableCreate
(
DATABASE_ID dbId,
const char *tableName,
ROW_ID rowDescription /* see raddatabaseRowDescriptionCreate */
);


Description

Create a table named 'tableName'.

Return Value

Returns OK or ERROR

Parameters

Type Name Description
DATABASE_ID dbId Value returned from successful raddatabaseOpen call
const char * tableName name of table to be created
ROW_ID rowDescription describes the row structure for the new table (see raddatabaseRowDescriptionCreate)


raddatabaseTableDelete()

int raddatabaseTableDelete
(
DATABASE_ID dbId,
const char *tableName
);


Description

Drop the table named 'tableName'.

Return Value

Returns OK or ERROR

Parameters

Type Name Description
DATABASE_ID dbId Value returned from successful raddatabaseOpen call
const char * tableName name of table to be deleted


raddatabaseTableTruncate()

int raddatabaseTableTruncate
(
DATABASE_ID dbId,
const char *tableName
);


Description

Truncate (empty) the table named 'tableName'.

Return Value

Returns OK or ERROR

Parameters

Type Name Description
DATABASE_ID dbId Value returned from successful raddatabaseOpen call
const char * tableName name of table to be truncated


raddatabaseTableDescriptionGet()

ROW_ID raddatabaseTableDescriptionGet
(
DATABASE_ID dbId,
const char *tableName


Description

Create a row description to use for row insertion/retrieval.

Return Value

Returns ROW_ID or NULL

Notes

The ROW_ID must be deleted with raddatabaseRowDescriptionDelete after the user is finished with it. Sets the FIELD_VALUE_IS_NULL bit in field->type for all fields - this means the user must clear this bit for field values to be used in queries/insertions/deletions (see the raddatabaseFieldSetXXXValue functions, which clear the FIELD_VALUE_IS_NULL bit for you).

Parameters

Type Name Description
DATABASE_ID dbId Value returned from successful raddatabaseOpen call
const char * tableName retrieve the row description for this table


raddatabaseTableQueryRow()

RESULT_SET_ID raddatabaseTableQueryRow
(
DATABASE_ID dbId,
const char *tableName,
ROW_ID rowDescription
);


Description

Query a table to create a result set given a row description.

Return Value

Returns RESULT_SET_ID or NULL

Notes

Columns to be included in the result set should have FIELD_DISPLAY set in the appropriate FIELD_ID.type within 'rowDescription'; columns NOT to be included in the WHERE clause should have FIELD_VALUE_IS_NULL set in FIELD_ID.type; fields in the where clause are 'ANDed' together. Can be slow and eat up a lot of heap space - the good news is that once the RESULT_SET_ID is retrieved, it can persist as long as the user needs to keep it without adverse effects on the db server or the radlib host. RESULT_SET_ID should be released via raddatabaseTableResultsRelease once the user is finished with it. Only the populated fields in 'rowDescription' will be used to match records in the table (i.e., multiple rows can be matched).

Parameters

Type Name Description
DATABASE_ID dbId Value returned from successful raddatabaseOpen call
const char * tableName table to query
ROW_ID rowDescription description with fields of interest populated


raddatabaseTableInsertRow()

int raddatabaseTableInsertRow
(
DATABASE_ID dbId,
const char *tableName,
ROW_ID rowId
);


Description

Insert a row into a table.

Return Value

Returns OK or ERROR

Notes

'rowId' is created with raddatabaseTableDescriptionGet then field values were populated with raddatabaseFieldGet, raddatabaseFieldSetXXXValue, etc. prior to this call. If a 'NOT NULL' field in the table has a NULL value in rowId, it's an error.

Parameters

Type Name Description
DATABASE_ID dbId Value returned from successful raddatabaseOpen call
const char * tableName table to insert the row into
ROW_ID rowId row description with fields of interest populated


raddatabaseTableModifyRows()

int raddatabaseTableModifyRows
(
DATABASE_ID dbId,
const char *tableName,
ROW_ID matchId,
ROW_ID newData
);


Description

Modify rows in 'tableName' matching 'matchId' with the field values defined in 'newData'.

Return Value

Returns OK or ERROR

Notes

Only the non-NULL fields in 'matchId' will be used to match records in the table (i.e., multiple rows can be matched). All fields in 'newData' will be updated in the rows which match 'matchId'- if a NULL value is given for a NOT NULL field in the table it is an error. Thus if you don't want to modify a column value, remove it from the 'newData' row desription with raddatabaseRowDescriptionRemoveField.

Parameters

Type Name Description
DATABASE_ID dbId Value returned from successful raddatabaseOpen call
const char * tableName table to modify
ROW_ID matchId row description with fields to match populated
ROW_ID newData row description with ONLY fields to be modified present


raddatabaseTableDeleteRows()

int raddatabaseTableDeleteRows
(
DATABASE_ID id
);


Description

Delete rows in 'tableName' matching 'matchId'.

Return Value

Returns OK or ERROR

Notes

Only the non-NULL fields will be used to match records in the table (i.e., multiple rows can be matched).

Parameters

Type Name Description
DATABASE_ID dbId Value returned from successful raddatabaseOpen call
ROW_ID matchId row description with fields to match populated


raddatabaseResultsGetFirst()

ROW_ID raddatabaseResultsGetFirst
(
RESULT_SET_ID id
);


Description

Retrieve the first row of a result set.

Return Value

Returns ROW_ID or NULL if the result set is empty

Notes

Allows traversal of the rows in a result set.

Parameters

Type Name Description
RESULT_SET_ID id result set obtained from raddatabaseGetResults or raddatabaseTableQueryRow


raddatabaseResultsGetNext()

ROW_ID raddatabaseResultsGetNext
(
RESULT_SET_ID id
);


Description

Retrieve the next row of a result set.

Return Value

Returns ROW_ID or NULL if there is no next row

Notes

Allows traversal of the rows in a result set.

Parameters

Type Name Description
RESULT_SET_ID id result set obtained from raddatabaseGetResults or raddatabaseTableQueryRow


raddatabaseResultsGetPrev()

ROW_ID raddatabaseResultsGetPrev
(
RESULT_SET_ID id
);


Description

Retrieve the previous row of a result set.

Return Value

Returns ROW_ID or NULL if there is no previous row

Notes

Allows traversal of the rows in a result set.

Parameters

Type Name Description
RESULT_SET_ID id result set obtained from raddatabaseGetResults or raddatabaseTableQueryRow


raddatabaseResultsGetLast()

ROW_ID raddatabaseResultsGetLast
(
RESULT_SET_ID id
);


Description

Retrieve the last row of a result set.

Return Value

Returns ROW_ID or NULL if the result set is empty

Notes

Allows traversal of the rows in a result set.

Parameters

Type Name Description
RESULT_SET_ID id result set obtained from raddatabaseGetResults or raddatabaseTableQueryRow


raddatabaseRowDescriptionCreate()

ROW_ID raddatabaseRowDescriptionCreate
(
void
);


Description

Create an empty row description to use when describing a new table.

Return Value

Returns ROW_ID or NULL

Notes

ROW_ID should be released via raddatabaseRowDescriptionDelete once the user is finished with it.



raddatabaseRowDescriptionAddField()

int raddatabaseRowDescriptionAddField
(
ROW_ID id,
const char *name,
UINT type,
int maxLength
);


Description

Add a new field to a row description.

Return Value

Returns OK or ERROR

Parameters

Type Name Description
ROW_ID id Value returned from successful raddatabaseRowDescriptionCreate call
const char * name name of the field to add
UINT type type of field to add (see radatabase.h)
int maxLength maximum length of field to add if it is a string


raddatabaseRowDescriptionRemoveField()

int raddatabaseRowDescriptionRemoveField
(
ROW_ID id,
const char *name
);


Description

Remove a field identified by 'name' from the row description.

Return Value

Returns OK or ERROR

Parameters

Type Name Description
ROW_ID id Value returned from successful raddatabaseRowDescriptionCreate call
const char * name name of field to be removed


raddatabaseRowDescriptionDelete()

void raddatabaseRowDescriptionDelete
(
ROW_ID id
);


Description

Release a row description and the corresponding fields.

Return Value

None

Parameters

Type Name Description
ROW_ID id Value returned from successful raddatabaseRowDescriptionCreate call


raddatabaseFieldGet()

FIELD_ID raddatabaseFieldGet
(
ROW_ID id,
const char *fieldName
);


Description

Get the field identified by 'fieldName'.

Return Value

Returns FIELD_ID or NULL

Parameters

Type Name Description
ROW_ID id valid row description ID
const char * fieldName name of field to retrieve


raddatabaseFieldGetType()

UINT raddatabaseFieldGetType
(
DATABASE_ID id
);


Description

Retrieve the field type bitmask (see raddatabase.h).

Return Value

Returns the field type bitmask

Notes

enum DbFieldTypes
{
FIELD_INT = 0x00000001,
FIELD_STRING = 0x00000002,
FIELD_BIGINT = 0x00000004,
FIELD_FLOAT = 0x00000008,
FIELD_DOUBLE = 0x00000010,
FIELD_DATETIME = 0x00000020,
FIELD_TYPE_CLEAR = 0xFF000000, /* used to clear field type only */
FIELD_VALUE_IS_NULL = 0x80000000, /* for queries & results only */
FIELD_DISPLAY = 0x40000000 /* for queries only */
};

Parameters

Type Name Description
FIELD_ID id valid field ID to retrieve type from


raddatabaseFieldGetIntValue()

int raddatabaseFieldGetIntValue
(
FIELD_ID id
);


Description

Retrieve the integer value of the field (must be of type FIELD_INT).

Return Value

Returns the value

Parameters

Type Name Description
FIELD_ID id field to extract value from


raddatabaseFieldGetBigIntValue()

long long raddatabaseFieldGetBigIntValue
(
FIELD_ID id
);


Description

Retrieve the big integer value of the field (must be of type FIELD_BIGINT).

Return Value

Returns the value

Parameters

Type Name Description
FIELD_ID id field to extract value from


raddatabaseFieldGetFloatValue()

float raddatabaseFieldGetFloatValue
(
FIELD_ID id
);


Description

Retrieve the float value of the field (must be of type FIELD_FLOAT).

Return Value

Returns the value

Parameters

Type Name Description
FIELD_ID id field to extract value from


raddatabaseFieldGetDoubleValue()

double raddatabaseFieldGetDoubleValue
(
DATABASE_ID id
);


Description

Retrieve the double value of the field (must be of type FIELD_DOUBLE).

Return Value

Returns the value

Parameters

Type Name Description
FIELD_ID id field to extract value from


raddatabaseFieldGetTimeDateValue()

char *raddatabaseFieldGetTimeDateValue
(
FIELD_ID id
);


Description

Retrieve the DATETIME value of the field (must be of type FIELD_DATETIME).

Return Value

Returns the value

Parameters

Type Name Description
FIELD_ID id field to extract value from


raddatabaseFieldGetCharValue()

char *raddatabaseFieldGetCharValue
(
FIELD_ID id
);


Description

Retrieve the string value of the field (must be of type FIELD_STRING).

Return Value

Returns the value

Parameters

Type Name Description
FIELD_ID id field to extract value from


raddatabaseFieldGetCharLength()

int raddatabaseFieldGetCharLength
(
FIELD_ID id
);


Description

Retrieve the string length of the field (must be of type FIELD_STRING).

Return Value

Returns the value

Parameters

Type Name Description
FIELD_ID id field to extract value from


raddatabaseFieldSetTypeInt()

int raddatabaseFieldSetTypeInt
(
FIELD_ID id
);


Description

Set the field type to FIELD_INT.

Return Value

Returns OK

Parameters

Type Name Description
FIELD_ID id valid field ID


raddatabaseFieldSetTypeBigInt()

int raddatabaseFieldSetTypeBigInt
(
FIELD_ID id
);


Description

Set the field type to FIELD_BIGINT.

Return Value

Returns OK

Parameters

Type Name Description
FIELD_ID id valid field ID


raddatabaseFieldSetTypeFloat()

int raddatabaseFieldSetTypeFloat
(
FIELD_ID id
);


Description

Set the field type to FIELD_FLOAT.

Return Value

Returns OK

Parameters

Type Name Description
FIELD_ID id valid field ID


raddatabaseFieldSetTypeDouble()

int raddatabaseFieldSetTypeDouble
(
FIELD_ID id
);


Description

Set the field type to FIELD_DOUBLE.

Return Value

Returns OK

Parameters

Type Name Description
FIELD_ID id valid field ID


raddatabaseFieldSetTypeDateTime()

int raddatabaseFieldSetTypeDateTime
(
FIELD_ID id
);


Description

Set the field type to FIELD_DATETIME.

Return Value

Returns OK

Parameters

Type Name Description
FIELD_ID id valid field ID


raddatabaseFieldSetTypeChar()

int raddatabaseFieldSetTypeChar
(
FIELD_ID id
);


Description

Set the field type to FIELD_STRING.

Return Value

Returns OK

Parameters

Type Name Description
FIELD_ID id valid field ID


raddatabaseFieldSetToNull()

int raddatabaseFieldSetToNull
(
FIELD_ID id
);


Description

Set the field flag to NULL (empty).

Return Value

Returns OK

Parameters

Type Name Description
FIELD_ID id valid field ID


raddatabaseFieldSetToNotNull()

int raddatabaseFieldSetToNotNull
(
FIELD_ID id
);


Description

Set the field flag to NOT NULL (not empty).

Return Value

Returns OK

Parameters

Type Name Description
FIELD_ID id valid field ID


raddatabaseFieldSetIntValue()

int raddatabaseFieldSetIntValue
(
FIELD_ID id,
int value
);


Description

Set the integer field value.

Return Value

Returns OK

Parameters

Type Name Description
FIELD_ID id valid field ID
int value value to set


raddatabaseFieldSetBigIntValue()

int raddatabaseFieldSetBigIntValue
(
FIELD_ID id,
long long value
);


Description

Set the big integer field value.

Return Value

Returns OK

Parameters

Type Name Description
FIELD_ID id valid field ID
long long value value to set


raddatabaseFieldSetFloatValue()

int raddatabaseFieldSetFloatValue
(
FIELD_ID id,
float value
);


Description

Set the float field value.

Return Value

Returns OK

Parameters

Type Name Description
FIELD_ID id valid field ID
float value value to set


raddatabaseFieldSetDoubleValue()

int raddatabaseFieldSetDoubleValue
(
FIELD_ID id,
double value
);


Description

Set the double field value.

Return Value

Returns OK

Parameters

Type Name Description
FIELD_ID id valid field ID
double value value to set


raddatabaseFieldSetDateTimeValue()

int raddatabaseFieldSetDateTimeValue
(
FIELD_ID id,
const char *value,
int valueLength
);


Description

Set the DATETIME field value.

Return Value

Returns OK

Parameters

Type Name Description
FIELD_ID id valid field ID
const char * value value to set
int valueLength string length of value to set


raddatabaseFieldSetCharValue()

int raddatabaseFieldSetCharValue
(
FIELD_ID id,
const char *value,
int valueLength
);


Description

Set the string field value.

Return Value

Returns OK

Parameters

Type Name Description
FIELD_ID id valid field ID
const char * value value to set
int valueLength string length of value to set


radEventsInit()

EVENTS_ID radEventsInit
(
T_QUEUE_ID queueId,
UINT initialEvents,
void (*evtCallback) (UINT eventsRx, UINT data, void *parm),
void *userParm
);


Description

Initialize events processing for this process - called once by each process (usually from radProcessInit). evtCallback will be called when an event(s) is signaled.

Return Value

Returns the valid EVENTS_ID or NULL

Notes

Events require an initialized message queue to deliver events.

Parameters

Type Name Description
T_QUEUE_ID queueId Valid queue ID for this process
UINT initialEvents Initial event mask of enabled events
void (*) evtCallback Callback function used to deliver events
void * userParm Data pointer delivered with events - use this to store work pointers for event processing


radEventsExit()

void radEventsExit (EVENTS_ID id);


Description

Exits the events processing for this process. Usually called from radProcessExit.

Return Value

None

Parameters

Type Name Description
EVENTS_ID id Valid events system ID


radEventsAdd()

int radEventsAdd (EVENTS_ID id, UINT newEvents);


Description

Add events to the receive mask.

Return Value

OK or ERROR

Notes

The receive mask is NOT replaced with this new mask but rather bitwise OR'd with the given mask.

Parameters

Type Name Description
EVENTS_ID id Valid events system ID
UINT newEvents mask of new events to "add"


radEventsRemove()

int radEventsRemove (EVENTS_ID id, UINT remEvents);


Description

Remove events from the receive mask.

Return Value

OK or ERROR

Notes

The receive mask is NOT replaced with this new mask but rather bitwise AND'd with the compliment of the remEvents.

Parameters

Type Name Description
EVENTS_ID id Valid events system ID
UINT remEvents mask of events to "remove"


radEventsGetMask()

UINT radEventsGetMask (EVENTS_ID id);


Description

Retrieve the current receive event mask. These are the events which, when received, will be delivered to the callback handler.

Return Value

The current receive event mask.

Parameters

Type Name Description
EVENTS_ID id Valid events system ID


radEventsSend()

int radEventsSend (EVENTS_ID id, char *destQName, UINT eventsToSend, UINT data);


Description

Send an event(s) to another process by queue name.

Return Value

OK or ERROR

Notes

If radProcessInit was initialized and destName == NULL, sends the events to the calling process.

Parameters

Type Name Description
EVENTS_ID id Valid events system ID
char * destQName Queue name of the destination process
UINT eventsToSend Event mask of events to send
UINT data Data to be delivered with the events


radEventsProcess()

int radEventsProcess (EVENTS_ID id, UINT eventsRx, UINT data);


Description

This routine should be called with the result mask of a received event "message". It is usually only called directly by radProcessWait.

Return Value

OK or ERROR

Parameters

Type Name Description
EVENTS_ID id Valid events system ID
UINT eventsRx Received events mask
UINT data Received event data


radListCreate()

RADLIST_ID radListCreate (void);


Description

Dynamically creates a RADLIST structure and initializes it to empty.

Return Value

If successful, a valid RADLIST_ID to be used with all subsequent list methods. NULL is returned if there is an error.



radListReset()

RADLIST_ID radListReset (RADLIST_ID list);


Description

Initializes the given list to empty.

Return Value

The RADLIST_ID passed in.

Parameters

Type Name Description
RADLIST_ID list list to initialize


radListDelete()

void radListDelete (RADLIST_ID list);


Description

Deletes the memory associated with a dynamically allocated list. This should not be called if the list was allocated statically (i.e., declared as type RADLIST).

Return Value

None

Parameters

Type Name Description
RADLIST_ID id list ID to be destroyed


radListInsertAfter()

void radListInsertAfter
(
RADLIST_ID list,
NODE_PTR afterThisOne, /* NULL inserts at front */
NODE_PTR node
);


Description

Inserts the new object referenced by node after the object referenced by afterThisOne.

Return Value

None

Notes

afterThisOne must already be in the list. List nodes CANNOT be inserted on multiple lists.

Parameters

Type Name Description
RADLIST_ID list List ID of interest
NODE_PTR afterThisOne Existing list node to insert after
NODE_PTR node New node to insert into the list


radListInsertBefore()

void radListInsertBefore
(
RADLIST_ID list,
NODE_PTR beforeThisOne, /* NULL inserts at front */
NODE_PTR node
);


Description

Inserts the new object referenced by node before the object referenced by beforeThisOne.

Return Value

None

Notes

beforeThisOne must already be in the list. List nodes CANNOT be inserted on multiple lists.

Parameters

Type Name Description
RADLIST_ID list List ID of interest
NODE_PTR beforeThisOne Existing list node to insert before
NODE_PTR node New node to insert into the list


radListAddToFront()

void radListAddToFront
(
RADLIST_ID list,
NODE_PTR node
);


Description

Inserts the new object referenced by node at the front of the list.

Return Value

None

Parameters

Type Name Description
RADLIST_ID list List ID of interest
NODE_PTR node New node to insert into the list


radListAddToEnd()

void radListAddToEnd
(
RADLIST_ID list,
NODE_PTR node
);


Description

Inserts the new object referenced by node at the end of the list.

Return Value

None

Parameters

Type Name Description
RADLIST_ID list List ID of interest
NODE_PTR node New node to insert into the list


radListRemove()

void radListRemove
(
RADLIST_ID list,
NODE_PTR removeThisOne
);


Description

Removes the node referenced by removeThisOne from the list.

Return Value

None

Parameters

Type Name Description
RADLIST_ID list List ID of interest
NODE_PTR removeThisOne Node to remove from the list


radListRemoveFirst()

NODE_PTR radListRemoveFirst
(
RADLIST_ID list
);


Description

Removes the first node from the list.

Return Value

If the list was not empty, the NODE_PTR of the first node is returned, otherwise NULL

Parameters

Type Name Description
RADLIST_ID list List ID of interest


radListRemoveLast()

NODE_PTR radListRemoveLast
(
RADLIST_ID list
);


Description

Removes the last node from the list.

Return Value

If the list was not empty, the NODE_PTR of the last node is returned, otherwise NULL

Parameters

Type Name Description
RADLIST_ID list List ID of interest


radListGetNumberOfNodes()

int radListGetNumberOfNodes
(
RADLIST_ID list
);


Description

Retrieves the number of nodes on the list.

Return Value

The number of nodes

Parameters

Type Name Description
RADLIST_ID list List ID of interest


radListGetFirst()

NODE_PTR radListGetFirst
(
RADLIST_ID list
);


Description

Retrieves the first node on the list. Does not remove it from the list.

Return Value

If the list is not empty, the first node on the list, otherwise NULL

Parameters

Type Name Description
RADLIST_ID list List ID of interest


radListGetLast()

NODE_PTR radListGetLast
(
RADLIST_ID list
);


Description

Retrieves the last node on the list. Does not remove the node from the list.

Return Value

If the list is not empty, the last node on the list, otherwise NULL

Parameters

Type Name Description
RADLIST_ID list List ID of interest


radListGetNext()

NODE_PTR radListGetNext
(
RADLIST_ID list,
NODE_PTR afterThisOne /* NULL => listGetFirst */
);


Description

Retrieves the node after the node referenced by afterThisOne from the list. Does not remove the node from the list.

Return Value

If afterThisOne is not the last node on the list, the next node on the list, otherwise NULL

Notes

If afterThisOne is NULL, this call is the same as radListGetFirst.

Parameters

Type Name Description
RADLIST_ID list List ID of interest
NODE_PTR afterThisOne Node to retrieve after


radListGetPrevious()

NODE_PTR radListGetPrevious
(
RADLIST_ID list,
NODE_PTR beforeThisOne /* NULL => listGetLast */
);


Description

Retrieves the node before the node referenced by beforeThisOne from the list. Does not remove the node from the list.

Return Value

If beforeThisOne is not the first node on the list, the next node on the list, otherwise NULL

Notes

If beforeThisOne is NULL, this call is the same as radListGetLast.

Parameters

Type Name Description
RADLIST_ID list List ID of interest
NODE_PTR beforeThisOne Node to retrieve before


radMsgLogInit()

int radMsgLogInit
(
char *procName,
int useStderr,
int timeStamp
);


Description

Initializes logging for the calling process. Normally only called directly by radProcessInit.

Return Value

OK or ERROR

Parameters

Type Name Description
char * procName Process name to be displayed with messages
int useStderr If TRUE, will log to stderr as well as the system log
int timeStamp If TRUE, include millisecond timestamps with messages


radMsgLogExit()

int radMsgLogExit (void);


Description

Exits the calling process from system logging capabilities. Normally only called directly by radProcessExit.

Return Value

OK or ERROR



radMsgLog()

int radMsgLog (int priority, char *format, ...);


Description

Log a message - allow variable length parameter list.

Return Value

OK or ERROR

Parameters

Type Name Description
int priority PRI_STATUS, PRI_MEDIUM, ...
char * format format string ala printf
Variable Variable format arguments ala printf


radMsgLogData()

void radMsgLogData (void *data, int length);


Description

Log data in a pointer dumping style. Displays hex and ASCII in a tabular form to the syslog.

Return Value

None

Parameters

Type Name Description
void * data pointer to dump from
int length Length (in bytes) of data to dump


radMsgRouterInit()

int radMsgRouterInit (char *workingDir)


Description

Register the message router API for the calling process.

Return Value

OK or ERROR

Parameters

Type Name Description
char * workingDir specifies where the pid file and FIFOs for the message router process are maintained


radMsgRouterExit()

void radMsgRouterExit (void);


Description

Deregister the message router API for the calling process



radMsgRouterProcessExit()

void radMsgRouterExit (int pid);


Description

Deregister the message router API for "pid" process



radMsgRouterMessageRegister()

int radMsgRouterMessageRegister (ULONG msgID)


Description

Request to receive 'msgID' messages.

Return Value

OK or ERROR

Parameters

Type Name Description
ULONG msgID specifies the msgID to be received - '0' and '0xFFFFFFFF' are reserved


radMsgRouterMessageDeregister()

int radMsgRouterMessageDeregister (ULONG msgID)


Description

Request to stop receiving 'msgID' messages.

Return Value

OK or ERROR

Parameters

Type Name Description
ULONG msgID specifies the msgID to stop reception of - '0' and '0xFFFFFFFF' are reserved


radMsgRouterMessageIsRegistered()

int radMsgRouterMessageIsRegistered (ULONG msgID)


Description

Request if any consumers are registered for 'msgID' messages.

Return Value

TRUE or FALSE

Parameters

Type Name Description
ULONG msgID specifies the msgID to query - '0' and '0xFFFFFFFF' are reserved


radMsgRouterMessageSend()

int radMsgRouterMessageSend
(
ULONG msgID,
void *msg,
ULONG byteLength
);


Description

Send a message through the message router - all processes which have registered to receive 'msgID' will receive a copy of the message. 'msg' will be copied - ownership of 'msg' is NOT transferred but remains with the caller.

Return Value

OK or ERROR

Parameters

Type Name Description
ULONG msgID message ID to send
void * msg application message to send
ULONG byteLength byte length of 'msg'


radMsgRouterStatsDump()

void radMsgRouterStatsDump (void);


Description

Request the message router to dump statistics to the log file.



radmrouted Daemon Usage

USAGE: [prefix]/radmrouted radSystemID workingDirectory [listenPort] [remoteIP:remotePort]

radSystemID 1-255, same system ID used by other processes in this group workingDirectory where to store FIFO and pid files for radmrouted listenPort (optional) socket sever listen port to accept remote connections remoteIP:remotePort (optional) remote host IP:port to connect to


radProcessInit()

int radProcessInit
(
char *processName,
char *queueName,
int numTimers,
int runAsDaemon,
void (*messageHandler)
     (char *srcQueueName, UINT msgType, void *msg, UINT length, void *userData),
void (*eventHandler)
     (UINT eventsRx, UINT rxData, void *userData),
void *userData
);


Description

Initialize process management; called once during process initialization. Automatically sets up the following utilities for a new process:
Message Logging (radmsgLog.h)
Message Queue (radqueue.h)
IO processing (ala "select")
Timer List with 'numTimers' timers (radtimers.h)
Event handler (radevents.h)

Return Value

OK or ERROR

Notes

This function should be called after radSystemInit.

Parameters

Type Name Description
char * processName Name of the calling process
char * queueName Full path name of the queue for this process
int numTimers Determines the max number of timers for this process
BOOL runAsDaemon Determines if the process can have a controlling terminal and if msgLog's go to stderr or not
void (*) messageHandler The callback for queue messages
void (*) eventHandler The callback for events
void * userData Passed to the event and message callbacks


radProcessExit()

void radProcessExit (void);


Description

Exit from radlib process framework.

Return Value

None

Notes

This function should be called immediately before radSystemExit.



radProcessSetExitFlag()

void radProcessSetExitFlag (void);


Description

Set the internal exit flag. radProcessWait will dump out immediately once this is set.

Return Value

None



radProcessWait()

int radProcessWait (int timeout);


Description

Wait for messages, timers, events, and user IO blocks in one call. Blocks execution until input stimulus is available or timeout expires. This method should be the focal point of a process's main loop - often (and preferably) it is the only invocation in the main loop. If timeout (in milliseconds) is greater than 0, this function will return TIMEOUT even if no input stimulus triggered after timeout milliseconds.

Return Value

OK, ERROR, or TIMEOUT if timeout occurred

Parameters

Type Name Description
int timeout If 0, will wait indefinitely for input stimulus, otherwise will timeout after this number of milliseconds


radProcessGetName()

char *radProcessGetName (char *store);


Description

Get the calling process's name.

Return Value

Returns the store pointer, where the name is copied.

Parameters

Type Name Description
char * store Character pointer to valid memory where the name is copied


radProcessGetPid()

pid_t radProcessGetPid (void);


Description

Retrieve the calling process's pid (process ID).

Return Value

The calling process's pid



radProcessIORegisterDescriptor()

PROC_IO_ID radProcessIORegisterDescriptor
(
int fd,
void (*ioCallback) (int fd, void *userData),
void *userData
);


Description

Register a file descriptor for radProcessWait inclusion. ioCallback will be executed if data or an error occurs on fd. userData will be passed to ioCallback.

Return Value

PROC_IO_ID or ERROR

Parameters

Type Name Description
int fd File descriptor to add to radProcessWait list
void (*) ioCallback Function called when data or error occurs on fd
void * userData This pointer is passed into ioCallback when data occurs


radProcessIODeRegisterDescriptor()

int radProcessIODeRegisterDescriptor (PROC_IO_ID id);


Description

Deregister a file descriptor for radProcessWait inclusion.

Return Value

None

Parameters

Type Name Description
PROC_IO_ID id ID obtained during successful radProcessIORegisterDescriptor call


radProcessIORegisterSTDIN()

PROC_IO_ID radProcessIORegisterSTDIN
(
void (*ioCallback) (int fd, void *userData),
void *userData
);


Description

Register STDIN for radProcessWait inclusion. This is a special case of radProcessIORegisterDescriptor.

Return Value

PROC_IO_ID or ERROR

Parameters

Type Name Description
void (*) ioCallback Function called when data or error occurs on fd
void * userData Passed to ioCallback


radProcessSignalCatchAll()

int radProcessSignalCatchAll (void (*defaultHandler) (int signum));


Description

Initialize all signals (except SIGKILL and SIGSTOP) to be caught by defaultHandler.

Return Value

OK or ERROR

Parameters

Type Name Description
void (*) defaultHandler default signal handler


radProcessSignalCatch()

int radProcessSignalCatch (int signum, void (*handler) (int signum));


Description

Assign a specific handler to a specific signal (signum).

Return Value

OK or ERROR

Parameters

Type Name Description
int signum signal number
void (*) handler signal handler


radProcessSignalRelease()

int radProcessSignalRelease (int signum);


Description

Set signum back to the default system handler.

Return Value

OK or ERROR

Parameters

Type Name Description
int signum signal number


radProcessSignalIgnore()

int radProcessSignalIgnore (int signum);


Description

Set signum to be ignored when raised.

Return Value

OK or ERROR

Parameters

Type Name Description
int signum signal number


radProcessSignalGetHandler()

void (*(radProcessSignalGetHandler (int signum))) (int);


Description

Retrieve the current handler for signum.

Return Value

The function pointer or NULL

Parameters

Type Name Description
int signum signal number


radProcessQueueGetName()

char *radProcessQueueGetName (char *store);


Description

Retrieve calling process's queue name.

Return Value

Queue name (stored in store)

Parameters

Type Name Description
char * store where the queue name is copied


radProcessQueueAttach()

int radProcessQueueAttach (char *newName, int group);


Description

Attach to an individual queue based on queue name so messages can be sent to it.

Return Value

OK or ERROR

Parameters

Type Name Description
char * newName Queue name to attach to
int group Group number of the queue


radProcessQueueDettach()

int radProcessQueueDettach (char *oldName, int group);


Description

Detach from an individual queue based on queue name.

Return Value

OK or ERROR

Parameters

Type Name Description
char * oldName queue to detach from
int group Group number of queue


radProcessQueueJoinGroup()

int radProcessQueueJoinGroup (int groupNumber);


Description

Add calling process's queue to a group and add the group to calling process's address list.

Return Value

OK or ERROR

Parameters

Type Name Description
int groupNumber Group to join


radProcessQueueQuitGroup()

int radProcessQueueQuitGroup (int groupNumber);


Description

Remove calling process's queue from a group and remove a group from calling process's address list.

Return Value

OK or ERROR

Parameters

Type Name Description
int groupNumber Group to join


radProcessQueueSend()

int radProcessQueueSend (char *destQueue, UINT msgType, void *sysBuffer, UINT length);


Description

Write to a queue. Assumes sysBuffer is a valid pointer to a system buffer. System buffer ownership is transferred to the receiving queue.

Return Value

OK, ERROR, or ERROR_ABORT if the destination queue is gone

Notes

Calling process should detach from the destination queue on ERROR_ABORT.

Parameters

Type Name Description
char * destQueue destination queue name
UINT msgType application-defined message type to send
void * sysBuffer system buffer to send
UINT length length of message to send


radProcessQueueSendGroup()

int radProcessQueueSendGroup (int destGroup, UINT msgType, void *sysBuffer, UINT length);


Description

Write message to all queues in a group. Checks to make sure the group hasn't changed - if it has it refreshes the address list before sending. Assumes sysBuffer is a valid pointer to a system buffer.

Return Value

OK or ERROR

Notes

The system buffer is released if this call returns OK. Calling process must release if ERROR is returned.

Parameters

Type Name Description
int destGroup destination queue group
UINT msgType application-defined message type to send
void * sysBuffer system buffer to send
UINT length length of message to send


radProcessQueueIsAttached()

int radProcessQueueIsAttached (char *queueName);


Description

Determine if calling process is attached to the given queue name.

Return Value

TRUE or FALSE

Parameters

Type Name Description
char * queueName destination queue


radProcessQueueKeepBuffer()

void radProcessQueueKeepBuffer (void);


Description

ONLY called from inside a message queue handler to indicate that retention of the buffer is desired; if not called, the buffer will be released as usual after the last handler in the traversal list has been invoked. It is the caller's responsibility to free the buffer after assuming ownership of it.

Return Value

None



radProcessQueueStopHandlerList()

void radProcessQueueStopHandlerList (void);


Description

ONLY called from inside a message queue handler - if more than one message queue handler has been defined via 'radProcessQueuePrependHandler', then this function is used to indicate that the traversal of the handler list should stop when the calling handler returns (i.e., the calling handler "matches" the message received).

Return Value

None



radProcessQueuePrependHandler()

int radProcessQueuePrependHandler
(
void (*msgHandler) (char *srcQueueName, UINT msgType, void *msg, UINT length, void *userData)
);


Description

Prepend (insert at front) an additional message queue handler to the existing list of message handlers. This allows other utilities/objects/etc. to insert a message handler to process specific utility messages without the radlib application process having to have knowledge of those messages. This will not interrupt normal application message reception (although the utility/object doing the insertion should ensure that message types it is using do not conflict with the application message type definitions). This is completely backward compatible with existing radlib applications.

Return Value

A unique identifier > 0 that can be used to remove the message handler later (see 'radProcessQueueRemoveHandler') or ERROR

Parameters

Type Name Description
void (*) function pointer msgHandler message handler to be inserted at the front of the message handler list; should take arguments as described above


radProcessQueueRemoveHandler()

int radProcessQueueRemoveHandler (int handlerID);


Description

Remove a message queue handler from the existing list of message handlers. 'handlerID must be a valid return value from a previous call to 'radProcessQueuePrependHandler' (this implies the default handler provided in 'radProcessInit' CANNOT be removed).

Return Value

OK or ERROR

Parameters

Type Name Description
int handlerID a valid return value from a previous call to 'radProcessQueuePrependHandler'


radProcessTimerCreate()

TIMER_ID radProcessTimerCreate (TIMER_ID timer, void (*routine) (void *parm), void *parm);


Description

Create a timer on the process's timer list.

Return Value

TIMER_ID or NULL if there is an error

Parameters

Type Name Description
TIMER_ID timer If not NULL, will re-initialize the given timer instead of creating a new one (pass NULL to create new one)
void (*) routine timer callback routine
void * parm pointer to be passed to the callback routine


radProcessTimerDelete()

void radProcessTimerDelete (TIMER_ID timer);


Description

Delete the timer specified by timer.

Return Value

None

Parameters

Type Name Description
TIMER_ID timer timer to delete


radProcessTimerStart()

void radProcessTimerStart (TIMER_ID timer, int time);


Description

Start the timer.

Return Value

None

Parameters

Type Name Description
TIMER_ID timer timer to start
int time duration of timer in milliseconds


radProcessTimerStop()

void radProcessTimerStop (TIMER_ID timer);


Description

Stop a running timer before it expires.

Return Value

None

Parameters

Type Name Description
TIMER_ID timer timer to stop


radProcessTimerStatus()

int radProcessTimerStatus (TIMER_ID timer);


Description

Determine if the given timer is running.

Return Value

TRUE or FALSE

Parameters

Type Name Description
TIMER_ID timer timer to status


radProcessTimerSetUserParm()

void radProcessTimerSetUserParm (TIMER_ID timer, void *newParm);


Description

Reset the user parm (pointer passed to the callback) for a timer.

Return Value

None

Parameters

Type Name Description
TIMER_ID timer timer to modify
void * newParm new user parm


radProcessEventsAdd()

int radProcessEventsAdd (UINT newEvents);


Description

Add events to the receive mask (see radEventsAdd).

Return Value

OK or ERROR

Parameters

Type Name Description
UINT newEvents new events to receive


radProcessEventsRemove()

int radProcessEventsRemove (UINT removeEvents);


Description

Remove events from the receive mask.

Return Value

OK or ERROR

Parameters

Type Name Description
UINT removeEvents events to remove from the receive mask


radProcessEventsGetEnabled()

UINT radProcessEventsGetEnabled (void);


Description

Retrieve current receive mask.

Return Value

Receive mask



radProcessEventsSend()

int radProcessEventsSend (char *destName, UINT eventsToSend, UINT data);


Description

Send event(s) to the destination process with queue name destName.

Return Value

OK or ERROR

Notes

If radProcessInit was initialized and destName == NULL, sends the events to the calling process.

Parameters

Type Name Description
char * destName destination queue name
UINT eventsToSend events to send
UINT data event data to send


radPlistCreate()

PROC_LIST_ID radPlistCreate (char *parentName);


Description

Create a new, empty process list.

Return Value

PROC_LIST_ID or NULL

Parameters

Type Name Description
char * parentName Name of the parent process


radPlistDestroy()

int radPlistDestroy (PROC_LIST_ID plistId);


Description

Destroy an existing process list (will clean up nodes).

Return Value

OK or ERROR

Parameters

Type Name Description
PROC_LIST_ID plistId Process list ID to destroy


radPlistAdd()

int radPlistAdd
(
PROC_LIST_ID plistId,
int (*entry) (void *pargs),
void *args,
int priority
);


Description

Add a new "entry" into an existing process list.

Return Value

OK or ERROR

Notes

When spawned, "entry" must call radProcessInit and then must give the synchronization semaphore by calling radPlistProcessReady or the parent process will hang forever waiting on it to do so. This semaphore is used to synchronize the launching of multiple processes.

Parameters

Type Name Description
PROC_LIST_ID plistId Process list ID
int (*) entry Entry point of process to launch
void * args Argument pointer passed to "entry" when launched
int priority Value of 1 - 100 indicating desired start position (1 is first, 100 is last)


radPlistStart()

int radPlistStart (PROC_LIST_ID plistId);


Description

Start all process entries in an existing process list, ordered by priority (1 -> 100).

Return Value

OK or ERROR

Parameters

Type Name Description
PROC_LIST_ID plistId process list to start


radPlistGetNumberRunning()

int radPlistGetNumberRunning (PROC_LIST_ID plistId);


Description

Retrieve the number of running processes (after radPlistStart is called).

Return Value

The number of processes successfully started

Parameters

Type Name Description
PROC_LIST_ID plistId process list


radPlistExecByEntryPoint()

int radPlistExecByEntryPoint
(
PROC_LIST_ID plistId,
int (*entry) (void *pargs),
void (*execFunction) (pid_t pid, void *data),
void *data
);


Description

Execute a user-supplied function for the process specified by "entry" (after radPlistStart is called).

Return Value

OK or ERROR

Notes

This allows the parent process to execute a function on the process pid of the process previously started with entry point "entry".

Parameters

Type Name Description
PROC_LIST_ID plistId process list
int (*) entry entry point of the process of interest
void (*) execFunction Function to execute if process denoted by "entry" is found
void * data void pointer to user-supplied data, passed to "execFunction"


radPlistExecAll()

int radPlistExecAll
(
PROC_LIST_ID plistId,
void (*execFunction) (pid_t pid, void *data),
void *data
);


Description

Execute a user-supplied function for each running process in the process list (after radPlistStart is called).

Return Value

Count of affected processes or ERROR

Notes

This allows the parent process to execute a function on the process pid of each process in the process list.

Parameters

Type Name Description
PROC_LIST_ID plistId process list
void (*) execFunction Function to execute for each process in the list
void * data data pointer to pass to "execFunction"


radPlistAddPid()

int radPlistAddPid (PROC_LIST_ID plistId, pid_t pid);


Description

Add a process entry to the list (not starting it). This may be done when a process is started after radPlistStart has been called to keep the list up to date.

Return Value

OK or ERROR

Parameters

Type Name Description
PROC_LIST_ID plistId process list
pid_t pid process ID to add


radPlistRemovePid()

int radPlistRemovePid (PROC_LIST_ID plistId, pid_t pid);


Description

Remove a process entry from the list by pid. This may be done when it exits to keep the list up to date.

Return Value

OK or ERROR

Parameters

Type Name Description
PROC_LIST_ID plistId process list
pid_t pid process ID to remove


radPlistAddandStart()

int radPlistAddandStart
(
PROC_LIST_ID plistId,
int (*entry) (void *pargs),
void *args
);


Description

Add a process entry to the list and start it. This may be done when a process is started after radPlistStart has been called to keep the list up to date.

Return Value

OK or ERROR

Parameters

Type Name Description
PROC_LIST_ID plistId process list
int (*) entry entry point of process to add and start
void * args arg pointer to pass to "entry"


radPlistProcessReady()

int radPlistProcessReady (void);


Description

Signal to the parent process (from the newly started process) that initialization is complete and it is safe to start the next process.

Return Value

OK or ERROR

Notes

This method cannot be called until radProcessInit has been successfully called by the new process.



radPlistFindByEntryPoint()

int radPlistFindByEntryPoint
(
PROC_LIST_ID plistId,
int (*entry) (void *pargs)
);


Description

Find an entry's pid based on its entry point.

Return Value

The process pid if found or ERROR if not

Notes

This cannot be called until radProcessInit has been successfully called by the new process.

Parameters

Type Name Description
PROC_LIST_ID plistId process list
int (*) entry entry point of process to find


radStartProcess()

int radStartProcess
(
int (*entryPoint) (void * pargs),
void *args
);


Description

Start a new process by forking.

Return Value

The new child pid or ERROR

Notes

Usually only invoked directly by radPlist functions.

Parameters

Type Name Description
int (*) entryPoint entry point of process to start
void * args args to pass to the new process


radQueueSystemInit()

int radQueueSystemInit (int initFlag);


Description

Initialize the process queue global constructs for this process. If initFlag is TRUE, the global table will be initialized too.

Return Value

OK or ERROR

Notes

Usually only invoked directly by radSystemInit. Must be called prior to radQueueInit.

Parameters

Type Name Description
int initFlag specify if the global table should be initialized


radQueueSystemExit()

void radQueueSystemExit (int destroy);


Description

Exit the process attachment to the queue global constructs. If destroy is TRUE, the global table will be destroyed.

Return Value

None

Notes

Usually only invoked directly by radSystemExit.

Parameters

Type Name Description
int destroy specify if the global table should be destroyed


radQueueInit()

T_QUEUE_ID radQueueInit (char *queueName, int startDummyProc);


Description

Create a message queue for the calling process. List the caller's new queue in the global queue list with the QUEUE_GROUP_ALL group.

Return Value

T_QUEUE_ID or NULL

Notes

Usually only invoked directly by radProcessInit. radQueueSystemInit must be called before this function.

Parameters

Type Name Description
char * queueName full path name of desired process queue


radQueueExit()

void radQueueExit (T_QUEUE_ID id);


Description

Exit (detach from) the global queue table.

Return Value

None

Notes

Usually only invoked directly by radProcessExit.

Parameters

Type Name Description
T_QUEUE_ID id queue ID


radQueueGetFD()

int radQueueGetFD
(
T_QUEUE_ID id
);


Description

Get the queue file descriptor to use in select or poll calls.

Return Value

The file descriptor

Notes

Usually only invoked directly by radProcessInit.

Parameters

Type Name Description
T_QUEUE_ID id queue ID


radQueueGetName()

char *radQueueGetName (T_QUEUE_ID tqid, char *store);


Description

Return the full path of the calling process's queue.

Return Value

A pointer to store, which has been updated with the queue name

Notes

store must be large enough to hold a file path.

Parameters

Type Name Description
T_QUEUE_ID id queue ID
char * store where to copy the result (must point to valid memory)


radQueueAttach()

int radQueueAttach (T_QUEUE_ID tqid, char *newName, int group);


Description

Attach to an individual queue based on queue name so that messages can be sent to it.

Return Value

OK or ERROR

Parameters

Type Name Description
T_QUEUE_ID id queue ID
char * newName full path to the queue to be attached
int group group number to attach through


radQueueDettach()

int radQueueDettach (T_QUEUE_ID tqid, char *oldName, int group);


Description

Detach from an individual queue based on queue name and group number.

Return Value

OK or ERROR

Parameters

Type Name Description
T_QUEUE_ID id queue ID
char * newName full path to the queue to be attached
int group group number to attach through


radQueueJoinGroup()

int radQueueJoinGroup (T_QUEUE_ID tqid, int groupNumber);


Description

Add calling process's queue to a group and add the group to calling process's address list.

Return Value

OK or ERROR

Parameters

Type Name Description
T_QUEUE_ID id queue ID
int groupNumber group number to join


radQueueQuitGroup()

int radQueueQuitGroup (T_QUEUE_ID tqid, int groupNumber);


Description

Remove calling process's queue from a group and remove a group from calling process's address list.

Return Value

OK or ERROR

Parameters

Type Name Description
T_QUEUE_ID id queue ID
int groupNumber group number to quit


radQueueRecv()

int radQueueRecv
(
T_QUEUE_ID tqid,
char *srcQueueName,
UINT *msgType,
void **msg,
UINT *length
);


Description

Read from message queue - populates srcQueueName, msg, length, and msgType.

Return Value

TRUE if msg received, FALSE if queue is empty, ERROR if error

Notes

msg will point to a system buffer when this call returns TRUE. User MUST call radBufferRls when done with buffer! This is usually only invoked directly by radProcessWait, which will take care of buffer releases.

Parameters

Type Name Description
T_QUEUE_ID id queue ID
char * srcQueueName A pointer to valid memory which will receive the name of the sending queue if a message is present
UINT * msgType A pointer to valid memory (UINT) which will receive the message type if a message is present
void ** msg The address of a void pointer which will receive the pointer to the system buffer if a message is present
UINT * length A pointer to valid memory (UINT) which will receive the length of the message if a message is present


radQueueSend()

int radQueueSend
(
T_QUEUE_ID tqid,
char *destQueueName,
UINT msgType,
void *sysBuffer,
UINT length
);


Description

Write a message to a queue.

Return Value

OK, ERROR, or ERROR_ABORT if the destination queue is gone

Notes

Assumes sysBuffer is a valid pointer to a system buffer. System buffer ownership is transferred to the receiving queue. User should detach from a destination queue if ERROR_ABORT is returned.

Parameters

Type Name Description
T_QUEUE_ID id queue ID
char * destQueueName Name of destination queue
UINT msgType Message type of message to send
void * sysBuffer System buffer containing message to send
UINT length Length of the message to send


radQueueSendGroup()

int radQueueSendGroup
(
T_QUEUE_ID tqid,
int destGroup,
UINT msgType,
void *sysBuffer,
UINT length
);


Description

Send to all queues in a group - checks to make sure the group hasn't changed - if it has it refreshes the address list before sending.

Return Value

OK or ERROR

Notes

Assumes sysBuffer is a valid pointer to a system buffer. sysBuffer is released if this call returns OK, otherwise, the calling process must release the sysBuffer on ERROR.

Parameters

Type Name Description
T_QUEUE_ID id queue ID
int destGroup Group number to send to
UINT msgType Message type of message to send
void * sysBuffer System buffer containing message to send
UINT length Length of the message to send


radQueueIsAttached()

int radQueueIsAttached (T_QUEUE_ID tqid, char *queueName);


Description

Determine if calling process is attached to the given queue name.

Return Value

TRUE or FALSE

Parameters

Type Name Description
T_QUEUE_ID id queue ID
char * queueName queue name to check status of


radSemProcessInit()

int radSemProcessInit (void);


Description

Called once during process initialization (usually from radSystemInit). Creates or attaches to an existing semaphore set.

Return Value

OK or ERROR

Notes

Usually only invoked directly by radSystemInit.



radSemSetDestroy()

void radSemSetDestroy (void);


Description

Called globally once to destroy a semaphore set (usually from radSystemExit).

Return Value

None

Notes

Usually only invoked directly by radSystemExit.



radSemCreate()

SEM_ID radSemCreate (int semIndex, int count);


Description

Create (or attach to) a specific indexed semaphore.

Return Value

SEM_ID or NULL

Parameters

Type Name Description
int semIndex semaphore index within the global semaphore set (1 - MAX_SEMAPHORES)
int count Indicates the initial value of the sem (0 or 1 for mutex). count less than 0 will leave the semaphore's count value undisturbed - (i.e. when it already exists)


radSemTake()

void radSemTake (SEM_ID id);


Description

Take (decrement) a semaphore. If the semaphore count is 0 when this function is called, the calling process will block until the semaphore count is incremented (via radSemGive).

Return Value

None

Parameters

Type Name Description
SEM_ID id semaphore ID


radSemGive()

void radSemGive (SEM_ID id);


Description

Give (increment) a semaphore's count. If other processes are blocked on the semaphore, this will cause one of them to unblock and run.

Return Value

None

Parameters

Type Name Description
SEM_ID id semaphore ID


radSemGiveMultiple()

void radSemGiveMultiple (SEM_ID id, int numToGive);


Description

Give multiple (increment by numToGive) a semaphore's count. One or more blocked processes will be unblocked.

Return Value

None

Parameters

Type Name Description
SEM_ID id semaphore ID
int numToGive value to increment the semaphore count by


radSemTest()

int radSemTest (SEM_ID id);


Description

Test a semaphore to see if it is free (unlocked), if so, take (decrement) the semaphore. If it is locked (count = 0), just return FALSE.

Return Value

TRUE if the semaphore was taken by this call (decremented), FALSE if the semaphore count is 0

Parameters

Type Name Description
SEM_ID id semaphore ID


radSemDelete()

int radSemDelete (SEM_ID id);


Description

Release a semaphore allocation.

Return Value

OK or ERROR

Parameters

Type Name Description
SEM_ID id semaphore ID


radSemDebug()

void radSemDebug (void);


Description

Dump semaphore set information to stdout.

Return Value

None

Notes

For debug use only.



radSHA1ComputeBlock()

int radSHA1ComputeBlock
(
void *block,
int byteLength,
char digestStore[RADSHA1_DIGEST_STR_LENGTH]
);


Description

Compute the SHA-1 digest for the memory block 'block' of byte length 'byteLength' and store the result in 'digestStore'.

Return Value

OK or ERROR

Parameters

Type Name Description
void * block pointer to memory block to compute the SHA-1 digest over
int byteLength byte length of the block
char * digestStore character array of size >= RADSHA1_DIGEST_STR_LENGTH where the resulting digest is returned


radSHA1ComputeFile()

int radSHA1ComputeFile
(
char *filename,
char digestStore[RADSHA1_DIGEST_STR_LENGTH]
);


Description

Compute the SHA-1 digest for the file given by full path and filename 'filename' and store the result in 'digestStore'.

Return Value

OK or ERROR

Parameters

Type Name Description
char * filename full path and name of file to compute the SHA-1 digest over
char * digestStore character array of size >= RADSHA1_DIGEST_STR_LENGTH where the resulting digest is returned


radSHA256ComputeBlock()

int radSHA256ComputeBlock
(
void *block,
int byteLength,
char digestStore[RADSHA256_DIGEST_STR_LENGTH]
);


Description

Compute the SHA-256 digest for the memory block 'block' of byte length 'byteLength' and store the result in 'digestStore'.

Return Value

OK or ERROR

Parameters

Type Name Description
void * block pointer to memory block to compute the SHA-256 digest over
int byteLength byte length of the block
char * digestStore character array of size >= RADSHA256_DIGEST_STR_LENGTH where the resulting digest is returned


radSHA256ComputeFile()

int radSHA256ComputeFile
(
char *filename,
char digestStore[RADSHA256_DIGEST_STR_LENGTH]
);


Description

Compute the SHA-256 digest for the file given by full path and filename 'filename' and store the result in 'digestStore'.

Return Value

OK or ERROR

Parameters

Type Name Description
char * filename full path and name of file to compute the SHA-256 digest over
char * digestStore character array of size >= RADSHA256_DIGEST_STR_LENGTH where the resulting digest is returned


radShmemIfExist()

int radShmemIfExist (int key);


Description

Called from a process to test a shared memory block for existence.

Return Value

TRUE if it exists or FALSE if it doesn't

Parameters

Type Name Description
int key Unique 32-bit key value which identifies a shared memory block across process boundaries


radShmemInit()

SHMEM_ID radShmemInit (int key, int semIndex, int size);


Description

Allocate or attach to existing shared memory block.

Return Value

SHMEM_ID or NULL

Parameters

Type Name Description
int key Unique 32-bit key value which identifies a shared memory block across process boundaries
int semIndex Unique semaphore index used globally to provide mutual exclusion for the shared memory block
int size size in bytes of the shared memory block


radShmemGet()

void *radShmemGet (SHMEM_ID id);


Description

Get the pointer to the beginning of the shared block as it is represented in the calling process's virtual memory map.

Return Value

the pointer or NULL

Parameters

Type Name Description
SHMEM_ID id shared memory ID


radShmemLock()

void radShmemLock (SHMEM_ID id);


Description

Lock the shared memory block for exclusive access. Can block execution if another process has the block locked.

Return Value

None

Parameters

Type Name Description
SHMEM_ID id shared memory ID


radShmemUnlock()

void radShmemUnlock (SHMEM_ID id);


Description

Unlock a shared memory block.

Return Value

None

Parameters

Type Name Description
SHMEM_ID id shared memory ID


radShmemExit()

void radShmemExit (SHMEM_ID id);


Description

Detach from a shared memory block. Does not destroy it.

Return Value

None

Parameters

Type Name Description
SHMEM_ID id shared memory ID


radShmemExitAndDestroy()

void radShmemExitAndDestroy (SHMEM_ID id);


Description

Detach from and destroy the shared memory block.

Return Value

None

Notes

This marks the shared memory for destruction once the last process has detached from it. No new processes will be able to attach it once this call is made.

Parameters

Type Name Description
SHMEM_ID id shared memory ID


radSocketServerCreate()

RADSOCK_ID radSocketServerCreate (int port);


Description

Create a socket server to listen on port "port".

Return Value

RADSOCK_ID or NULL if there is an error

Notes

This provides the "Server" side of the Client-Server paradigm. Once created, the user will need to add the listen socket file descriptor (obtained via radSocketGetDescriptor) to your FD_SET to wait for connect notifications on the listen socket. New connections are completed by use of radSocketServerAcceptConnection, which accepts the connection and prepares the new socket for read/write activity.

Parameters

Type Name Description
int port TCP port number to listen for connections on


radSocketServerAcceptConnection()

RADSOCK_ID radSocketServerAcceptConnection (RADSOCK_ID listenServerID);


Description

Create a new socket instance for the incoming connection and prepare it for read/write activity.

Return Value

The new RADSOCK_ID for the client connection or NULL if there is an error

Notes

Should be called when there is a "wake up" on the listen socket indicating an incoming connection attempt.

Parameters

Type Name Description
RADSOCK_ID listenServerID Valid listen socket ID obtained from a successful call to radSocketServerCreate


radSocketClientCreate()

RADSOCK_ID radSocketClientCreate (char *hostNameOrIP, int port);


Description

Create a socket client that connects to "hostNameOrIP" on port "port". Once connected, prepares the socket for read/write activity.

Return Value

The new RADSOCK_ID or NULL if there is an error

Notes

This provides the "Client" side of the Client-Server paradigm.

Parameters

Type Name Description
char * hostNameOrIP Host name or IP address of the socket server to be connected
int port Port the socket server is listening on


radSocketClientCreateAny()

RADSOCK_ID radSocketClientCreateAny (char *hostNameOrIP, int port);


Description

Create a socket client that connects to "hostNameOrIP" on port "port". if "hostNameOrIP" resolves to multiple IP addresses (via getaddrinfo), each IP address will be tried until a connection is achieved in the order received from getaddrinfo; Once connected, prepares the socket for read/write activity.

Return Value

The new RADSOCK_ID or NULL if there is an error

Notes

This provides the "Client" side of the Client-Server paradigm.

Parameters

Type Name Description
char * hostNameOrIP Host name or IP address of the socket server to be connected
int port Port the socket server is listening on


radSocketDestroy()

int radSocketDestroy (RADSOCK_ID id);


Description

Close connection and cleanup resources.

Return Value

OK or ERROR

Parameters

Type Name Description
RADSOCK_ID id Valid socket ID obtained from a successful call to radSocketServerCreate, radSocketServerAcceptConnection or radSocketClientCreate


radSocketGetDescriptor()

int radSocketGetDescriptor (RADSOCK_ID id);


Description

Get the socket descriptor (for select calls, etc.).

Return Value

The socket descriptor associated with "id".

Parameters

Type Name Description
RADSOCK_ID id Valid socket ID obtained from a successful call to radSocketServerCreate, radSocketServerAcceptConnection or radSocketClientCreate


radSocketGetHost()

char *radSocketGetHost (RADSOCK_ID id);


Description

Get the socket hostname or IP.

Return Value

The hostname or IP address associated with "id".

Parameters

Type Name Description
RADSOCK_ID id Valid socket ID obtained from a successful call to radSocketServerCreate, radSocketServerAcceptConnection or radSocketClientCreate


radSocketGetPort()

int radSocketGetPort (RADSOCK_ID id);


Description

Get the socket hostname or IP.

Return Value

The socket port number associated with "id".

Notes

For listen sockets this is the listen port. For accepted client connections on a server this is the local port of the client connection. For pure client connections this is the local port of the connection.

Parameters

Type Name Description
RADSOCK_ID id Valid socket ID obtained from a successful call to radSocketServerCreate, radSocketServerAcceptConnection or radSocketClientCreate


radSocketReadExact()

int radSocketReadExact
(
RADSOCK_ID id,
void *buffer,
int lengthToRead
);


Description

Read an exact size (will block if a blocking socket).

Return Value

Bytes read or ERROR if an error occurs.

Notes

Will return less than requested amount if a non-blocking socket and the read would block or it is interrupted by a received signal.

Parameters

Type Name Description
RADSOCK_ID id Valid socket ID obtained from a successful call to radSocketServerCreate, radSocketServerAcceptConnection or radSocketClientCreate
void * buffer User buffer pointing to valid memory of size >= "lengthToRead" bytes where data is written
int lengthToRead Bytes to read


radSocketWriteExact()

int radSocketWriteExact
(
RADSOCK_ID id,
void *buffer,
int lengthToWrite
);


Description

Write an exact size (will block if a blocking socket).

Return Value

Bytes written or ERROR if an error occurs.

Notes

Will return less than requested amount if a non-blocking socket and the write would block or it is interrupted by a received signal.

Parameters

Type Name Description
RADSOCK_ID id Valid socket ID obtained from a successful call to radSocketServerCreate, radSocketServerAcceptConnection or radSocketClientCreate
void * buffer User buffer pointing to the data to be written
int lengthToWrite Bytes to write


radSocketSetBlocking()

int radSocketSetBlocking
(
RADSOCK_ID id,
int isBlocking
);


Description

Set the socket for blocking or non-blocking IO.

Return Value

OK or ERROR

Notes

By default, all socket types are created in blocking IO mode. It is the user's responsibility to handle blocking/non-blocking IO properly (EAGAIN and EINTR errno's). Non-blocking should NOT be set for server (listen) sockets.

Parameters

Type Name Description
RADSOCK_ID id Valid socket ID obtained from a successful call to radSocketServerAcceptConnection or radSocketClientCreate
int isBlocking Boolean indicating if the socket should be set to non-blocking (non-zero value) or blocking IO (0 value, default)


radSocketSetDebug()

void radSocketSetDebug
(
RADUDPSOCK_ID id,
int enable
);


Description

Turn on or off data debug which dumps all read/write data to radMsgLog.

Return Value

N/A

Notes

If enabled, debug will radMsgLog the contents of all RX/TX data.

Parameters

Type Name Description
RADSOCK_ID id Valid socket ID obtained from a successful call to radSocketCreate
int enable Boolean indicating if the debug dumping of RX/TX datagrams should be enabled or disabled


radSortListInit()

SORTLIST_ID radSortListInit (int (*getKey)(void *data));


Description

Create a sorted list. The getKey function should return an "ordinal" value given a pointer to the list node - this is used to sort the list. If getKey is NULL, this will use the address of the NODE_PTR (not very useful!) This allows the calling process to specify "how" to sort the elements of the list through the getKey function.

Return Value

SORTLIST_ID or NULL

Parameters

Type Name Description
int (*) getKey application-supplied sorting function


radSortListExit()

void radSortListExit (SORTLIST_ID id);


Description

This WILL free all nodes on the sorted list before destroying the list.

Return Value

None

Parameters

Type Name Description
SORTLIST_ID id sorted list ID


radSortListInsert()

int radSortListInsert (SORTLIST_ID id, NODE_PTR node);


Description

Insert node into the list (see radList for details on NODE_PTR type).

Return Value

OK or ERROR

Parameters

Type Name Description
SORTLIST_ID id sorted list ID
NODE_PTR node object to be inserted (in order) into the list


radSortListRemove()

int radSortListRemove (SORTLIST_ID id, NODE_PTR node);


Description

Find and remove the node given the NODE_PTR.

Return Value

OK or ERROR

Parameters

Type Name Description
SORTLIST_ID id sorted list ID
NODE_PTR node object pointer to remove


radSortListFind()

NODE_PTR radSortListFind (SORTLIST_ID id, int key);


Description

Find a NODE_PTR given the "ordinal" or "key" of the node.

Return Value

The NODE_PTR or NULL

Parameters

Type Name Description
SORTLIST_ID id sorted list ID
int key the ordinal value (as determined by getKey) of the object to find


radsqliteOpen()

DATABASE_ID radsqliteOpen
(
const char *dbFilePath
);


Description

Connect to a database server.

Return Value

Returns the DATABASE_ID or NULL

Parameters

Type Name Description
const char * dbFilePath Full path and name of the SQLite database file


radsqliteClose()

void radsqliteClose
(
DATABASE_ID dbId
);


Description

Close the connection to a database file.

Return Value

None

Parameters

Type Name Description
DATABASE_ID dbId Value returned from successful radsqliteOpen call


radsqliteQuery()

int radsqliteQuery
(
DATABASE_ID dbId,
const char *query,
int createResults
);


Description

Issue an SQL query against the database.

Return Value

Returns OK or ERROR if there is a db error, query error, or 'createResults' is set to TRUE and no result set is generated by the 'query'.

Notes

If results are generated it can be VERY slow and eat up a lot of heap space; the good news is that once the RESULT_SET_ID is retrieved using radsqliteTableGetResults, it can persist as long as the user needs to keep it without adverse effects on the database server or the radlib host system.

Parameters

Type Name Description
DATABASE_ID dbId Value returned from successful radsqliteOpen call
const char * query Well-formed SQL query statement
int createResults flag indicating if a result set should be generated


radsqliteGetResults()

RESULT_SET_ID radsqliteGetResults
(
DATABASE_ID dbId
);


Description

Retrieve the result set (if there is one) - should be called immediately after radsqliteTableQuery if the query was intended to generate a result set (SELECT, SHOW, etc.).

Return Value

Returns RESULT_SET_ID or NULL

Notes

RESULT_SET_ID should be released via radsqliteTableResultsRelease once the user is finished with it.

Parameters

Type Name Description
DATABASE_ID dbId Value returned from successful radsqliteOpen call


radsqliteRefreshResults()

RESULT_SET_ID radsqliteRefreshResults
(
DATABASE_ID dbId,
RESULT_SET_ID origResultSet
);


Description

Refresh a result set based on the original query.

Return Value

Returns RESULT_SET_ID or NULL

Notes

RESULT_SET_ID should be released via radsqliteTableResultsRelease once the user is finished with it.

Parameters

Type Name Description
DATABASE_ID dbId Value returned from successful radsqliteOpen call
RESULT_SET_ID origResultSet original result set returned by radsqliteGetResults


radsqliteReleaseResults()

void radsqliteReleaseResults
(
DATABASE_ID dbId,
RESULT_SET_ID resultSet
);


Description

Release a result set.

Return Value

None

Parameters

Type Name Description
DATABASE_ID dbId Value returned from successful radsqliteOpen call
RESULT_SET_ID resultSet result set returned by radsqliteGetResults


radsqliteTableIfExists()

int radsqliteTableIfExists
(
DATABASE_ID dbId,
const char tableName );


Description

Does 'tableName' table exist?

Return Value

Returns TRUE or FALSE

Parameters

Type Name Description
DATABASE_ID dbId Value returned from successful radsqliteOpen call
const char * tableName name of table to check for existence


radsqliteTableCreate()

int radsqliteTableCreate
(
DATABASE_ID dbId,
const char *tableName,
ROW_ID rowDescription /* see radsqliteRowDescriptionCreate */
);


Description

Create a table named 'tableName'.

Return Value

Returns OK or ERROR

Parameters

Type Name Description
DATABASE_ID dbId Value returned from successful radsqliteOpen call
const char * tableName name of table to be created
ROW_ID rowDescription describes the row structure for the new table (see radsqliteRowDescriptionCreate)


radsqliteTableDelete()

int radsqliteTableDelete
(
DATABASE_ID dbId,
const char *tableName
);


Description

Drop the table named 'tableName'.

Return Value

Returns OK or ERROR

Parameters

Type Name Description
DATABASE_ID dbId Value returned from successful radsqliteOpen call
const char * tableName name of table to be deleted


radsqliteTableTruncate()

int radsqliteTableTruncate
(
DATABASE_ID dbId,
const char *tableName
);


Description

Truncate (empty) the table named 'tableName'.

Return Value

Returns OK or ERROR

Parameters

Type Name Description
DATABASE_ID dbId Value returned from successful radsqliteOpen call
const char * tableName name of table to be truncated


radsqliteTableDescriptionGet()

ROW_ID radsqliteTableDescriptionGet
(
DATABASE_ID dbId,
const char *tableName


Description

Create a row description to use for row insertion/retrieval.

Return Value

Returns ROW_ID or NULL

Notes

The ROW_ID must be deleted with radsqliteRowDescriptionDelete after the user is finished with it. Sets the FIELD_VALUE_IS_NULL bit in field->type for all fields - this means the user must clear this bit for field values to be used in queries/insertions/deletions (see the radsqliteFieldSetXXXValue functions, which clear the FIELD_VALUE_IS_NULL bit for you).

Parameters

Type Name Description
DATABASE_ID dbId Value returned from successful radsqliteOpen call
const char * tableName retrieve the row description for this table


radsqliteTableQueryRow()

RESULT_SET_ID radsqliteTableQueryRow
(
DATABASE_ID dbId,
const char *tableName,
ROW_ID rowDescription
);


Description

Query a table to create a result set given a row description.

Return Value

Returns RESULT_SET_ID or NULL

Notes

Columns to be included in the result set should have FIELD_DISPLAY set in the appropriate FIELD_ID.type within 'rowDescription'; columns NOT to be included in the WHERE clause should have FIELD_VALUE_IS_NULL set in FIELD_ID.type; fields in the where clause are 'ANDed' together. Can be slow and eat up a lot of heap space - the good news is that once the RESULT_SET_ID is retrieved, it can persist as long as the user needs to keep it without adverse effects on the db server or the radlib host. RESULT_SET_ID should be released via radsqliteTableResultsRelease once the user is finished with it. Only the populated fields in 'rowDescription' will be used to match records in the table (i.e., multiple rows can be matched).

Parameters

Type Name Description
DATABASE_ID dbId Value returned from successful radsqliteOpen call
const char * tableName table to query
ROW_ID rowDescription description with fields of interest populated


radsqliteTableInsertRow()

int radsqliteTableInsertRow
(
DATABASE_ID dbId,
const char *tableName,
ROW_ID rowId
);


Description

Insert a row into a table.

Return Value

Returns OK or ERROR

Notes

'rowId' is created with radsqliteTableDescriptionGet then field values were populated with radsqliteFieldGet, radsqliteFieldSetXXXValue, etc. prior to this call. If a 'NOT NULL' field in the table has a NULL value in rowId, it's an error.

Parameters

Type Name Description
DATABASE_ID dbId Value returned from successful radsqliteOpen call
const char * tableName table to insert the row into
ROW_ID rowId row description with fields of interest populated


radsqliteTableModifyRows()

int radsqliteTableModifyRows
(
DATABASE_ID dbId,
const char *tableName,
ROW_ID matchId,
ROW_ID newData
);


Description

Modify rows in 'tableName' matching 'matchId' with the field values defined in 'newData'.

Return Value

Returns OK or ERROR

Notes

Only the non-NULL fields in 'matchId' will be used to match records in the table (i.e., multiple rows can be matched). All fields in 'newData' will be updated in the rows which match 'matchId'- if a NULL value is given for a NOT NULL field in the table it is an error. Thus if you don't want to modify a column value, remove it from the 'newData' row desription with radsqliteRowDescriptionRemoveField.

Parameters

Type Name Description
DATABASE_ID dbId Value returned from successful radsqliteOpen call
const char * tableName table to modify
ROW_ID matchId row description with fields to match populated
ROW_ID newData row description with ONLY fields to be modified present


radsqliteTableDeleteRows()

int radsqliteTableDeleteRows
(
DATABASE_ID id
);


Description

Delete rows in 'tableName' matching 'matchId'.

Return Value

Returns OK or ERROR

Notes

Only the non-NULL fields will be used to match records in the table (i.e., multiple rows can be matched).

Parameters

Type Name Description
DATABASE_ID dbId Value returned from successful radsqliteOpen call
ROW_ID matchId row description with fields to match populated


radsqliteResultsGetFirst()

ROW_ID radsqliteResultsGetFirst
(
RESULT_SET_ID id
);


Description

Retrieve the first row of a result set.

Return Value

Returns ROW_ID or NULL if the result set is empty

Notes

Allows traversal of the rows in a result set.

Parameters

Type Name Description
RESULT_SET_ID id result set obtained from radsqliteGetResults or radsqliteTableQueryRow


radsqliteResultsGetNext()

ROW_ID radsqliteResultsGetNext
(
RESULT_SET_ID id
);


Description

Retrieve the next row of a result set.

Return Value

Returns ROW_ID or NULL if there is no next row

Notes

Allows traversal of the rows in a result set.

Parameters

Type Name Description
RESULT_SET_ID id result set obtained from radsqliteGetResults or radsqliteTableQueryRow


radsqliteResultsGetPrev()

ROW_ID radsqliteResultsGetPrev
(
RESULT_SET_ID id
);


Description

Retrieve the previous row of a result set.

Return Value

Returns ROW_ID or NULL if there is no previous row

Notes

Allows traversal of the rows in a result set.

Parameters

Type Name Description
RESULT_SET_ID id result set obtained from radsqliteGetResults or radsqliteTableQueryRow


radsqliteResultsGetLast()

ROW_ID radsqliteResultsGetLast
(
RESULT_SET_ID id
);


Description

Retrieve the last row of a result set.

Return Value

Returns ROW_ID or NULL if the result set is empty

Notes

Allows traversal of the rows in a result set.

Parameters

Type Name Description
RESULT_SET_ID id result set obtained from radsqliteGetResults or radsqliteTableQueryRow


radsqliteRowDescriptionCreate()

ROW_ID radsqliteRowDescriptionCreate
(
void
);


Description

Create an empty row description to use when describing a new table.

Return Value

Returns ROW_ID or NULL

Notes

ROW_ID should be released via radsqliteRowDescriptionDelete once the user is finished with it.



radsqliteRowDescriptionAddField()

int radsqliteRowDescriptionAddField
(
ROW_ID id,
const char *name,
UINT type,
int maxLength
);


Description

Add a new field to a row description.

Return Value

Returns OK or ERROR

Parameters

Type Name Description
ROW_ID id Value returned from successful radsqliteRowDescriptionCreate call
const char * name name of the field to add
UINT type type of field to add (see radatabase.h)
int maxLength maximum length of field to add if it is a string


radsqliteRowDescriptionRemoveField()

int radsqliteRowDescriptionRemoveField
(
ROW_ID id,
const char *name
);


Description

Remove a field identified by 'name' from the row description.

Return Value

Returns OK or ERROR

Parameters

Type Name Description
ROW_ID id Value returned from successful radsqliteRowDescriptionCreate call
const char * name name of field to be removed


radsqliteRowDescriptionDelete()

void radsqliteRowDescriptionDelete
(
ROW_ID id
);


Description

Release a row description and the corresponding fields.

Return Value

None

Parameters

Type Name Description
ROW_ID id Value returned from successful radsqliteRowDescriptionCreate call


radsqliteFieldGet()

FIELD_ID radsqliteFieldGet
(
ROW_ID id,
const char *fieldName
);


Description

Get the field identified by 'fieldName'.

Return Value

Returns FIELD_ID or NULL

Parameters

Type Name Description
ROW_ID id valid row description ID
const char * fieldName name of field to retrieve


radsqliteFieldGetType()

UINT radsqliteFieldGetType
(
DATABASE_ID id
);


Description

Retrieve the field type bitmask (see radsqlite.h).

Return Value

Returns the field type bitmask

Notes

enum DbFieldTypes
{
FIELD_STRING = 0x00000001,
FIELD_BIGINT = 0x00000002,
FIELD_DOUBLE = 0x00000004,
FIELD_TYPE_CLEAR = 0xFF000000, /* used to clear field type only */
FIELD_VALUE_IS_NULL = 0x80000000, /* for queries & results only */
FIELD_DISPLAY = 0x40000000 /* for queries only */
};

Parameters

Type Name Description
FIELD_ID id valid field ID to retrieve type from


radsqliteFieldGetBigIntValue()

long long radsqliteFieldGetBigIntValue
(
FIELD_ID id
);


Description

Retrieve the big integer value of the field (must be of type FIELD_BIGINT).

Return Value

Returns the value

Parameters

Type Name Description
FIELD_ID id field to extract value from


radsqliteFieldGetDoubleValue()

double radsqliteFieldGetDoubleValue
(
DATABASE_ID id
);


Description

Retrieve the double value of the field (must be of type FIELD_DOUBLE).

Return Value

Returns the value

Parameters

Type Name Description
FIELD_ID id field to extract value from


radsqliteFieldGetCharValue()

char *radsqliteFieldGetCharValue
(
FIELD_ID id
);


Description

Retrieve the string value of the field (must be of type FIELD_STRING).

Return Value

Returns the value

Parameters

Type Name Description
FIELD_ID id field to extract value from


radsqliteFieldGetCharLength()

int radsqliteFieldGetCharLength
(
FIELD_ID id
);


Description

Retrieve the string length of the field (must be of type FIELD_STRING).

Return Value

Returns the value

Parameters

Type Name Description
FIELD_ID id field to extract value from


radsqliteFieldSetTypeBigInt()

int radsqliteFieldSetTypeBigInt
(
FIELD_ID id
);


Description

Set the field type to FIELD_BIGINT.

Return Value

Returns OK

Parameters

Type Name Description
FIELD_ID id valid field ID


radsqliteFieldSetTypeDouble()

int radsqliteFieldSetTypeDouble
(
FIELD_ID id
);


Description

Set the field type to FIELD_DOUBLE.

Return Value

Returns OK

Parameters

Type Name Description
FIELD_ID id valid field ID


radsqliteFieldSetTypeChar()

int radsqliteFieldSetTypeChar
(
FIELD_ID id
);


Description

Set the field type to FIELD_STRING.

Return Value

Returns OK

Parameters

Type Name Description
FIELD_ID id valid field ID


radsqliteFieldSetToNull()

int radsqliteFieldSetToNull
(
FIELD_ID id
);


Description

Set the field flag to NULL (empty).

Return Value

Returns OK

Parameters

Type Name Description
FIELD_ID id valid field ID


radsqliteFieldSetToNotNull()

int radsqliteFieldSetToNotNull
(
FIELD_ID id
);


Description

Set the field flag to NOT NULL (not empty).

Return Value

Returns OK

Parameters

Type Name Description
FIELD_ID id valid field ID


radsqliteFieldSetBigIntValue()

int radsqliteFieldSetBigIntValue
(
FIELD_ID id,
long long value
);


Description

Set the big integer field value.

Return Value

Returns OK

Parameters

Type Name Description
FIELD_ID id valid field ID
long long value value to set


radsqliteFieldSetDoubleValue()

int radsqliteFieldSetDoubleValue
(
FIELD_ID id,
double value
);


Description

Set the double field value.

Return Value

Returns OK

Parameters

Type Name Description
FIELD_ID id valid field ID
double value value to set


radsqliteFieldSetCharValue()

int radsqliteFieldSetCharValue
(
FIELD_ID id,
const char *value,
int valueLength
);


Description

Set the string field value.

Return Value

Returns OK

Parameters

Type Name Description
FIELD_ID id valid field ID
const char * value value to set
int valueLength string length of value to set


radStackInit()

STACK_ID radStackInit (void);


Description

Create a an empty stack.

Return Value

STACK_ID or NULL



radStackExit()

void radStackExit (STACK_ID id);


Description

Delete a stack, freeing all the nodes as well.

Return Value

None

Parameters

Type Name Description
STACK_ID id stack ID


radStackPush()

int radStackPush (STACK_ID id, STACK_NODE *newNode);


Description

Push an object onto the stack.

Return Value

OK or ERROR

Parameters

Type Name Description
STACK_ID id stack ID
STACK_NODE newNode New object to push onto the stack


radStackPop()

STACK_NODE *radStackPop (STACK_ID id);


Description

Pop an object off the stack.

Return Value

STACK_NODE or NULL if the stack is empty

Parameters

Type Name Description
STACK_ID id stack ID


radStackCount()

int radStackCount (STACK_ID id);


Description

Get the count of objects on the stack.

Return Value

Stack count

Parameters

Type Name Description
STACK_ID id stack ID


radStatesInit()

STATES_ID radStatesInit (void *saveData);


Description

Create and initialize a state machine.

Return Value

STATES_ID or NULL

Notes

State values MUST be 0-based and contiguous.

Parameters

Type Name Description
void * saveData application-specific data pointer that will be passed into all state handlers by radStatesProcess


radStatesExit()

void radStatesExit (STATES_ID id);


Description

Destroy a state machine.

Return Value

None

Parameters

Type Name Description
STATES_ID id state machine ID


radStatesAddHandler()

int radStatesAddHandler
(
STATES_ID id,
int state,
int (*handler) (int state, void *stimulus, void *userData)
);


Description

Add a state processor to the state machine. state MUST be < STATE_MAX_STATES defined in radstates.h.

Return Value

OK or ERROR

Notes

handler must ALWAYS return the next state of the machine.

Parameters

Type Name Description
STATES_ID id state machine ID
int state the specific state to which "handler" is assigned
int (*) handler state machine handler for the state "state"


radStatesRemHandler()

int radStatesRemHandler (STATES_ID id, int state);


Description

Remove a processor (resets the handler to the stub handler).

Return Value

OK or ERROR

Parameters

Type Name Description
STATES_ID id state machine ID
int state the state to remove the assigned handler for


radStatesProcess()

void radStatesProcess (STATES_ID id, void *stimulus);


Description

Process an application-defined stimulus. Stimuli can be messages, timers, events, file descriptors, etc.

Return Value

None

Parameters

Type Name Description
STATES_ID id state machine ID
void * stimulus application-defined stimulus pointer which is passed into the active state's handler


radStatesSetState()

int radStatesSetState (STATES_ID id, int state);


Description

Change the state of the machine

Return Value

OK or ERROR

Notes

Usually only invoked during state machine initialization. When called from within a state machine handler, bad side-effects can occur.

Parameters

Type Name Description
STATES_ID id state machine ID
int state new state for the state machine


radStatesGetState()

int radStatesGetState (STATES_ID id);


Description

Get the currently active state of the machine.

Return Value

current state of the state machine

Parameters

Type Name Description
STATES_ID id state machine ID


radStatesReset()

void radStatesReset (STATES_ID id, void *saveData);


Description

Reset all handlers to the stub handler and set the new user data to saveData.

Return Value

None

Parameters

Type Name Description
STATES_ID id state machine ID
void * saveData new user data for the state machine


radSystemInit()

int radSystemInit (UCHAR systemID);


Description

Initialize a unique radlib system and/or register the calling process within an existing radlib system.

Return Value

OK or ERROR

Notes

All processes within a radlib system must call this method before calling radProcessInit. If this is the first process in the system to call this, system facilities will be created and initialized, otherwise this will just register the process with existing system facilities. Care must be taken that all processes within a given radlib system use the same unique systemID. Thus unrelated radlib systems can run concurrently by using different system IDs for initialization. This function must be called before calling radProcessInit.

Parameters

Type Name Description
UCHAR systemID the unique system ID for the calling process (or processes) - system IDs are limited to the range 0-255


radSystemExit()

int radSystemExit (UCHAR systemID);


Description

Deregister the calling process from a unique radlib system and destroy all facilities if it is the last process left in the radlib system.

Return Value

OK or ERROR

Notes

Care must be taken that all processes within a given radlib system use the same unique systemID. This function must be called after calling radProcessExit.

Parameters

Type Name Description
UCHAR systemID the unique system ID for the calling process (or processes) - system IDs are limited to the range 0-255


radSystemGetUpTimeMS()

ULONG radSystemGetUpTimeMS (UCHAR systemID);


Description

Returns the number of milliseconds since radSystemInit was first called with this "systemID".

Return Value

Number of milliseconds since radSystemInit was first called with this "systemID"

Notes

Care must be taken that all processes within a given radlib system use the same unique systemID. This function may be called after calling radSystemInit.

Parameters

Type Name Description
UCHAR systemID the unique system ID for the calling process (or processes) - system IDs are limited to the range 0-255


radSystemGetUpTimeSEC()

ULONG radSystemGetUpTimeSEC (UCHAR systemID);


Description

Returns the number of seconds since radSystemInit was first called with this "systemID".

Return Value

Number of seconds since radSystemInit was first called with this "systemID"

Notes

Care must be taken that all processes within a given radlib system use the same unique systemID. This function may be called after calling radSystemInit.

Parameters

Type Name Description
UCHAR systemID the unique system ID for the calling process (or processes) - system IDs are limited to the range 0-255


radSystemGetUpTimeSTR()

char *radSystemGetUpTimeSTR (UCHAR systemID);


Description

Returns a string of the form: "Y years, M months, D days, H hours, m minutes, S seconds" which represents the time since radSystemInit was first called with this "systemID".

Return Value

The up time string

Notes

Care must be taken that all processes within a given radlib system use the same unique systemID. This function may be called after calling radSystemInit. This call is not reentrant and successive calls will overwrite the static buffer contents.

Parameters

Type Name Description
UCHAR systemID the unique system ID for the calling process (or processes) - system IDs are limited to the range 0-255


radthreadCreate()

RAD_THREAD_ID radthreadCreate ( void (*ThreadEntry)(RAD_THREAD_ID threadId, void* threadData), void* threadData );


Description

Create and start a thread.

Return Value

the new RAD_THREAD_ID or NULL if not successful

Notes

See the header file radthread.h for more details.

Parameters

Type Name Description
void (*)(RAD_THREAD_ID threadId, void* threadData) ThreadEntry Thread entry function
void* threadData User-defined data passed to the thread entry function


radthreadWaitExit()

void radthreadWaitExit(RAD_THREAD_ID threadId);


Description

Set the exit flag and wait for the thread described by threadId to exit.

Return Value

N/A

Notes

Will block until the thread terminates.

Parameters

Type Name Description
RAD_THREAD_ID threadId unique thread ID


radthreadSendToThread()

int radthreadSendToThread ( RAD_THREAD_ID threadId, int type, void* data, int length );


Description

Send data (thread safe) to the thread described by threadId.

Return Value

OK or ERROR

Notes

Uses internal mutex and condition variable to provide thread safe delivery and notification.

Parameters

Type Name Description
RAD_THREAD_ID threadId unique thread ID
int type user-defined value (typically a message ID)
void* data pointer to the data to be sent; data is copied, ownership not transferred
int length length of "data"


radthreadReceiveFromThread()

int radthreadReceiveFromThread ( RAD_THREAD_ID threadId, void** data, int* length, int blocking );


Description

Receive data (thread safe) from the thread described by threadId.

Return Value

User-defined msg type or ERROR_ABORT if non-blocking and no msg available.

Notes

Uses internal mutex and condition variable to provide thread safe delivery and notification. "*data" will point to a radsysBuffer which must be freed via radBufferRls when the receiver is done with it.

Parameters

Type Name Description
RAD_THREAD_ID threadId unique thread ID
void** data address of a pointer that is modified to point to the received buffer
int* length pointer to an integer which is modified to contain the length of the received buffer
int blocking if non-zero, this function will block until a message is available


radthreadSendToParent()

int radthreadSendToParent ( RAD_THREAD_ID threadId, int type, void* data, int length );


Description

Send data (thread safe) to the parent of the thread described by threadId.

Return Value

OK or ERROR

Notes

Uses internal mutex and condition variable to provide thread safe delivery and notification.

Parameters

Type Name Description
RAD_THREAD_ID threadId unique thread ID
int type user-defined value (typically a message ID)
void* data pointer to the data to be sent; data is copied, ownership not transferred
int length length of "data"


radthreadReceiveFromParent()

int radthreadReceiveFromParent ( RAD_THREAD_ID threadId, void** data, int* length, int blocking );


Description

Receive data (thread safe) from the parent of the thread described by threadId.

Return Value

User-defined msg type or ERROR_ABORT if non-blocking and no msg available.

Notes

Uses internal mutex and condition variable to provide thread safe delivery and notification. "*data" will point to a radsysBuffer which must be freed via radBufferRls when the receiver is done with it.

Parameters

Type Name Description
RAD_THREAD_ID threadId unique thread ID
void** data address of a pointer that is modified to point to the received buffer
int* length pointer to an integer which is modified to contain the length of the received buffer
int blocking if non-zero, this function will block until a message is available


radthreadShouldExit()

int radthreadShouldExit(RAD_THREAD_ID threadId);


Description

Thread described by threadId test for exit command from parent.

Return Value

TRUE (non-zero) if the thread should exit, FALSE (0) otherwise.

Notes

Thread should call this function periodically and exit if it returns TRUE.

Parameters

Type Name Description
RAD_THREAD_ID threadId unique thread ID


radthreadLock()

int radthreadLock(void);


Description

Lock the general thread mutex for this process.

Return Value

N/A

Notes

This mutex should not be held when calling radMsgRouterMessageSend.



radthreadUnlock()

int radthreadUnlock(void);


Description

Release the general thread mutex for this process.

Return Value

N/A

Notes

This mutex should not be held when calling radMsgRouterMessageSend.



radUtilsSetIntervalTimer()

int radUtilsSetIntervalTimer (int msecs);


Description

Start the system interval timer to deliver SIGALRM after msecs milliseconds.

Return Value

OK or ERROR

Notes

Usually only invoked directly by radTimer functions. If radTimers are running, manual manipulation of the system timer will corrupt the timer subsystem.

Parameters

Type Name Description
int msecs number of milliseconds for the timer expiry


radUtilsSetIntervalTimer()

int radUtilsSetIntervalTimer (int msecs);


Description

Start the system interval timer to deliver SIGALRM after msecs milliseconds.

Return Value

OK or ERROR

Notes

Usually only invoked directly by radTimer functions. If radTimers are running, manual manipulation of the system timer will corrupt the timer subsystem.

Parameters

Type Name Description
int msecs number of milliseconds for the timer expiry


radUtilsGetIntervalTimer()

int radUtilsGetIntervalTimer (void);


Description

Get the value of the real interval timer in milliseconds.

Return Value

milliseconds before the next system timer delivers SIGALRM

Notes

Usually only invoked directly by radTimer functions.



radUtilsEnableSignal()

int radUtilsEnableSignal (int signum);


Description

Allow a signal to be received (see signal.h).

Return Value

OK or ERROR

Notes

Usually only invoked directly by radlib functions.

Parameters

Type Name Description
int signum signal to enable


radUtilsDisableSignal()

int radUtilsDisableSignal (int signum);


Description

Disallow a signal from being received (see signal.h).

Return Value

OK or ERROR

Notes

Usually only invoked directly by radlib functions.

Parameters

Type Name Description
int signum signal to disable


radUtilsBecomeDaemon()

int radUtilsBecomeDaemon (const char *workingDirectory);


Description

Make calling process a daemon. The calling process forks a new daemon child then exits - new process does a "chdir" to 'workingDirectory' if not NULL. The resulting process has no controlling terminal.

Return Value

the new process pid or ERROR

Notes

Usually only invoked directly by radProcessInit.

Parameters

Type Name Description
char * workingDirectory working directory of new daemon process (if not NULL)


radUtilsSleep()

void radUtilsSleep (int msDuration);


Description

Provide a sleep function with ms resolution.

Return Value

None

Parameters

Type Name Description
int msDuration milliseconds to sleep


radtextsearchInit()

TEXT_SEARCH_ID radtextsearchInit (void);


Description

Create a text search object.

Return Value

New search ID or ERROR if the ID cannot be allocated



radtextsearchExit()

void radtextsearchExit (TEXT_SEARCH_ID id);


Description

Cleanup and delete a search object.

Return Value

N/A

Parameters

Type Name Description
TEXT_SEARCH_ID id text search ID returned from radtextsearchInit


radtextsearchInsert()

int radtextsearchInsert (TEXT_SEARCH_ID id, const char* text, int ordinal);


Description

Insert a member of the text string universe.

Return Value

OK or ERROR if a new node cannot be allocated.

Parameters

Type Name Description
TEXT_SEARCH_ID id text search ID returned from radtextsearchInit
const char* text text to be inserted in binary search tree
int ordinal ordinal value corresponding to text string


radtextsearchRemove()

int radtextsearchRemove (TEXT_SEARCH_ID id, const char* text);


Description

Delete a member of the universe.

Return Value

OK if found/removed, ERROR otherwise.

Parameters

Type Name Description
TEXT_SEARCH_ID id text search ID returned from radtextsearchInit
const char* text text to be removed from binary search tree


radtextsearchFind()

int radtextsearchFind (TEXT_SEARCH_ID id, const char* text, int* ordinalStore);


Description

Find a member of the universe and return the corresponding ordinal in ordinalStore.

Return Value

OK if found (and ordinalStore populated) or ERROR if not found.

Parameters

Type Name Description
TEXT_SEARCH_ID id text search ID returned from radtextsearchInit
const char* text text to be found in binary search tree
int* ordinalStore where to store ordinal value corresponding to text string (if found)


radTimerListCreate()

int radTimerListCreate (int noTimers, int notifyDescriptor);


Description

Create a timer list for the calling process. Timer expiries are notified through the notifyDescriptor.

Return Value

OK or ERROR

Notes

Usually only invoked directly by radProcessInit.

Parameters

Type Name Description
int noTimers number of timers for the timer list
int notifyDescriptor file descriptor to notify timer events through


radTimerListDelete()

void radTimerListDelete (void);


Description

Delete the calling process's timer list.

Return Value

None

Notes

Usually only invoked directly by radProcessExit.



radTimerCreate()

TIMER_ID radTimerCreate (TIMER_ID timer, void (*routine) (void *parm), void *parm);


Description

Create a timer object from the timer list free pool.

Return Value

TIMER_ID or NULL

Parameters

Type Name Description
TIMER_ID timer if not NULL, timer will be re-initialized instead of a new one being allocated
void (*) routine timer expiry callback routine
void * parm application data passed to the callback routine


radTimerDelete()

void radTimerDelete (TIMER_ID timer);


Description

Release a timer instance to the timer list free pool.

Return Value

None

Parameters

Type Name Description
TIMER_ID timer timer to release


radTimerStart()

void radTimerStart (TIMER_ID timer, int time);


Description

Start the timer for time milliseconds.

Return Value

None

Parameters

Type Name Description
TIMER_ID timer timer ID
int time milliseconds for timer duration


radTimerStop()

void radTimerStop (TIMER_ID timer);


Description

Stop a running timer.

Return Value

None

Parameters

Type Name Description
TIMER_ID timer timer ID to stop


radTimerStatus()

int radTimerStatus (TIMER_ID timer);


Description

Determine if the timer is running.

Return Value

TRUE or FALSE

Parameters

Type Name Description
TIMER_ID timer timer ID to status


radTimerSetUserParm()

void radTimerSetUserParm (TIMER_ID timer, void *newParm);


Description

Reset the user pointer passed to the callback routine.

Return Value

None

Parameters

Type Name Description
TIMER_ID timer timer ID
void * newParm new user pointer for callback


radTimeGetMSSinceEpoch()

ULONGLONG radTimeGetMSSinceEpoch (void);


Description

Returns the time in milliseconds since midnight, January 1, 1970

Return Value

milliseconds since the EPOCH



radTimeGetSECSinceEpoch()

ULONG radTimeGetSECSinceEpoch (void);


Description

Returns the time in seconds since midnight, January 1, 1970

Return Value

seconds since the EPOCH



radUDPSocketCreate()

RADUDPSOCK_ID radUDPSocketCreate (void);


Description

Create a datagram socket.

Return Value

RADUDPSOCK_ID or NULL if there is an error

Notes

This creates a UDP datagram socket. It can be used to send on immediately with the radUDPSocketSendTo function and/or it can be bound to a specific local IP address and port to receive datagrams with the radUDPSocketBind function.



radUDPSocketDestroy()

int radUDPSocketDestroy (RADUDPSOCK_ID id);


Description

Close connection and cleanup resources.

Return Value

OK or ERROR

Parameters

Type Name Description
RADUDPSOCK_ID id Valid socket ID obtained from a successful call to radUDPSocketCreate


radSocketGetDescriptor()

int radSocketGetDescriptor (RADUDPSOCK_ID id);


Description

Get the socket descriptor (for select calls, etc.).

Return Value

The socket descriptor associated with "id".

Parameters

Type Name Description
RADUDPSOCK_ID id Valid socket ID obtained from a successful call to radUDPSocketCreate


radUDPSocketBind()

int radUDPSocketBind (RADUDPSOCK_ID id, USHORT port);


Description

Bind the UDP socket to a local port so you can add the socket descriptor to your select list and receive data.

Return Value

OK or ERROR

Parameters

Type Name Description
RADUDPSOCK_ID id Valid socket ID obtained from a successful call to radUDPSocketCreate
USHORT port Port number to be bound


radUDPSocketSetBroadcast()

int radUDPSocketSetBroadcast (RADUDPSOCK_ID id, int enable);


Description

Enable/Disable sending broadcast packets.

Return Value

OK or ERROR

Parameters

Type Name Description
RADUDPSOCK_ID id Valid socket ID obtained from a successful call to radUDPSocketCreate
int enable FALSE disables, TRUE enables


radUDPSocketSetMulticastTXInterface()

int radUDPSocketSetMulticastTXInterface
(
RADUDPSOCK_ID id,
char *interfaceIP
);


Description

Set multicast interface for outgoing datagrams.

Return Value

OK or ERROR

Parameters

Type Name Description
RADUDPSOCK_ID id Valid socket ID obtained from a successful call to radUDPSocketCreate
char * interfaceIP interface IP address to send on


radUDPSocketSetMulticastTTL()

int radUDPSocketSetMulticastTTL (RADUDPSOCK_ID id, int ttl);


Description

Set multicast TTL for outgoing datagrams (1 by default).

Return Value

OK or ERROR

Notes

The TTL value for multicast packets has a special meaning: it specifies the number of "hops" the packet shall be allowed to traverse. In other words, the number of router traversals. A value of "1" will keep the multicast packet on the local segment.

Parameters

Type Name Description
RADUDPSOCK_ID id Valid socket ID obtained from a successful call to radUDPSocketCreate
int ttl number of router "hops" allowed


radUDPSocketSetMulticastLoopback()

int radUDPSocketSetMulticastLoopback (RADUDPSOCK_ID id, int enable);


Description

Enable/Disable multicast loopback (disabled by default).

Return Value

OK or ERROR

Parameters

Type Name Description
RADUDPSOCK_ID id Valid socket ID obtained from a successful call to radUDPSocketCreate
int enable FALSE disables, TRUE enables


radUDPSocketAddMulticastMembership()

int radUDPSocketAddMulticastMembership
(
RADUDPSOCK_ID id,
char *multicastGroupIP,
char *interfaceIP
);


Description

"Turn on" RX multicast datagrams on the "multicastGroupIP" group and "interfaceIP" interface.

Return Value

OK or ERROR

Notes

Enables multicast packet reception for the given multicast group (IP address) on the given local interface (IP address).

Parameters

Type Name Description
RADUDPSOCK_ID id Valid socket ID obtained from a successful call to radUDPSocketCreate
char * multicastGroupIP multicast group IP address
char * interfaceIP interface IP address


radUDPSocketDropMulticastMembership()

int radUDPSocketDropMulticastMembership
(
RADUDPSOCK_ID id,
char *multicastGroupIP,
char *interfaceIP
);


Description

"Turn off" RX multicast datagrams on the "multicastGroupIP" group and "interfaceIP" interface.

Return Value

OK or ERROR

Notes

Disables multicast packet reception for the given multicast group (IP address) on the given local interface (IP address).

Parameters

Type Name Description
RADUDPSOCK_ID id Valid socket ID obtained from a successful call to radUDPSocketCreate
char * multicastGroupIP multicast group IP address
char * interfaceIP interface IP address


radUDPSocketRecvFrom()

int radUDPSocketRecvFrom
(
RADUDPSOCK_ID id,
void *buffer,
int maxToRead
);


Description

Receive a datagram from a UDP socket.

Return Value

Bytes read or ERROR if an error occurs.

Notes

Will return less than requested amount based on the size of the datagram or if it is interrupted by a received signal.

Parameters

Type Name Description
RADUDPSOCK_ID id Valid socket ID obtained from a successful call to radUDPSocketCreate
void * buffer User buffer pointing to valid memory of size >= "lengthToRead" bytes where data is written
int maxToRead Maximum bytes to read


radUDPSocketSendTo()

int radUDPSocketSendTo
(
RADUDPSOCK_ID id,
char *hostOrIPAdrs,
USHORT port,
void *data,
int length
);


Description

Send a datagram to a host name or IP adrs and port (connectionless).

Return Value

OK or ERROR

Parameters

Type Name Description
RADUDPSOCK_ID id Valid socket ID obtained from a successful call to radUDPSocketCreate
char * hostOrIPAdrs host name or IP address string of the destination
USHORT port destination port number
void * data User buffer pointing to the data to be written
int length Bytes to write


radUDPSocketSetBlocking()

int radUDPSocketSetBlocking
(
RADUDPSOCK_ID id,
int isBlocking
);


Description

Set the socket for blocking or non-blocking IO.

Return Value

OK or ERROR

Notes

By default, all socket types are created in blocking IO mode. It is the user's responsibility to handle blocking/non-blocking IO properly (EAGAIN and EINTR errno's). Non-blocking should NOT be set for server (listen) sockets.

Parameters

Type Name Description
RADUDPSOCK_ID id Valid socket ID obtained from a successful call to radUDPSocketCreate
int isBlocking Boolean indicating if the socket should be set to non-blocking (non-zero value) or blocking IO (0 value, default)


radUDPSocketSetDebug()

void radUDPSocketSetDebug
(
RADUDPSOCK_ID id,
int enable
);


Description

Turn on or off data debug which dumps all read/write datagrams to msgLog.

Return Value

N/A

Notes

If enabled, debug will radMsgLog the contents of all RX/TX datagrams.

Parameters

Type Name Description
RADUDPSOCK_ID id Valid socket ID obtained from a successful call to radUDPSocketCreate
int enable Boolean indicating if the debug dumping of RX/TX datagrams should be enabled or disabled