Sending Commands to STK Using Connect
Once you've established a connection to STK, you can send and receive data using the AgConProcessSTKCmd()
function, whose prototype is:
int
AgConProcessSTKCmd (
char *context,
char *cmdString,
AgTConReturnInfo *returnInfo
);
The context
argument, is the value returned from the AgConOpenSTK
function, defined during connection, and identifies the connection to which commands are sent.
The cmdString
argument is a character string containing the Connect command to be sent.
The returnInfo
argument is a structure that contains any information returned by STK.
Connect takes information returned from STK and places it in a AgTConReturnInfo
structure:
typedef struct AgTConReturnInfo
{
char hdrType[AgCRMHAHdrTypeLen+1];
char transId[AgCRMHAHdrIdLen+1];
int numEntries;
char **returnList;
} AgTConReturnInfo;
The hdrType
and transId
fields are relevant only when Connect is in Async mode. The hdrType
field stores type information contained in an asynchronous header. The transId
field stores the transaction identification number, also returned in an asynchronous header.
The numEntries
field identifies the number of data items being returned by STK. Finally, the returnList
field is an array of strings that contains the returned data. The number of array elements is the same as the numEntries
field for the structure.
The returnList
portion of AgTConReturnInfo()
is an allocated array of pointers. The number of array elements allocated depends on the number of messages returned for a given command. Each array element is then allocated sufficient space to hold the returned message. You must free the space allocated with the AgConCleanupReturnInfo
.
You must use the AgConCleanupReturnInfo
function to free the memory returned by AgConProcessSTKCmd(), otherwise processing errors will occur.
The AgConCleanupReturnInfo() prototype is:
void
AgConCleanupReturnInfo (
AgTConReturnInfo *pReturnInfo
);
The AgConCleanupReturnInfo()
function frees the memory associated with the structure pointed to by the pReturnInfo
parameter.
AgConProcessSTKCmd()
returns AgCNoError
if successful, AgCError
if an error occurs and AgCNackReturned
if the command was sent successfully but was rejected by STK.
See the Connect Example File.
Sending Connect commands to STK will not function as expected if the decimal separator character in the regional settings of the operating system is set to a comma.