C Interface¶

Defines

cisOutput_t¶

Flag for checking if CisInterface.h has already been included.

Aliases to preserve names of original structures.

cisInput_t¶

cis_free¶

cisSend¶

Send arguments as a small formatted message to an output queue. Use the format string to create a message from the input arguments that is then sent to the specified output queue. If the message is larger than CIS_MSG_MAX or cannot be encoded, it will not be sent.

Formatted IO

Output Usage:

One-time: Create output channel with format specifier. cisOutput_t output_channel = cisOutputFmt(“out_name”, “a=%d, b=%d”);
Send: ret = cisSend(output_channel, 1, 2);
Free: cis_free(&output_channel);

Input Usage:

One-time: Create output channel with format specifier. cisInput_t input_channel = cisInput(“in_name”, “a=%d, b=%d”);
Prepare: Allocate space for recovered variables. int a, b;
Receive: int ret = cisRecv(input_channel, &a, &b);

Return

int 0 if send succesfull, -1 if send unsuccessful.

Parameters

cisQ: cisOutput_t structure that queue should be sent to.
...: arguments to be formatted into a message using sprintf.

cisRecv¶

Assign arguments by receiving and parsing a message from an input queue. Receive a message smaller than CIS_MSG_MAX bytes from an input queue and parse it using the associated format string.

Return

int -1 if message could not be received or could not be parsed. Length of the received message if message was received and parsed.

Parameters

cisQ: cisOutput_t structure that message should be sent to.
...: arguments that should be assigned by parsing the received message using sscanf. As these are being assigned, they should be pointers to memory that has already been allocated.

cisRecvRealloc¶

vcisSend¶: Definitions for symmetry, but there is no difference.

vcisRecv¶

vcisSend_nolimit¶

vcisRecv_nolimit¶

cisSend_nolimit¶

cisRecv_nolimit¶

cisRpc_t¶

Remote Procedure Call (RPC) structure. Contains information required to coordinate sending/receiving response/requests from/to an RPC server/client.

Remote Procedure Call (RPC) IO

Handle IO case of a server receiving input from clients, performing some calculation, and then sending a response back to the client.

Server Usage:

One-time: Create server channels with format specifiers for input and output. cisRpc_t srv = cisRpcServer(“srv_name”, “%d”, “%d %d”);
Prepare: Allocate space for recovered variables from request. int a;
Receive request: int ret = rpcRecv(srv, &a);
Process: Do tasks the server should do with input to produce output. int b = 2*a; int c = 3*a;
Send response: ret = rpcSend(srv, b, c);

Client Usage:

One-time: Create client channels to desired server with format specifiers for output and input (should be the same arguments as for the server except for name). cisRpc_t cli = cisRpcClient(“cli_name”, “%d”, “%d %d”);
Prepare: Allocate space for recovered variables from response. int b, c;
Call server: int ret = rpcCall(cli, 1, &b, &c);

Clients can also send several requests at once before receiving any responses. This allows the server to be processing the next requests while the client handles the previous response, thereby increasing efficiency. The responses are assumed to be in the same order as the generating requests (i.e. first come, first served).

vrpcSend¶

Format and send a message to an RPC output queue. Format provided arguments list using the output queue format string and then sends it to the output queue under the assumption that it is larger than the maximum message size.

Return

integer specifying if the send was succesful. Values >= 0 indicate success.

Parameters

rpc: cisRpc_t structure with RPC information.
ap: va_list variable list of arguments for formatting.

vrpcRecv(rpc, nargs, ap)¶

Receive and parse a message from an RPC input queue. Receive a message from the input queue under the assumption that it is larger than the maximum message size. Then parse the message using the input queue format string to extract parameters and assign them to the arguments.

Return

integer specifying if the receive was succesful. Values >= 0 indicate success.

Parameters

rpc: cisRpc_t structure with RPC information.
nargs: int Number of arguments contained in ap.
ap: va_list variable list of arguments that should be assigned parameters extracted using the format string. Since these will be assigned, they should be pointers to memory that has already been allocated.

vrpcRecvRealloc(rpc, nargs, ap)¶

rpcSend¶

Format and send a message to an RPC output queue. Format provided arguments using the output queue format string and then sends it to the output queue under the assumption that it is larger than the maximum message size.

Return

integer specifying if the send was succesful. Values >= 0 indicate success.

Parameters

rpc: cisRpc_t structure with RPC information.
...: arguments for formatting.

rpcRecv¶

Receive and parse a message from an RPC input queue. Receive a message from the input queue under the assumption that it is larger than the maximum message size. Then parse the message using the input queue format string to extract parameters and assign them to the arguments.

Return

integer specifying if the receive was succesful. Values >= 0 indicate success.

Parameters

