Version 2.12.0
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.
radBuffersInitCCITT CRC utilities.
radCRC16CalculateOptional 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 MethodsTo 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
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
};
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.
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.
radProcessInitProcess 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.
radQueueSystemInitThe 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.
radSHA1ComputeBlockShared memory is the lynch pin of radlib interprocess communications. System buffers and message queues depend upon the existence (and robustness) of shared memory.
radShmemIfExistOptional 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 MethodsStacks 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.
radStackInitState 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.
radStatesInitThis 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.
radSystemInitThis 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 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.
radBuffersInit()int radBuffersInit (int minBufferSize, int maxBufferSize, int *numberOfEachSize)
| Called from process initialization (normally by radSystemInit). Not normally called directly by application methods. Creates the system buffer pool. |
|
OK or ERROR |
|
radSemProcessInit must be called before this method (also usually called from radSystemInit). |
| 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);
| Request a system buffer of size "size". |
|
The buffer pointer or NULL if none available. |
|
|
| Type | Name | Description |
| int | size | The length in bytes of the buffer requested |
radBufferRls() int radBufferRls (void *buffer);
| Release a system buffer back into the free pool. |
| OK or ERROR |
|
|
| Type | Name | Description |
| void * | buffer | Buffer pointer obtained from a successful radBufferGet call. |
radBuffersExit() void radBuffersExit (void);
|
Detach from the system buffer pool. Does NOT destroy the system buffer pool. Not normally called from application methods (called from radSystemExit). |
|
None |
radBuffersExitAndDestroy() void radBuffersExitAndDestroy (void);
| 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);
|
Retrieve the total number of buffers (all sizes, free and allocated) in the system. |
|
The total free and allocated buffers in the system. |
radBuffersGetAvailable() ULONG radBuffersGetAvailable (void);
|
Retrieve the number of available (free) buffers in the system. |
|
The number of free buffers of any size in the system. |
radCfOpen() CF_ID radCfOpen (char *file);
| 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. |
| If successful, a valid CF_ID to be used with all subsequent radCF methods. NULL is returned if there is an error. |
| 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! |
| Type | Name | Description |
| char * | file | Full path name of the config file |
radCfClose() void radCfClose (CF_ID file);
| Releases the lock on the file, closes the file and cleans up local information about it. |
| None |
| Type | Name | Description |
| CF_ID | file | radCF ID |
radCfFlush() int radCfFlush (CF_ID file);
| Flushes the file to disk. |
| OK or ERROR |
| This call MUST be made for any changes to config files to be saved to the disk file itself. |
| Type | Name | Description |
| CF_ID | file | radCF ID |
radCfPutComment() int radCfPutComment (CF_ID file, char *text);
| Creates a comment line at the end of the config file. |
| OK or ERROR |
| 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);
| Inserts a comment before the given entry. |
| OK or ERROR |
| 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);
| Checks for a comment before the given entry. |
| TRUE or FALSE |
| 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);
| Checks for a comment after the given entry. |
| TRUE or FALSE |
| 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);
| Retrieves the first entry for a particular ID. instance and value are both filled with the appropriate information when an entry is found. |
| OK or ERROR |
| 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);
| Gets the next entry for a particular ID. instance and value are both filled with the appropriate information when a new entry is found. |
| OK or ERROR |
| 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);
| Retrieves a particular config file entry specified by the "id" and "instance" inputs. |
| OK or ERROR |
| 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);
| 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. |
| OK or ERROR |
| 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);
| Calculate the 16-bit CRC-CCITT for the given memory block. |
| The USHORT CRC value. |
| 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. |
| 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);
| Calculate the 32-bit CRC-CCITT for the given memory block. |
| The ULONG CRC value. |
| 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. |
| 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
);
| Connect to a database server. |
| Returns the DATABASE_ID or NULL |
| 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. |
| 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
);
| Close the connection to a database server. |
| None |
| Type | Name | Description |
| DATABASE_ID | dbId | Value returned from successful raddatabaseOpen call |
raddatabaseQuery() int raddatabaseQuery
(
DATABASE_ID dbId,
const char *query,
int createResults
);
| Issue an SQL query to the database server. |
| 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'. |
| 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. |
| 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
);
| 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.). |
| Returns RESULT_SET_ID or NULL |
| RESULT_SET_ID should be released via raddatabaseTableResultsRelease once the user is finished with it. |
| Type | Name | Description |
| DATABASE_ID | dbId | Value returned from successful raddatabaseOpen call |
raddatabaseRefreshResults() RESULT_SET_ID raddatabaseRefreshResults
(
DATABASE_ID dbId,
RESULT_SET_ID origResultSet
);
| Refresh a result set based on the original query. |
| Returns RESULT_SET_ID or NULL |
| RESULT_SET_ID should be released via raddatabaseTableResultsRelease once the user is finished with it. |
| 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
);
| Release a result set. |
| None |
| 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
);
| Does 'tableName' table exist? |
| Returns TRUE or FALSE |
| 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'. |
| 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 */
);
| Create a table named 'tableName'. |
| Returns OK or ERROR |
| 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
);
| Drop the table named 'tableName'. |
| Returns OK or ERROR |
| 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
);
| Truncate (empty) the table named 'tableName'. |
| Returns OK or ERROR |
| 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
| Create a row description to use for row insertion/retrieval. |
| Returns ROW_ID or NULL |
| 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). |
| 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
);
| Query a table to create a result set given a row description. |
| Returns RESULT_SET_ID or NULL |
| 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). |
| 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
);
| Insert a row into a table. |
| Returns OK or ERROR |
| '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. |
| 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
);
| Modify rows in 'tableName' matching 'matchId' with the field values defined in 'newData'. |
| Returns OK or ERROR |
| 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. |
| 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
);
| Delete rows in 'tableName' matching 'matchId'. |
| Returns OK or ERROR |
| Only the non-NULL fields will be used to match records in the table (i.e., multiple rows can be matched). |
| 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
);
| Retrieve the first row of a result set. |
| Returns ROW_ID or NULL if the result set is empty |
| Allows traversal of the rows in a result set. |
| Type | Name | Description |
| RESULT_SET_ID | id | result set obtained from raddatabaseGetResults or raddatabaseTableQueryRow |
raddatabaseResultsGetNext() ROW_ID raddatabaseResultsGetNext
(
RESULT_SET_ID id
);
| Retrieve the next row of a result set. |
| Returns ROW_ID or NULL if there is no next row |
| Allows traversal of the rows in a result set. |
| Type | Name | Description |
| RESULT_SET_ID | id | result set obtained from raddatabaseGetResults or raddatabaseTableQueryRow |
raddatabaseResultsGetPrev() ROW_ID raddatabaseResultsGetPrev
(
RESULT_SET_ID id
);
| Retrieve the previous row of a result set. |
| Returns ROW_ID or NULL if there is no previous row |
| Allows traversal of the rows in a result set. |
| Type | Name | Description |
| RESULT_SET_ID | id | result set obtained from raddatabaseGetResults or raddatabaseTableQueryRow |
raddatabaseResultsGetLast() ROW_ID raddatabaseResultsGetLast
(
RESULT_SET_ID id
);
| Retrieve the last row of a result set. |
| Returns ROW_ID or NULL if the result set is empty |
| Allows traversal of the rows in a result set. |
| Type | Name | Description |
| RESULT_SET_ID | id | result set obtained from raddatabaseGetResults or raddatabaseTableQueryRow |
raddatabaseRowDescriptionCreate() ROW_ID raddatabaseRowDescriptionCreate
(
void
);
| Create an empty row description to use when describing a new table. |
| Returns ROW_ID or NULL |
| 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
);
| Add a new field to a row description. |
| Returns OK or ERROR |
| 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
);
| Remove a field identified by 'name' from the row description. |
| Returns OK or ERROR |
| 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
);
| Release a row description and the corresponding fields. |
| None |
| Type | Name | Description |
| ROW_ID | id | Value returned from successful raddatabaseRowDescriptionCreate call |
raddatabaseFieldGet() FIELD_ID raddatabaseFieldGet
(
ROW_ID id,
const char *fieldName
);
| Get the field identified by 'fieldName'. |
| Returns FIELD_ID or NULL |
| Type | Name | Description |
| ROW_ID | id | valid row description ID |
| const char * | fieldName | name of field to retrieve |
raddatabaseFieldGetType() UINT raddatabaseFieldGetType
(
DATABASE_ID id
);
| Retrieve the field type bitmask (see raddatabase.h). |
| Returns the field type bitmask |
|
enum DbFieldTypes |
| Type | Name | Description |
| FIELD_ID | id | valid field ID to retrieve type from |
raddatabaseFieldGetIntValue() int raddatabaseFieldGetIntValue
(
FIELD_ID id
);
| Retrieve the integer value of the field (must be of type FIELD_INT). |
| Returns the value |
| Type | Name | Description |
| FIELD_ID | id | field to extract value from |
raddatabaseFieldGetBigIntValue() long long raddatabaseFieldGetBigIntValue
(
FIELD_ID id
);
| Retrieve the big integer value of the field (must be of type FIELD_BIGINT). |
| Returns the value |
| Type | Name | Description |
| FIELD_ID | id | field to extract value from |
raddatabaseFieldGetFloatValue() float raddatabaseFieldGetFloatValue
(
FIELD_ID id
);
| Retrieve the float value of the field (must be of type FIELD_FLOAT). |
| Returns the value |
| Type | Name | Description |
| FIELD_ID | id | field to extract value from |
raddatabaseFieldGetDoubleValue() double raddatabaseFieldGetDoubleValue
(
DATABASE_ID id
);
| Retrieve the double value of the field (must be of type FIELD_DOUBLE). |
| Returns the value |
| Type | Name | Description |
| FIELD_ID | id | field to extract value from |
raddatabaseFieldGetTimeDateValue() char *raddatabaseFieldGetTimeDateValue
(
FIELD_ID id
);
| Retrieve the DATETIME value of the field (must be of type FIELD_DATETIME). |
| Returns the value |
| Type | Name | Description |
| FIELD_ID | id | field to extract value from |
raddatabaseFieldGetCharValue() char *raddatabaseFieldGetCharValue
(
FIELD_ID id
);
| Retrieve the string value of the field (must be of type FIELD_STRING). |
| Returns the value |
| Type | Name | Description |
| FIELD_ID | id | field to extract value from |
raddatabaseFieldGetCharLength() int raddatabaseFieldGetCharLength
(
FIELD_ID id
);
| Retrieve the string length of the field (must be of type FIELD_STRING). |
| Returns the value |
| Type | Name | Description |
| FIELD_ID | id | field to extract value from |
raddatabaseFieldSetTypeInt() int raddatabaseFieldSetTypeInt
(
FIELD_ID id
);
| Set the field type to FIELD_INT. |
| Returns OK |
| Type | Name | Description |
| FIELD_ID | id | valid field ID |
raddatabaseFieldSetTypeBigInt() int raddatabaseFieldSetTypeBigInt
(
FIELD_ID id
);
| Set the field type to FIELD_BIGINT. |
| Returns OK |
| Type | Name | Description |
| FIELD_ID | id | valid field ID |
raddatabaseFieldSetTypeFloat() int raddatabaseFieldSetTypeFloat
(
FIELD_ID id
);
| Set the field type to FIELD_FLOAT. |
| Returns OK |
| Type | Name | Description |
| FIELD_ID | id | valid field ID |
raddatabaseFieldSetTypeDouble() int raddatabaseFieldSetTypeDouble
(
FIELD_ID id
);
| Set the field type to FIELD_DOUBLE. |
| Returns OK |
| Type | Name | Description |
| FIELD_ID | id | valid field ID |
raddatabaseFieldSetTypeDateTime() int raddatabaseFieldSetTypeDateTime
(
FIELD_ID id
);
| Set the field type to FIELD_DATETIME. |
| Returns OK |
| Type | Name | Description |
| FIELD_ID | id | valid field ID |
raddatabaseFieldSetTypeChar() int raddatabaseFieldSetTypeChar
(
FIELD_ID id
);
| Set the field type to FIELD_STRING. |
| Returns OK |
| Type | Name | Description |
| FIELD_ID | id | valid field ID |
raddatabaseFieldSetToNull() int raddatabaseFieldSetToNull
(
FIELD_ID id
);
| Set the field flag to NULL (empty). |
| Returns OK |
| Type | Name | Description |
| FIELD_ID | id | valid field ID |
raddatabaseFieldSetToNotNull() int raddatabaseFieldSetToNotNull
(
FIELD_ID id
);
| Set the field flag to NOT NULL (not empty). |
| Returns OK |
| Type | Name | Description |
| FIELD_ID | id | valid field ID |
raddatabaseFieldSetIntValue() int raddatabaseFieldSetIntValue
(
FIELD_ID id,
int value
);
| Set the integer field value. |
| Returns OK |
| Type | Name | Description |
| FIELD_ID | id | valid field ID |
| int | value | value to set |
raddatabaseFieldSetBigIntValue() int raddatabaseFieldSetBigIntValue
(
FIELD_ID id,
long long value
);
| Set the big integer field value. |
| Returns OK |
| Type | Name | Description |
| FIELD_ID | id | valid field ID |
| long long | value | value to set |
raddatabaseFieldSetFloatValue() int raddatabaseFieldSetFloatValue
(
FIELD_ID id,
float value
);
| Set the float field value. |
| Returns OK |
| Type | Name | Description |
| FIELD_ID | id | valid field ID |
| float | value | value to set |
raddatabaseFieldSetDoubleValue() int raddatabaseFieldSetDoubleValue
(
FIELD_ID id,
double value
);
| Set the double field value. |
| Returns OK |
| 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
);
| Set the DATETIME field value. |
| Returns OK |
| 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
);
| Set the string field value. |
| Returns OK |
| 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
);
| Initialize events processing for this process - called once by each process (usually from radProcessInit). evtCallback will be called when an event(s) is signaled. |
| Returns the valid EVENTS_ID or NULL |
| Events require an initialized message queue to deliver events. |
| 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);
| Exits the events processing for this process. Usually called from radProcessExit. |
| None |
| Type | Name | Description |
| EVENTS_ID | id | Valid events system ID |
radEventsAdd() int radEventsAdd (EVENTS_ID id, UINT newEvents);
| Add events to the receive mask. |
| OK or ERROR |
| The receive mask is NOT replaced with this new mask but rather bitwise OR'd with the given mask. |
| 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);
| Remove events from the receive mask. |
| OK or ERROR |
| The receive mask is NOT replaced with this new mask but rather bitwise AND'd with the compliment of the remEvents. |
| Type | Name | Description |
| EVENTS_ID | id | Valid events system ID |
| UINT | remEvents | mask of events to "remove" |
radEventsGetMask() UINT radEventsGetMask (EVENTS_ID id);
| Retrieve the current receive event mask. These are the events which, when received, will be delivered to the callback handler. |
| The current receive event mask. |
| Type | Name | Description |
| EVENTS_ID | id | Valid events system ID |
radEventsSend() int radEventsSend (EVENTS_ID id, char *destQName,
UINT eventsToSend, UINT data);
| Send an event(s) to another process by queue name. |
| OK or ERROR |
| If radProcessInit was initialized and destName == NULL, sends the events to the calling process. |
| 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);
| This routine should be called with the result mask of a received event "message". It is usually only called directly by radProcessWait. |
| OK or ERROR |
| 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);
| Dynamically creates a RADLIST structure and initializes it to empty. |
| 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);
| Initializes the given list to empty. |
| The RADLIST_ID passed in. |
| Type | Name | Description |
| RADLIST_ID | list | list to initialize |
radListDelete() void radListDelete (RADLIST_ID list);
| 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). |
| None |
| 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
);
| Inserts the new object referenced by node after the object referenced by afterThisOne. |
| None |
| afterThisOne must already be in the list. List nodes CANNOT be inserted on multiple lists. |
| 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
);
| Inserts the new object referenced by node before the object referenced by beforeThisOne. |
| None |
| beforeThisOne must already be in the list. List nodes CANNOT be inserted on multiple lists. |
| 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
);
| Inserts the new object referenced by node at the front of the list. |
| None |
| 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
);
| Inserts the new object referenced by node at the end of the list. |
| None |
| 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
);
| Removes the node referenced by removeThisOne from the list. |
| None |
| 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
);
| Removes the first node from the list. |
| If the list was not empty, the NODE_PTR of the first node is returned, otherwise NULL |
| Type | Name | Description |
| RADLIST_ID | list | List ID of interest |
radListRemoveLast() NODE_PTR radListRemoveLast
(
RADLIST_ID list
);
| Removes the last node from the list. |
| If the list was not empty, the NODE_PTR of the last node is returned, otherwise NULL |
| Type | Name | Description |
| RADLIST_ID | list | List ID of interest |
radListGetNumberOfNodes() int radListGetNumberOfNodes
(
RADLIST_ID list
);
| Retrieves the number of nodes on the list. |
| The number of nodes |
| Type | Name | Description |
| RADLIST_ID | list | List ID of interest |
radListGetFirst() NODE_PTR radListGetFirst
(
RADLIST_ID list
);
| Retrieves the first node on the list. Does not remove it from the list. |
| If the list is not empty, the first node on the list, otherwise NULL |
| Type | Name | Description |
| RADLIST_ID | list | List ID of interest |
radListGetLast() NODE_PTR radListGetLast
(
RADLIST_ID list
);
| Retrieves the last node on the list. Does not remove the node from the list. |
| If the list is not empty, the last node on the list, otherwise NULL |
| Type | Name | Description |
| RADLIST_ID | list | List ID of interest |
radListGetNext() NODE_PTR radListGetNext
(
RADLIST_ID list,
NODE_PTR afterThisOne /* NULL => listGetFirst */
);
| Retrieves the node after the node referenced by afterThisOne from the list. Does not remove the node from the list. |
| If afterThisOne is not the last node on the list, the next node on the list, otherwise NULL |
| If afterThisOne is NULL, this call is the same as radListGetFirst. |
| 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 */
);
| Retrieves the node before the node referenced by beforeThisOne from the list. Does not remove the node from the list. |
| If beforeThisOne is not the first node on the list, the next node on the list, otherwise NULL |
| If beforeThisOne is NULL, this call is the same as radListGetLast. |
| 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
);
| Initializes logging for the calling process. Normally only called directly by radProcessInit. |
| OK or ERROR |
| 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);
| Exits the calling process from system logging capabilities. Normally only called directly by radProcessExit. |
| OK or ERROR |
radMsgLog() int radMsgLog (int priority, char *format, ...);
| Log a message - allow variable length parameter list. |
| OK or ERROR |
| 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);
| Log data in a pointer dumping style. Displays hex and ASCII in a tabular form to the syslog. |
| None |
| Type | Name | Description |
| void * | data | pointer to dump from |
| int | length | Length (in bytes) of data to dump |
radMsgRouterInit()int radMsgRouterInit (char *workingDir)
| Register the message router API for the calling process. |
| OK or ERROR |
| Type | Name | Description |
| char * | workingDir | specifies where the pid file and FIFOs for the message router process are maintained |
radMsgRouterExit()void radMsgRouterExit (void);
| Deregister the message router API for the calling process |
radMsgRouterProcessExit()void radMsgRouterExit (int pid);
| Deregister the message router API for "pid" process |
radMsgRouterMessageRegister()int radMsgRouterMessageRegister (ULONG msgID)
| Request to receive 'msgID' messages. |
| OK or ERROR |
| Type | Name | Description |
| ULONG | msgID | specifies the msgID to be received - '0' and '0xFFFFFFFF' are reserved |
radMsgRouterMessageDeregister()int radMsgRouterMessageDeregister (ULONG msgID)
| Request to stop receiving 'msgID' messages. |
| OK or ERROR |
| Type | Name | Description |
| ULONG | msgID | specifies the msgID to stop reception of - '0' and '0xFFFFFFFF' are reserved |
radMsgRouterMessageIsRegistered()int radMsgRouterMessageIsRegistered (ULONG msgID)
| Request if any consumers are registered for 'msgID' messages. |
| TRUE or FALSE |
| Type | Name | Description |
| ULONG | msgID | specifies the msgID to query - '0' and '0xFFFFFFFF' are reserved |
radMsgRouterMessageSend()int radMsgRouterMessageSend
(
ULONG msgID,
void *msg,
ULONG byteLength
);
| 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. |
| OK or ERROR |
| 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);
| Request the message router to dump statistics to the log file. |
radmrouted Daemon UsageUSAGE: [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
);
| Initialize process management; called once during process
initialization. Automatically sets up the following utilities for a new
process: |
| OK or ERROR |
| This function should be called after radSystemInit. |
| 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);
| Exit from radlib process framework. |
| None |
| This function should be called immediately before radSystemExit. |
radProcessSetExitFlag() void radProcessSetExitFlag (void);
| Set the internal exit flag. radProcessWait will dump out immediately once this is set. |
| None |
radProcessWait() int radProcessWait (int timeout);
| 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. |
| OK, ERROR, or TIMEOUT if timeout occurred |
| 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);
| Get the calling process's name. |
| Returns the store pointer, where the name is copied. |
| Type | Name | Description |
| char * | store | Character pointer to valid memory where the name is copied |
radProcessGetPid() pid_t radProcessGetPid (void);
| Retrieve the calling process's pid (process ID). |
| The calling process's pid |
radProcessIORegisterDescriptor() PROC_IO_ID radProcessIORegisterDescriptor
(
int fd,
void (*ioCallback) (int fd, void *userData),
void *userData
);
| 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. |
| PROC_IO_ID or ERROR |
| 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);
| Deregister a file descriptor for radProcessWait inclusion. |
| None |
| 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
);
| Register STDIN for radProcessWait inclusion. This is a special case of radProcessIORegisterDescriptor. |
| PROC_IO_ID or ERROR |
| 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));
| Initialize all signals (except SIGKILL and SIGSTOP) to be caught by defaultHandler. |
| OK or ERROR |
| Type | Name | Description |
| void (*) | defaultHandler | default signal handler |
radProcessSignalCatch() int radProcessSignalCatch (int signum, void (*handler)
(int signum));
| Assign a specific handler to a specific signal (signum). |
| OK or ERROR |
| Type | Name | Description |
| int | signum | signal number |
| void (*) | handler | signal handler |
radProcessSignalRelease() int radProcessSignalRelease (int signum);
| Set signum back to the default system handler. |
| OK or ERROR |
| Type | Name | Description |
| int | signum | signal number |
radProcessSignalIgnore() int radProcessSignalIgnore (int signum);
| Set signum to be ignored when raised. |
| OK or ERROR |
| Type | Name | Description |
| int | signum | signal number |
radProcessSignalGetHandler() void (*(radProcessSignalGetHandler (int signum)))
(int);
| Retrieve the current handler for signum. |
| The function pointer or NULL |
| Type | Name | Description |
| int | signum | signal number |
radProcessQueueGetName() char *radProcessQueueGetName (char *store);
| Retrieve calling process's queue name. |
| Queue name (stored in store) |
| Type | Name | Description |
| char * | store | where the queue name is copied |
radProcessQueueAttach() int radProcessQueueAttach (char *newName, int group);
| Attach to an individual queue based on queue name so messages can be sent to it. |
| OK or ERROR |
| Type | Name | Description |
| char * | newName | Queue name to attach to |
| int | group | Group number of the queue |
radProcessQueueDettach() int radProcessQueueDettach (char *oldName, int group);
| Detach from an individual queue based on queue name. |
| OK or ERROR |
| Type | Name | Description |
| char * | oldName | queue to detach from |
| int | group | Group number of queue |
radProcessQueueJoinGroup() int radProcessQueueJoinGroup (int groupNumber);
| Add calling process's queue to a group and add the group to calling process's address list. |
| OK or ERROR |
| Type | Name | Description |
| int | groupNumber | Group to join |
radProcessQueueQuitGroup() int radProcessQueueQuitGroup (int groupNumber);
| Remove calling process's queue from a group and remove a group from calling process's address list. |
| OK or ERROR |
| Type | Name | Description |
| int | groupNumber | Group to join |
radProcessQueueSend() int radProcessQueueSend (char *destQueue, UINT msgType,
void *sysBuffer, UINT length);
| Write to a queue. Assumes sysBuffer is a valid pointer to a system buffer. System buffer ownership is transferred to the receiving queue. |
| OK, ERROR, or ERROR_ABORT if the destination queue is gone |
| Calling process should detach from the destination queue on ERROR_ABORT. |
| 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);
| 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. |
| OK or ERROR |
| The system buffer is released if this call returns OK. Calling process must release if ERROR is returned. |
| 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);
| Determine if calling process is attached to the given queue name. |
| TRUE or FALSE |
| Type | Name | Description |
| char * | queueName | destination queue |
radProcessQueueKeepBuffer() void radProcessQueueKeepBuffer (void);
| 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. |
| None |
radProcessQueueStopHandlerList() void radProcessQueueStopHandlerList (void);
| 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). |
| None |
radProcessQueuePrependHandler() int radProcessQueuePrependHandler
(
void (*msgHandler) (char *srcQueueName, UINT msgType, void *msg, UINT length, void *userData)
);
| 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. |
| A unique identifier > 0 that can be used to remove the message handler later (see 'radProcessQueueRemoveHandler') or ERROR |
| 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);
| 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). |
| OK or ERROR |
| 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);
| Create a timer on the process's timer list. |
| TIMER_ID or NULL if there is an error |
| 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);
| Delete the timer specified by timer. |
| None |
| Type | Name | Description |
| TIMER_ID | timer | timer to delete |
radProcessTimerStart() void radProcessTimerStart (TIMER_ID timer, int time);
| Start the timer. |
| None |
| Type | Name | Description |
| TIMER_ID | timer | timer to start |
| int | time | duration of timer in milliseconds |
radProcessTimerStop() void radProcessTimerStop (TIMER_ID timer);
| Stop a running timer before it expires. |
| None |
| Type | Name | Description |
| TIMER_ID | timer | timer to stop |
radProcessTimerStatus() int radProcessTimerStatus (TIMER_ID timer);
| Determine if the given timer is running. |
| TRUE or FALSE |
| Type | Name | Description |
| TIMER_ID | timer | timer to status |
radProcessTimerSetUserParm() void radProcessTimerSetUserParm (TIMER_ID timer, void
*newParm);
| Reset the user parm (pointer passed to the callback) for a timer. |
| None |
| Type | Name | Description |
| TIMER_ID | timer | timer to modify |
| void * | newParm | new user parm |
radProcessEventsAdd() int radProcessEventsAdd (UINT newEvents);
| Add events to the receive mask (see radEventsAdd). |
| OK or ERROR |
| Type | Name | Description |
| UINT | newEvents | new events to receive |
radProcessEventsRemove() int radProcessEventsRemove (UINT removeEvents);
| Remove events from the receive mask. |
| OK or ERROR |
| Type | Name | Description |
| UINT | removeEvents | events to remove from the receive mask |
radProcessEventsGetEnabled() UINT radProcessEventsGetEnabled (void);
| Retrieve current receive mask. |
| Receive mask |
radProcessEventsSend() int radProcessEventsSend (char *destName, UINT eventsToSend,
UINT data);
| Send event(s) to the destination process with queue name destName. |
| OK or ERROR |
| If radProcessInit was initialized and destName == NULL, sends the events to the calling process. |
| 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);
| Create a new, empty process list. |
| PROC_LIST_ID or NULL |
| Type | Name | Description |
| char * | parentName | Name of the parent process |
radPlistDestroy() int radPlistDestroy (PROC_LIST_ID plistId);
| Destroy an existing process list (will clean up nodes). |
| OK or ERROR |
| 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
);
| Add a new "entry" into an existing process list. |
| OK or ERROR |
| 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. |
| 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);
| Start all process entries in an existing process list, ordered by priority (1 -> 100). |
| OK or ERROR |
| Type | Name | Description |
| PROC_LIST_ID | plistId | process list to start |
radPlistGetNumberRunning() int radPlistGetNumberRunning (PROC_LIST_ID plistId);
| Retrieve the number of running processes (after radPlistStart is called). |
| The number of processes successfully started |
| 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
);
| Execute a user-supplied function for the process specified by "entry" (after radPlistStart is called). |
| OK or ERROR |
| This allows the parent process to execute a function on the process pid of the process previously started with entry point "entry". |
| 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
);
| Execute a user-supplied function for each running process in the process list (after radPlistStart is called). |
| Count of affected processes or ERROR |
| This allows the parent process to execute a function on the process pid of each process in the process list. |
| 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);
| 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. |
| OK or ERROR |
| 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);
| Remove a process entry from the list by pid. This may be done when it exits to keep the list up to date. |
| OK or ERROR |
| 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
);
| 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. |
| OK or ERROR |
| 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);
| Signal to the parent process (from the newly started process) that initialization is complete and it is safe to start the next process. |
| OK or ERROR |
| 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)
);
| Find an entry's pid based on its entry point. |
| The process pid if found or ERROR if not |
| This cannot be called until radProcessInit has been successfully called by the new process. |
| 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
);
| Start a new process by forking. |
| The new child pid or ERROR |
| Usually only invoked directly by radPlist functions. |
| 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);
| Initialize the process queue global constructs for this process. If initFlag is TRUE, the global table will be initialized too. |
| OK or ERROR |
| Usually only invoked directly by radSystemInit. Must be called prior to radQueueInit. |
| Type | Name | Description |
| int | initFlag | specify if the global table should be initialized |
radQueueSystemExit() void radQueueSystemExit (int destroy);
| Exit the process attachment to the queue global constructs. If destroy is TRUE, the global table will be destroyed. |
| None |
| Usually only invoked directly by radSystemExit. |
| Type | Name | Description |
| int | destroy | specify if the global table should be destroyed |
radQueueInit() T_QUEUE_ID radQueueInit (char *queueName, int startDummyProc);
| 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. |
| T_QUEUE_ID or NULL |
| Usually only invoked directly by radProcessInit. radQueueSystemInit must be called before this function. |
| Type | Name | Description |
| char * | queueName | full path name of desired process queue |
radQueueExit() void radQueueExit (T_QUEUE_ID id);
| Exit (detach from) the global queue table. |
| None |
| Usually only invoked directly by radProcessExit. |
| Type | Name | Description |
| T_QUEUE_ID | id | queue ID |
radQueueGetFD() int radQueueGetFD
(
T_QUEUE_ID id
);
| Get the queue file descriptor to use in select or poll calls. |
| The file descriptor |
| Usually only invoked directly by radProcessInit. |
| Type | Name | Description |
| T_QUEUE_ID | id | queue ID |
radQueueGetName() char *radQueueGetName (T_QUEUE_ID tqid, char *store);
| Return the full path of the calling process's queue. |
| A pointer to store, which has been updated with the queue name |
| store must be large enough to hold a file path. |
| 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);
| Attach to an individual queue based on queue name so that messages can be sent to it. |
| OK or ERROR |
| 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);
| Detach from an individual queue based on queue name and group number. |
| OK or ERROR |
| 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);
| Add calling process's queue to a group and add the group to calling process's address list. |
| OK or ERROR |
| Type | Name | Description |
| T_QUEUE_ID | id | queue ID |
| int | groupNumber | group number to join |
radQueueQuitGroup() int radQueueQuitGroup (T_QUEUE_ID tqid, int groupNumber);
| Remove calling process's queue from a group and remove a group from calling process's address list. |
| OK or ERROR |
| 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
);
| Read from message queue - populates srcQueueName, msg, length, and msgType. |
| TRUE if msg received, FALSE if queue is empty, ERROR if error |
| 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. |
| 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
);
| Write a message to a queue. |
| OK, ERROR, or ERROR_ABORT if the destination queue is gone |
| 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. |
| 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
);
| 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. |
| OK or ERROR |
| 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. |
| 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);
| Determine if calling process is attached to the given queue name. |
| TRUE or FALSE |
| Type | Name | Description |
| T_QUEUE_ID | id | queue ID |
| char * | queueName | queue name to check status of |
radSemProcessInit() int radSemProcessInit (void);
| Called once during process initialization (usually from radSystemInit). Creates or attaches to an existing semaphore set. |
| OK or ERROR |
| Usually only invoked directly by radSystemInit. |
radSemSetDestroy() void radSemSetDestroy (void);
| Called globally once to destroy a semaphore set (usually from radSystemExit). |
| None |
| Usually only invoked directly by radSystemExit. |
radSemCreate() SEM_ID radSemCreate (int semIndex, int count);
| Create (or attach to) a specific indexed semaphore. |
| SEM_ID or NULL |
| 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);
| 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). |
| None |
| Type | Name | Description |
| SEM_ID | id | semaphore ID |
radSemGive() void radSemGive (SEM_ID id);
| Give (increment) a semaphore's count. If other processes are blocked on the semaphore, this will cause one of them to unblock and run. |
| None |
| Type | Name | Description |
| SEM_ID | id | semaphore ID |
radSemGiveMultiple() void radSemGiveMultiple (SEM_ID id, int numToGive);
| Give multiple (increment by numToGive) a semaphore's count. One or more blocked processes will be unblocked. |
| None |
| Type | Name | Description |
| SEM_ID | id | semaphore ID |
| int | numToGive | value to increment the semaphore count by |
radSemTest() int radSemTest (SEM_ID id);
| 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. |
| TRUE if the semaphore was taken by this call (decremented), FALSE if the semaphore count is 0 |
| Type | Name | Description |
| SEM_ID | id | semaphore ID |
radSemDelete() int radSemDelete (SEM_ID id);
| Release a semaphore allocation. |
| OK or ERROR |
| Type | Name | Description |
| SEM_ID | id | semaphore ID |
radSemDebug() void radSemDebug (void);
| Dump semaphore set information to stdout. |
| None |
| For debug use only. |
radSHA1ComputeBlock() int radSHA1ComputeBlock
(
void *block,
int byteLength,
char digestStore[RADSHA1_DIGEST_STR_LENGTH]
);
| Compute the SHA-1 digest for the memory block 'block' of byte length 'byteLength' and store the result in 'digestStore'. |
| OK or ERROR |
| 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]
);
| Compute the SHA-1 digest for the file given by full path and filename 'filename' and store the result in 'digestStore'. |
| OK or ERROR |
| 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]
);
| Compute the SHA-256 digest for the memory block 'block' of byte length 'byteLength' and store the result in 'digestStore'. |
| OK or ERROR |
| 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]
);
| Compute the SHA-256 digest for the file given by full path and filename 'filename' and store the result in 'digestStore'. |
| OK or ERROR |
| 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);
| Called from a process to test a shared memory block for existence. |
| TRUE if it exists or FALSE if it doesn't |
| 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);
| Allocate or attach to existing shared memory block. |
| SHMEM_ID or NULL |
| 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);
| Get the pointer to the beginning of the shared block as it is represented in the calling process's virtual memory map. |
| the pointer or NULL |
| Type | Name | Description |
| SHMEM_ID | id | shared memory ID |
radShmemLock() void radShmemLock (SHMEM_ID id);
| Lock the shared memory block for exclusive access. Can block execution if another process has the block locked. |
| None |
| Type | Name | Description |
| SHMEM_ID | id | shared memory ID |
radShmemUnlock() void radShmemUnlock (SHMEM_ID id);
| Unlock a shared memory block. |
| None |
| Type | Name | Description |
| SHMEM_ID | id | shared memory ID |
radShmemExit() void radShmemExit (SHMEM_ID id);
| Detach from a shared memory block. Does not destroy it. |
| None |
| Type | Name | Description |
| SHMEM_ID | id | shared memory ID |
radShmemExitAndDestroy() void radShmemExitAndDestroy (SHMEM_ID id);
| Detach from and destroy the shared memory block. |
| None |
| 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. |
| Type | Name | Description |
| SHMEM_ID | id | shared memory ID |
radSocketServerCreate() RADSOCK_ID radSocketServerCreate (int port);
| Create a socket server to listen on port "port". |
| RADSOCK_ID or NULL if there is an error |
| 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. |
| Type | Name | Description |
| int | port | TCP port number to listen for connections on |
radSocketServerAcceptConnection() RADSOCK_ID radSocketServerAcceptConnection (RADSOCK_ID listenServerID);
| Create a new socket instance for the incoming connection and prepare it for read/write activity. |
| The new RADSOCK_ID for the client connection or NULL if there is an error |
| Should be called when there is a "wake up" on the listen socket indicating an incoming connection attempt. |
| 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);
| Create a socket client that connects to "hostNameOrIP" on port "port". Once connected, prepares the socket for read/write activity. |
| The new RADSOCK_ID or NULL if there is an error |
| This provides the "Client" side of the Client-Server paradigm. |
| 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);
| 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. |
| The new RADSOCK_ID or NULL if there is an error |
| This provides the "Client" side of the Client-Server paradigm. |
| 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);
| Close connection and cleanup resources. |
| OK or ERROR |
| 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);
| Get the socket descriptor (for select calls, etc.). |
| The socket descriptor associated with "id". |
| 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);
| Get the socket hostname or IP. |
| The hostname or IP address associated with "id". |
| 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);
| Get the socket hostname or IP. |
| The socket port number associated with "id". |
| 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. |
| 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
);
| Read an exact size (will block if a blocking socket). |
| Bytes read or ERROR if an error occurs. |
| Will return less than requested amount if a non-blocking socket and the read would block or it is interrupted by a received signal. |
| 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
);
| Write an exact size (will block if a blocking socket). |
| Bytes written or ERROR if an error occurs. |
| Will return less than requested amount if a non-blocking socket and the write would block or it is interrupted by a received signal. |
| 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
);
| Set the socket for blocking or non-blocking IO. |
| OK or ERROR |
| 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. |
| 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
);
| Turn on or off data debug which dumps all read/write data to radMsgLog. |
| N/A |
| If enabled, debug will radMsgLog the contents of all RX/TX data. |
| 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));
| 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. |
| SORTLIST_ID or NULL |
| Type | Name | Description |
| int (*) | getKey | application-supplied sorting function |
radSortListExit() void radSortListExit (SORTLIST_ID id);
| This WILL free all nodes on the sorted list before destroying the list. |
| None |
| Type | Name | Description |
| SORTLIST_ID | id | sorted list ID |
radSortListInsert() int radSortListInsert (SORTLIST_ID id, NODE_PTR node);
| Insert node into the list (see radList for details on NODE_PTR type). |
| OK or ERROR |
| 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);
| Find and remove the node given the NODE_PTR. |
| OK or ERROR |
| 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);
| Find a NODE_PTR given the "ordinal" or "key" of the node. |
| The NODE_PTR or NULL |
| 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
);
| Connect to a database server. |
| Returns the DATABASE_ID or NULL |
| Type | Name | Description |
| const char * | dbFilePath | Full path and name of the SQLite database file |
radsqliteClose() void radsqliteClose
(
DATABASE_ID dbId
);
| Close the connection to a database file. |
| None |
| Type | Name | Description |
| DATABASE_ID | dbId | Value returned from successful radsqliteOpen call |
radsqliteQuery() int radsqliteQuery
(
DATABASE_ID dbId,
const char *query,
int createResults
);
| Issue an SQL query against the database. |
| 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'. |
| 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. |
| 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
);
| 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.). |
| Returns RESULT_SET_ID or NULL |
| RESULT_SET_ID should be released via radsqliteTableResultsRelease once the user is finished with it. |
| Type | Name | Description |
| DATABASE_ID | dbId | Value returned from successful radsqliteOpen call |
radsqliteRefreshResults() RESULT_SET_ID radsqliteRefreshResults
(
DATABASE_ID dbId,
RESULT_SET_ID origResultSet
);
| Refresh a result set based on the original query. |
| Returns RESULT_SET_ID or NULL |
| RESULT_SET_ID should be released via radsqliteTableResultsRelease once the user is finished with it. |
| 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
);
| Release a result set. |
| None |
| 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
);
| Does 'tableName' table exist? |
| Returns TRUE or FALSE |
| 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 */
);
| Create a table named 'tableName'. |
| Returns OK or ERROR |
| 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
);
| Drop the table named 'tableName'. |
| Returns OK or ERROR |
| 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
);
| Truncate (empty) the table named 'tableName'. |
| Returns OK or ERROR |
| 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
| Create a row description to use for row insertion/retrieval. |
| Returns ROW_ID or NULL |
| 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). |
| 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
);
| Query a table to create a result set given a row description. |
| Returns RESULT_SET_ID or NULL |
| 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). |
| 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
);
| Insert a row into a table. |
| Returns OK or ERROR |
| '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. |
| 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
);
| Modify rows in 'tableName' matching 'matchId' with the field values defined in 'newData'. |
| Returns OK or ERROR |
| 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. |
| 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
);
| Delete rows in 'tableName' matching 'matchId'. |
| Returns OK or ERROR |
| Only the non-NULL fields will be used to match records in the table (i.e., multiple rows can be matched). |
| 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
);
| Retrieve the first row of a result set. |
| Returns ROW_ID or NULL if the result set is empty |
| Allows traversal of the rows in a result set. |
| Type | Name | Description |
| RESULT_SET_ID | id | result set obtained from radsqliteGetResults or radsqliteTableQueryRow |
radsqliteResultsGetNext() ROW_ID radsqliteResultsGetNext
(
RESULT_SET_ID id
);
| Retrieve the next row of a result set. |
| Returns ROW_ID or NULL if there is no next row |
| Allows traversal of the rows in a result set. |
| Type | Name | Description |
| RESULT_SET_ID | id | result set obtained from radsqliteGetResults or radsqliteTableQueryRow |
radsqliteResultsGetPrev() ROW_ID radsqliteResultsGetPrev
(
RESULT_SET_ID id
);
| Retrieve the previous row of a result set. |
| Returns ROW_ID or NULL if there is no previous row |
| Allows traversal of the rows in a result set. |
| Type | Name | Description |
| RESULT_SET_ID | id | result set obtained from radsqliteGetResults or radsqliteTableQueryRow |
radsqliteResultsGetLast() ROW_ID radsqliteResultsGetLast
(
RESULT_SET_ID id
);
| Retrieve the last row of a result set. |
| Returns ROW_ID or NULL if the result set is empty |
| Allows traversal of the rows in a result set. |
| Type | Name | Description |
| RESULT_SET_ID | id | result set obtained from radsqliteGetResults or radsqliteTableQueryRow |
radsqliteRowDescriptionCreate() ROW_ID radsqliteRowDescriptionCreate
(
void
);
| Create an empty row description to use when describing a new table. |
| Returns ROW_ID or NULL |
| 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
);
| Add a new field to a row description. |
| Returns OK or ERROR |
| 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
);
| Remove a field identified by 'name' from the row description. |
| Returns OK or ERROR |
| 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
);
| Release a row description and the corresponding fields. |
| None |
| Type | Name | Description |
| ROW_ID | id | Value returned from successful radsqliteRowDescriptionCreate call |
radsqliteFieldGet() FIELD_ID radsqliteFieldGet
(
ROW_ID id,
const char *fieldName
);
| Get the field identified by 'fieldName'. |
| Returns FIELD_ID or NULL |
| Type | Name | Description |
| ROW_ID | id | valid row description ID |
| const char * | fieldName | name of field to retrieve |
radsqliteFieldGetType() UINT radsqliteFieldGetType
(
DATABASE_ID id
);
| Retrieve the field type bitmask (see radsqlite.h). |
| Returns the field type bitmask |
|
enum DbFieldTypes |
| Type | Name | Description |
| FIELD_ID | id | valid field ID to retrieve type from |
radsqliteFieldGetBigIntValue() long long radsqliteFieldGetBigIntValue
(
FIELD_ID id
);
| Retrieve the big integer value of the field (must be of type FIELD_BIGINT). |
| Returns the value |
| Type | Name | Description |
| FIELD_ID | id | field to extract value from |
radsqliteFieldGetDoubleValue() double radsqliteFieldGetDoubleValue
(
DATABASE_ID id
);
| Retrieve the double value of the field (must be of type FIELD_DOUBLE). |
| Returns the value |
| Type | Name | Description |
| FIELD_ID | id | field to extract value from |
radsqliteFieldGetCharValue() char *radsqliteFieldGetCharValue
(
FIELD_ID id
);
| Retrieve the string value of the field (must be of type FIELD_STRING). |
| Returns the value |
| Type | Name | Description |
| FIELD_ID | id | field to extract value from |
radsqliteFieldGetCharLength() int radsqliteFieldGetCharLength
(
FIELD_ID id
);
| Retrieve the string length of the field (must be of type FIELD_STRING). |
| Returns the value |
| Type | Name | Description |
| FIELD_ID | id | field to extract value from |
radsqliteFieldSetTypeBigInt() int radsqliteFieldSetTypeBigInt
(
FIELD_ID id
);
| Set the field type to FIELD_BIGINT. |
| Returns OK |
| Type | Name | Description |
| FIELD_ID | id | valid field ID |
radsqliteFieldSetTypeDouble() int radsqliteFieldSetTypeDouble
(
FIELD_ID id
);
| Set the field type to FIELD_DOUBLE. |
| Returns OK |
| Type | Name | Description |
| FIELD_ID | id | valid field ID |
radsqliteFieldSetTypeChar() int radsqliteFieldSetTypeChar
(
FIELD_ID id
);
| Set the field type to FIELD_STRING. |
| Returns OK |
| Type | Name | Description |
| FIELD_ID | id | valid field ID |
radsqliteFieldSetToNull() int radsqliteFieldSetToNull
(
FIELD_ID id
);
| Set the field flag to NULL (empty). |
| Returns OK |
| Type | Name | Description |
| FIELD_ID | id | valid field ID |
radsqliteFieldSetToNotNull() int radsqliteFieldSetToNotNull
(
FIELD_ID id
);
| Set the field flag to NOT NULL (not empty). |
| Returns OK |
| Type | Name | Description |
| FIELD_ID | id | valid field ID |
radsqliteFieldSetBigIntValue() int radsqliteFieldSetBigIntValue
(
FIELD_ID id,
long long value
);
| Set the big integer field value. |
| Returns OK |
| Type | Name | Description |
| FIELD_ID | id | valid field ID |
| long long | value | value to set |
radsqliteFieldSetDoubleValue() int radsqliteFieldSetDoubleValue
(
FIELD_ID id,
double value
);
| Set the double field value. |
| Returns OK |
| 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
);
| Set the string field value. |
| Returns OK |
| 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);
| Create a an empty stack. |
| STACK_ID or NULL |
radStackExit() void radStackExit (STACK_ID id);
| Delete a stack, freeing all the nodes as well. |
| None |
| Type | Name | Description |
| STACK_ID | id | stack ID |
radStackPush() int radStackPush (STACK_ID id, STACK_NODE *newNode);
| Push an object onto the stack. |
| OK or ERROR |
| 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);
| Pop an object off the stack. |
| STACK_NODE or NULL if the stack is empty |
| Type | Name | Description |
| STACK_ID | id | stack ID |
radStackCount() int radStackCount (STACK_ID id);
| Get the count of objects on the stack. |
| Stack count |
| Type | Name | Description |
| STACK_ID | id | stack ID |
radStatesInit() STATES_ID radStatesInit (void *saveData);
| Create and initialize a state machine. |
| STATES_ID or NULL |
| State values MUST be 0-based and contiguous. |
| 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);
| Destroy a state machine. |
| None |
| 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)
);
| Add a state processor to the state machine. state MUST be < STATE_MAX_STATES defined in radstates.h. |
| OK or ERROR |
| handler must ALWAYS return the next state of the machine. |
| 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);
| Remove a processor (resets the handler to the stub handler). |
| OK or ERROR |
| 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);
| Process an application-defined stimulus. Stimuli can be messages, timers, events, file descriptors, etc. |
| None |
| 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);
| Change the state of the machine |
| OK or ERROR |
| Usually only invoked during state machine initialization. When called from within a state machine handler, bad side-effects can occur. |
| Type | Name | Description |
| STATES_ID | id | state machine ID |
| int | state | new state for the state machine |
radStatesGetState() int radStatesGetState (STATES_ID id);
| Get the currently active state of the machine. |
| current state of the state machine |
| Type | Name | Description |
| STATES_ID | id | state machine ID |
radStatesReset() void radStatesReset (STATES_ID id, void *saveData);
| Reset all handlers to the stub handler and set the new user data to saveData. |
| None |
| Type | Name | Description |
| STATES_ID | id | state machine ID |
| void * | saveData | new user data for the state machine |
radSystemInit() int radSystemInit (UCHAR systemID);
| Initialize a unique radlib system and/or register the calling process within an existing radlib system. |
| OK or ERROR |
| 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. |
| 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);
| Deregister the calling process from a unique radlib system and destroy all facilities if it is the last process left in the radlib system. |
| OK or ERROR |
| 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. |
| 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);
| Returns the number of milliseconds since radSystemInit was first called with this "systemID". |
| Number of milliseconds since radSystemInit was first called with this "systemID" |
| 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. |
| 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);
| Returns the number of seconds since radSystemInit was first called with this "systemID". |
| Number of seconds since radSystemInit was first called with this "systemID" |
| 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. |
| 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);
| 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". |
| The up time string |
| 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. |
| 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
);
| Create and start a thread. |
| the new RAD_THREAD_ID or NULL if not successful |
| See the header file radthread.h for more details. |
| 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);
|
Set the exit flag and wait for the thread described by threadId to exit. |
| N/A |
| Will block until the thread terminates. |
| Type | Name | Description |
| RAD_THREAD_ID | threadId | unique thread ID |
radthreadSendToThread()
int radthreadSendToThread
(
RAD_THREAD_ID threadId,
int type,
void* data,
int length
);
|
Send data (thread safe) to the thread described by threadId. |
| OK or ERROR |
|
Uses internal mutex and condition variable to provide thread safe delivery and notification. |
| 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
);
|
Receive data (thread safe) from the thread described by threadId. |
| User-defined msg type or ERROR_ABORT if non-blocking and no msg available. |
|
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. |
| 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
);
|
Send data (thread safe) to the parent of the thread described by threadId. |
| OK or ERROR |
|
Uses internal mutex and condition variable to provide thread safe delivery and notification. |
| 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
);
|
Receive data (thread safe) from the parent of the thread described by threadId. |
| User-defined msg type or ERROR_ABORT if non-blocking and no msg available. |
|
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. |
| 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);
|
Thread described by threadId test for exit command from parent. |
| TRUE (non-zero) if the thread should exit, FALSE (0) otherwise. |
| Thread should call this function periodically and exit if it returns TRUE. |
| Type | Name | Description |
| RAD_THREAD_ID | threadId | unique thread ID |
radthreadLock()
int radthreadLock(void);
|
Lock the general thread mutex for this process. |
| N/A |
| This mutex should not be held when calling radMsgRouterMessageSend. |
radthreadUnlock()
int radthreadUnlock(void);
|
Release the general thread mutex for this process. |
| N/A |
| This mutex should not be held when calling radMsgRouterMessageSend. |
radUtilsSetIntervalTimer() int radUtilsSetIntervalTimer (int msecs);
| Start the system interval timer to deliver SIGALRM after msecs milliseconds. |
| OK or ERROR |
| Usually only invoked directly by radTimer functions. If radTimers are running, manual manipulation of the system timer will corrupt the timer subsystem. |
| Type | Name | Description |
| int | msecs | number of milliseconds for the timer expiry |
radUtilsSetIntervalTimer() int radUtilsSetIntervalTimer (int msecs);
| Start the system interval timer to deliver SIGALRM after msecs milliseconds. |
| OK or ERROR |
| Usually only invoked directly by radTimer functions. If radTimers are running, manual manipulation of the system timer will corrupt the timer subsystem. |
| Type | Name | Description |
| int | msecs | number of milliseconds for the timer expiry |
radUtilsGetIntervalTimer() int radUtilsGetIntervalTimer (void);
| Get the value of the real interval timer in milliseconds. |
| milliseconds before the next system timer delivers SIGALRM |
| Usually only invoked directly by radTimer functions. |
radUtilsEnableSignal() int radUtilsEnableSignal (int signum);
| Allow a signal to be received (see signal.h). |
| OK or ERROR |
| Usually only invoked directly by radlib functions. |
| Type | Name | Description |
| int | signum | signal to enable |
radUtilsDisableSignal() int radUtilsDisableSignal (int signum);
| Disallow a signal from being received (see signal.h). |
| OK or ERROR |
| Usually only invoked directly by radlib functions. |
| Type | Name | Description |
| int | signum | signal to disable |
radUtilsBecomeDaemon() int radUtilsBecomeDaemon (const char *workingDirectory);
| 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. |
| the new process pid or ERROR |
| Usually only invoked directly by radProcessInit. |
| Type | Name | Description |
| char * | workingDirectory | working directory of new daemon process (if not NULL) |
radUtilsSleep() void radUtilsSleep (int msDuration);
| Provide a sleep function with ms resolution. |
| None |
| Type | Name | Description |
| int | msDuration | milliseconds to sleep |
radtextsearchInit() TEXT_SEARCH_ID radtextsearchInit (void);
| Create a text search object. |
| New search ID or ERROR if the ID cannot be allocated |
radtextsearchExit() void radtextsearchExit (TEXT_SEARCH_ID id);
| Cleanup and delete a search object. |
| N/A |
| 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);
| Insert a member of the text string universe. |
| OK or ERROR if a new node cannot be allocated. |
| 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);
| Delete a member of the universe. |
| OK if found/removed, ERROR otherwise. |
| 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);
| Find a member of the universe and return the corresponding ordinal in ordinalStore. |
| OK if found (and ordinalStore populated) or ERROR if not found. |
| 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);
| Create a timer list for the calling process. Timer expiries are notified through the notifyDescriptor. |
| OK or ERROR |
| Usually only invoked directly by radProcessInit. |
| 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);
| Delete the calling process's timer list. |
| None |
| Usually only invoked directly by radProcessExit. |
radTimerCreate() TIMER_ID radTimerCreate (TIMER_ID timer, void (*routine)
(void *parm), void *parm);
| Create a timer object from the timer list free pool. |
| TIMER_ID or NULL |
| 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);
| Release a timer instance to the timer list free pool. |
| None |
| Type | Name | Description |
| TIMER_ID | timer | timer to release |
radTimerStart() void radTimerStart (TIMER_ID timer, int time);
| Start the timer for time milliseconds. |
| None |
| Type | Name | Description |
| TIMER_ID | timer | timer ID |
| int | time | milliseconds for timer duration |
radTimerStop() void radTimerStop (TIMER_ID timer);
| Stop a running timer. |
| None |
| Type | Name | Description |
| TIMER_ID | timer | timer ID to stop |
radTimerStatus() int radTimerStatus (TIMER_ID timer);
| Determine if the timer is running. |
| TRUE or FALSE |
| Type | Name | Description |
| TIMER_ID | timer | timer ID to status |
radTimerSetUserParm() void radTimerSetUserParm (TIMER_ID timer, void *newParm);
| Reset the user pointer passed to the callback routine. |
| None |
| Type | Name | Description |
| TIMER_ID | timer | timer ID |
| void * | newParm | new user pointer for callback |
radTimeGetMSSinceEpoch() ULONGLONG radTimeGetMSSinceEpoch (void);
| Returns the time in milliseconds since midnight, January 1, 1970 |
| milliseconds since the EPOCH |
radTimeGetSECSinceEpoch() ULONG radTimeGetSECSinceEpoch (void);
| Returns the time in seconds since midnight, January 1, 1970 |
| seconds since the EPOCH |
radUDPSocketCreate() RADUDPSOCK_ID radUDPSocketCreate (void);
| Create a datagram socket. |
| RADUDPSOCK_ID or NULL if there is an error |
| 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);
| Close connection and cleanup resources. |
| OK or ERROR |
| Type | Name | Description |
| RADUDPSOCK_ID | id | Valid socket ID obtained from a successful call to radUDPSocketCreate |
radSocketGetDescriptor() int radSocketGetDescriptor (RADUDPSOCK_ID id);
| Get the socket descriptor (for select calls, etc.). |
| The socket descriptor associated with "id". |
| Type | Name | Description |
| RADUDPSOCK_ID | id | Valid socket ID obtained from a successful call to radUDPSocketCreate |
radUDPSocketBind() int radUDPSocketBind (RADUDPSOCK_ID id, USHORT port);
| Bind the UDP socket to a local port so you can add the socket descriptor to your select list and receive data. |
| OK or ERROR |
| 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);
| Enable/Disable sending broadcast packets. |
| OK or ERROR |
| 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
);
| Set multicast interface for outgoing datagrams. |
| OK or ERROR |
| 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);
| Set multicast TTL for outgoing datagrams (1 by default). |
| OK or ERROR |
| 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. |
| 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);
| Enable/Disable multicast loopback (disabled by default). |
| OK or ERROR |
| 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
);
| "Turn on" RX multicast datagrams on the "multicastGroupIP" group and "interfaceIP" interface. |
| OK or ERROR |
| Enables multicast packet reception for the given multicast group (IP address) on the given local interface (IP address). |
| 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
);
| "Turn off" RX multicast datagrams on the "multicastGroupIP" group and "interfaceIP" interface. |
| OK or ERROR |
| Disables multicast packet reception for the given multicast group (IP address) on the given local interface (IP address). |
| 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
);
| Receive a datagram from a UDP socket. |
| Bytes read or ERROR if an error occurs. |
| Will return less than requested amount based on the size of the datagram or if it is interrupted by a received signal. |
| 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
);
| Send a datagram to a host name or IP adrs and port (connectionless). |
| OK or ERROR |
| 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
);
| Set the socket for blocking or non-blocking IO. |
| OK or ERROR |
| 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. |
| 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
);
| Turn on or off data debug which dumps all read/write datagrams to msgLog. |
| N/A |
| If enabled, debug will radMsgLog the contents of all RX/TX datagrams. |
| 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 |