Table of Contents
The details the functions available in the Storyboard IO library,
libgreio.a, are also documented in the Storyboard IO header
file gre/greio.h>.
int gre_io_add_mdata(
gre_io_serialized_data_t ** mbuffer,
const char * key_name,
const char * data_format,
const void * data,
int data_nbytes
)
Add a data change key/value pair to a serialized buffer. This call can be used to serialize multiple data changes into a single Storyboard IO send operation to improve efficiency.
Once an multi-part data buffer is constructed, it can be sent using the
gre_io_send_mdata function.
Parameters:
buffer The buffer containing the serialized data
key_name The data key which is to be set
data_format The format for the data to be set
data The data value to set
data_nbytes The number of bytes used for the data
Returns:
-1 on failure anything else is success
void gre_io_close(
gre_io_t * handle
)
Close an io connection. Any pending clients will return with an error on their pending actions.
Parameters:
handle A valid handle created with gre_io_open()
void gre_io_free_buffer(
gre_io_serialized_data_t * buffer
)
This de-allocates the memory associated with a buffer created through the Storyboard IO API.
Parameters:
buffer The buffer whose memory is to be de-allocated
void gre_io_grow_buffer(
gre_io_t* handle,
gre_io_serialized_data_t * buffer
)
This function attempts to expand the internal capacity of the Storyboard IO transport to ensure that the payload contained within serialized buffer can be transmitted.
This call is not supported by all platforms and may fail if the transport buffer can not be resized.
Parameters:
handle The handle to the Storyboard IO channel to resize
buffer The buffer whose capacity is to be matched by the transport
Returns:
-1 on failure otherwise success
gre_io_t* gre_io_open(
const char * io_name,
int flag,
...
)
Open a Storyboard IO communication channel using a named connection.
Parameters:
io_name The name of the io-channel to use
flags The mode you want to open the queue in
Flags define how the connection is opend. Possible flags are:
GRE_IO_TYPE_RDONLY: open read only, creating the channel if it doesn't exist
GRE_IO_TYPE_XRDONLY: open for exclusive read, unlinking an existing channel and creating a new one
GRE_IO_TYPE_WRONLY: open write only
GRE_IO_FLAG_NONBLOCK: open non-blocking
Returns:
Returns a valid Storyboard IO handle or NULL if no channel can be created.
int gre_io_receive(
gre_io_t * handle,
gre_io_serialized_data_t ** buffer
)
Receive a serialized event from a channel. By default this call blocks
until an event is received or until the channel is destroyed unless the
GRE_IO_FLAG_NONBLOCK flag was passed to the
gre_io_open()call.
In order to receive events, the handle must have been opened for reading
using one of GRE_IO_RDONLY or
GRE_IO_XRDONLY.
Parameters:
handle A valid handle created with gre_io_open()
buffer A pointer to a serialized buffer pointer. If the buffer is NULL then a new
buffer is allocated otherwise the buffer provided is used to store the received event.
Returns:
The size of the message received in bytes or -1 on failure.
When a data buffer is successfully received, the event specific content can be extracted by
making a call to gre_io_unserialize. The values returned by the unserialize call
will be pointers directly into the memory allocated to the data buffer. Clients can read and
write to the extracted values (such as event name, event format and data payload) directly
as long as the serialized buffer is not re-used at the same time. Any data from the event
that needs to be maintained across calls to gre_io_receive must be copied by
the user before the serialized buffer is re-used.
int gre_io_send(
gre_io_t * handle,
gre_io_serialized_data_t * buffer
)
Send a serialized event buffer to a channel. In order to send events, the
handle must have been opened for writing using
GRE_IO_WRONLY.
Parameters:
handle A valid handle created with gre_io_open()
buffer A data buffer containing a serialized event
Returns:
-1 on failure otherwise success.
int gre_io_send_mdata(
gre_io_t * handle,
gre_io_serialized_data_t * md_buffer
)
Send a serialized buffer of mdata (data manager key/value pairs) to the
handle. The handle must have been opened for writing using
GRE_IO_WRONLY.
Parameters:
handle A valid handle created with gre_io_open()
buffer A data buffer containing a serialized data
Returns:
-1 on failure anything else is success
gre_io_serialized_data_t* gre_io_serialize(
gre_io_serialized_data_t * buffer,
const char * event_addr,
const char * event_name,
const char * event_format,
const void * event_data,
int event_nbytes
)
Serialize individual event items (see gre/io_mgr.h) into a
single buffer for transmission using Storyboard IO.
Parameters:
buffer The buffer that will contain the serialized data or NULL if a new buffer should be allocated
event_addr The name of the event target model element (screen,layer, control, render extension),
or NULL to send to the default target (application level)
event_name The name of the event to send, or NULL to send an empty event
event_format The format description of the data (ex. "1s0 string") or NULL if no data is being sent
event_data A pointer do the data to transmit, or NULL if no data is transmitted
event_nbytes The number of data bytes to transmit, or NULL if no data is transmitted
Returns:
A buffer with the serialized data or NULL on error. It may be necessary for the
internal buffer to be re-sized or re-allocated if the new data payload is larger than the
previous one is being serialized.
example:
nbuffer = gre_io_serialize(nbuffer, NULL, "cluster_update",
"2u1 speed 2u1 rpm 2u1 fuel 2u1 battery 2u1 oil 2u1 odometer 2u1 trip",
& event_data, sizeof(event_data));
if(!nbuffer) {
fprintf(stderr, "Can't serialized data to buffer, exiting\n");
break;
}
gre_io_serialized_data_t* gre_io_size_buffer(
gre_io_serialized_data_t * buffer,
int nbytes
)
This function ensures that the specified buffer has enough internal storage capacity for a payload of nbytes size. If the buffer is NULL or the existing capacity is not large enough then a new memory buffer will be assigned to the buffer object.
Data parameters must be sent in order of descending alignment requirements. Example: 4u1 4u1 2u1 1s0 is good, 2u1 4u1 4u1 1s0 is not
Parameters:
buffer The buffer to be sized, or NULL to allocate a new buffer
nbytes The number of bytes this buffer should be able to support
Returns:
A buffer with room for a message nbytes in size or NULL if the space could not be allocated
int gre_io_unserialize(
gre_io_serialized_data_t * buffer,
char ** event_addr,
char ** event_name,
char ** event_format,
void ** event_data
)
Transform a serialized buffer into individual event items (see
gre/io_mgr.h). The pointers returned point back into the
content of the serialized buffer so the buffer can't be de-allocated until
clients are finished referencing the event items returned from this
call.
Data parameters must be sent in order of descending alignment requirements. Example: 4u1 4u1 2u1 1s0 is good, 2u1 4u1 4u1 1s0 is not
Parameters:
buffer The buffer containing the serialized data
event_addr Location to store the event target model element
event_name Location to store the event name
event_format Location to store the event format
event_data Location to store the event data
Returns:
The number of bytes in the event_data structure
void gre_io_zero_buffer(
gre_io_serialized_data_t * buffer
)
This clears the internal byte count of the buffer, but does not de-allocate the buffer's memory.
Use this function to reset a buffer in between multiple calls to
gre_io_serialize
Parameters:
buffer The buffer to have its byte count cleared
void gre_io_get_error_codes( gre_io_t *handle, gre_io_error_t *errorcodes )
This gets the error codes if greio experiences an error.
Parameters:
handle A valid handle created with gre_io_open()
errorcodes A valid gre_io_error_t structure to be filled out
const char * gre_io_get_error_message( gre_io_error_t *errorcodes )
This gets the error message for an error code returned by a call to gre_io_get_error_codes.
Parameters:
errorcodes A valid gre_io_error_t structure containing the errors returned from a call
to gre_io_get_error_codes
Returns:
The error message.