rpc: cisRpc_t structure with RPC information.
...: mixed arguments that should be assigned parameters extracted using the format string. Since these will be assigned, they should be pointers to memory that has already been allocated.

rpcRecvRealloc¶

vrpcCall(rpc, nargs, ap)¶

vrpcCallRealloc(rpc, nargs, ap)¶

rpcCall(rpc, ...)¶

rpcCallRealloc(rpc, ...)¶

cisAsciiFileInput_t¶

Definitions for file sturctures.

File IO

Handle I/O from/to a file line by line.

Input Usage:

One-time: Create file interface by providing a channel name. comm_t fin = cisAsciiFileInput(“file_channel”);
Prepare: Get pointer for line. char *line;
Receive each line, terminating when receive returns -1 (EOF or channel closed). int ret = 1; while (ret > 0) { ret = cisRecv(fin, &line); // line will be realloced to fit message Do something with the line }
Cleanup. Call functions to deallocate structures. free(line);

Output Usage:

One-time: Create file interface by providing a channel name. comm_t fout = cisAsciiFileOutput(“file_channel”);
Send lines to the file. If return value is not 0, the send was not succesfull. int ret; ret = cisSend(fin, “Line 1\n”); ret = cisSend(fout, “Line 1\n”); ret = cisSend(fout, “Line 2\n”);

cisAsciiFileOutput_t¶

cisAsciiTableInput_t¶

Definitions for table sturctures.

Table IO

Handle I/O from/to an ASCII table either line-by-line or as an array.

Row-by-Row

Input by Row Usage:

One-time: Create file interface by providing a channel name. comm_t fin = cisAsciiTableInput(“file_channel”);
Prepare: Allocate space for variables in row (the format in this example is “%5s %d %f\n” like the output example below). char a[5]; int b; double c;
Receive each row, terminating when receive returns -1 (EOF or channel closed). int ret = 1; while (ret > 0) { ret = cisRecv(fin, &a, &b, &c); Do something with the row }

Output by Row Usage:

One-time: Create file interface by providing a channel name and a format string for rows. comm_t fout = cisAsciiTableOutput(“file_channel”, “%5s %d %f\n”);
Send rows to the file by providing entries. Formatting is handled by the interface. If return value is not 0, the send was not succesful. int ret; ret = cisSend(fout, “one”, 1, 1.0); ret = cisSend(fout, “two”, 2, 2.0);

Array

Input by Array Usage:

One-time: Create file interface by providing a channel name. comm_t fin = cisAsciiArrayInput(“file_channel”);
Prepare: Declare pointers for table columns (they will be allocated by the interface once the number of rows is known). char *aCol; int *bCol; double *cCol;
Receive entire table as columns. Return value will be the number of elements in each column (the number of table rows). Negative values indicate errors. int ret = cisRecv(fin, &a, &b, &c);
Cleanup. Call functions to deallocate structures. free(a); free(b); free(c);

Output by Array Usage:

One-time: Create file interface by providing a channel name and a format string for rows. comm_t fout = cisAsciiArrayOutput(“file_channel”, “%5s %d %f\n”);
Send columns to the file by providing pointers (or arrays). Formatting is handled by the interface. If return value is not 0, the send was not succesful. char aCol[] = {“one “, “two “, “three”}; \ Each str is of len 5 int bCol[3] = {1, 2, 3}; float cCol[3] = {1.0, 2.0, 3.0}; int ret = cisSend(fout, a, b, c);

cisAsciiTableOutput_t¶

cisAsciiArrayInput_t¶

cisAsciiArrayOutput_t¶

cisPlyInput_t¶

Definitions for ply structures.

Ply IO

Handle I/O from/to a Ply file.

Input Usage:

One-time: Create file interface by providing a channel name. comm_t fin = cisPlyInput(“file_channel”); // channel
Prepare: Allocate ply structure. ply_t p;
Receive each structure, terminating when receive returns -1 (EOF or channel closed). int ret = 1; while (ret > 0) { ret = cisRecv(fin, &p); Do something with the ply structure }

Output by Usage:

One-time: Create file interface by providing a channel name. comm_t fout = cisPlyOutput(“file_channel”); // channel
Send structure to the file by providing entries. Formatting is handled by the interface. If return value is not 0, the send was not succesful. int ret; ply_t p; Populate the structure ret = cisSend(fout, p); ret = cisSend(fout, p);

cisPlyOutput_t¶

cisObjInput_t¶

Definitions for obj structures.

Obj IO

Handle I/O from/to a Obj file.

Input Usage:

One-time: Create file interface by providing a channel name. comm_t fin = cisObjInput(“file_channel”); // channel
Prepare: Allocate obj structure. obj_t p;
Receive each structure, terminating when receive returns -1 (EOF or channel closed). int ret = 1; while (ret > 0) { ret = cisRecv(fin, &p); Do something with the obj structure }

Output by Usage:

One-time: Create file interface by providing a channel name. comm_t fout = cisObjOutput(“file_channel”); // channel
Send structure to the file by providing entries. Formatting is handled by the interface. If return value is not 0, the send was not succesful. int ret; obj_t p; Populate the structure ret = cisSend(fout, p); ret = cisSend(fout, p);

cisObjOutput_t¶

Functions

static cisOutput_t cisOutputFmt(const char *name, const char *fmtString)¶

Constructor for cisOutput_t structure with format. Create a cisOutput_t structure based on a provided name that is used to locate a particular comm address stored in the environment variable name and a format string that can be used to format arguments into outgoing messages for the queue.

Basic IO

Output Usage:

One-time: Create output channel (store in named variables) cisOutput_t output_channel = cisOutput(“out_name”);
Prepare: Format data to a character array buffer. char buffer[CIS_MSG_BUF]; sprintf(buffer, “a=%d, b=%d”, 1, 2);
Send: ret = cis_send(output_channel, buffer, strlen(buffer));

Input Usage:

One-time: Create output channel (store in named variables) cisInput_t input_channel = cisInput(“in_name”);
Prepare: Allocate a character array buffer. char buffer[CIS_MSG_BUF];
Receive: int ret = cis_recv(input_channel, buffer, CIS_MSG_BUF);

Return

cisOutput_t output queue structure.

Parameters

name: constant character pointer to name of queue.
fmtString: character pointer to format string.

static cisInput_t cisInputFmt(const char *name, const char *fmtString)¶

Constructor for cisInput_t structure with format. Create a cisInput_t structure based on a provided name that is used to locate a particular comm address stored in the environment variable name and a format stirng that can be used to extract arguments from received messages.

Return

cisInput_t input queue structure.

Parameters

name: constant character pointer to name of queue.
fmtString: character pointer to format string.

static cisOutput_t cisOutput(const char *name)¶

Constructor for cisOutput_t output structure. Create a cisOutput_t structure based on a provided name that is used to locate a particular comm address stored in the environment variable name.

Return

cisOutput_t output queue structure.

Parameters

name: constant character pointer to name of queue.

static cisInput_t cisInput(const char *name)¶

Constructor for cisInput_t structure. Create a cisInput_t structure based on a provided name that is used to locate a particular comm address stored in the environment variable name.

Return

cisInput_t input queue structure.

Parameters

name: constant character pointer to name of queue.

static int cis_send(const cisOutput_t cisQ, const char *data, const size_t len)¶

Send a message to an output queue. Send a message smaller than CIS_MSG_MAX bytes to an output queue. If the message is larger, it will not be sent.

Return

int 0 if send succesfull, -1 if send unsuccessful.

Parameters

cisQ: cisOutput_t structure that queue should be sent to.
data: character pointer to message that should be sent.
len: size_t length of message to be sent.

static int cis_send_eof(const cisOutput_t cisQ)¶

Send EOF message to the output queue.

Return

int 0 if send successfull, -1 if unsuccessful.

Parameters

cisQ: cisOutput_t structure that message should be sent to.

static int cis_recv(const cisInput_t cisQ, char *data, const size_t len)¶

Receive a message from an input queue. Receive a message smaller than CIS_MSG_MAX bytes from an input queue.

Return

int -1 if message could not be received. Length of the received message if message was received.

Parameters

cisQ: cisOutput_t structure that message should be sent to.
data: character pointer to allocated buffer where the message should be saved.
len: const size_t length of the allocated message buffer in bytes.

static int cis_send_nolimit(const cisOutput_t cisQ, const char *data, const size_t len)¶

Send a large message to an output queue. Send a message larger than CIS_MSG_MAX bytes to an output queue by breaking it up between several smaller messages and sending initial message with the size of the message that should be expected. Must be partnered with cis_recv_nolimit for communication to make sense.

Return

int 0 if send succesfull, -1 if send unsuccessful.

Parameters

cisQ: cisOutput_t structure that message should be sent to.
data: character pointer to message that should be sent.
len: size_t length of message to be sent.

static int cis_send_nolimit_eof(const cisOutput_t cisQ)¶

Send EOF message to the output queue.

Return

int 0 if send successfull, -1 if unsuccessful.

Parameters

cisQ: cisOutput_t structure that message should be sent to.

static int cis_recv_nolimit(const cisInput_t cisQ, char **data, const size_t len)¶

Receive a large message from an input queue. Receive a message larger than CIS_MSG_MAX bytes from an input queue by receiving it in parts. This expects the first message to be the size of the total message.

Return

int -1 if message could not be received. Length of the received message if message was received.

Parameters

cisQ: cisOutput_t structure that message should be sent to.
data: character pointer to pointer for allocated buffer where the message should be stored. A pointer to a pointer is used so that the buffer may be reallocated as necessary for the incoming message.
len: size_t length of the initial allocated message buffer in bytes.

static comm_t cisRpcClient(const char *name, const char *outFormat, const char *inFormat)¶

Constructor for client side RPC structure. Creates an instance of cisRpc_t with provided information.

Return

cisRpc_t structure with provided info.

Parameters

name: constant character pointer to name for queues.
outFormat: character pointer to format that should be used for formatting output.
inFormat: character pointer to format that should be used for parsing input.

static comm_t cisRpcServer(const char *name, const char *inFormat, const char *outFormat)¶

Constructor for server side RPC structure. Creates an instance of cisRpc_t with provided information.

Return

cisRpc_t structure with provided info.

Parameters

name: constant character pointer to name for queues.
inFormat: character pointer to format that should be used for parsing input.
outFormat: character pointer to format that should be used for formatting output.

static int vrpcCallBase(const cisRpc_t rpc, const int allow_realloc, size_t nargs, va_list_t ap)¶

Send request to an RPC server from the client and wait for a response. Format arguments using the output queue format string, send the message to the output queue, receive a response from the input queue, and assign arguments from the message using the input queue format string to parse it.

Return

integer specifying if the receive was succesful. Values >= 0 indicate success.

Parameters

rpc: cisRpc_t structure with RPC information.
allow_realloc: int If 1, output arguments are assumed to be pointers to pointers such that they can be reallocated as necessary to receive incoming data. If 0, output arguments are assumed to be preallocated.
nargs: size_t Number of arguments contained in ap including both input and output arguments.
ap: va_list mixed arguments that include those that should be formatted using the output format string, followed by those that should be assigned parameters extracted using the input format string. These that will be assigned should be pointers to memory that has already been allocated.

static int nrpcCallBase(const cisRpc_t rpc, const int allow_realloc, size_t nargs, ...)¶

Send request to an RPC server from the client and wait for a response. Format arguments using the output queue format string, send the message to the output queue, receive a response from the input queue, and assign arguments from the message using the input queue format string to parse it.

Return

integer specifying if the receive was succesful. Values >= 0 indicate success.

Parameters

rpc: cisRpc_t structure with RPC information.
allow_realloc: int If 1, output arguments are assumed to be pointers to pointers such that they can be reallocated as necessary to receive incoming data. If 0, output arguments are assumed to be preallocated.
nargs: size_t Number of arguments contained in ap including both input and output arguments.
...: mixed arguments that include those that should be formatted using the output format string, followed by those that should be assigned parameters extracted using the input format string. These that will be assigned should be pointers to memory that has already been allocated.

static comm_t cisAsciiFileOutput(const char *name)¶

Constructor for AsciiFile output comm to channel.

Return

comm_t for line-by-line output to a file or channel.

Parameters

name: constant character pointer to name of an output channel.

static comm_t cisAsciiFileInput(const char *name)¶

Constructor for AsciiFile input comm from channel.

Return

comm_t for line-by-line input from a file or channel.

Parameters

name: constant character pointer to name of an input channel.

static comm_t cisAsciiTableOutput(const char *name, const char *format_str)¶

Constructor for table output comm to an output channel.

Return

comm_t output structure.

Parameters

name: constant character pointer to output channel name.
format_str: character pointer to format string that should be used to format rows into table lines.

static comm_t cisAsciiTableInput(const char *name)¶

Constructor for AsciiTable input comm from an input channel.

Return

comm_t input structure.

Parameters

name: constant character pointer to input channel name.

static comm_t cisAsciiArrayOutput(const char *name, const char *format_str)¶

Constructor for table output comm with array output.

Return

comm_t output structure.

Parameters

name: constant character pointer to an output channel name.
format_str: character pointer to format string that should be used to format rows into table lines.

static comm_t cisAsciiArrayInput(const char *name)¶

Constructor for AsciiTable input comm with array input.

Return

comm_t input structure.

Parameters

name: constant character pointer to an input channel name.

static comm_t cisPlyOutput(const char *name)¶

Constructor for ply output comm to an output channel.

Return

comm_t output structure.

Parameters

name: constant character pointer to output channel name.

static comm_t cisPlyInput(const char *name)¶

Constructor for ply input comm from an input channel.

Return

comm_t input structure.

Parameters

name: constant character pointer to input channel name.

static comm_t cisObjOutput(const char *name)¶

Constructor for obj output comm to an output channel.

Return

comm_t output structure.

Parameters

name: constant character pointer to output channel name.

static comm_t cisObjInput(const char *name)¶

Constructor for obj input comm from an input channel.

Return

comm_t input structure.

Parameters

name: constant character pointer to input channel name.