Appendix B. Storyboard IO API

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.

void gre_io_close(
    gre_io_t *  handle  
)
            

Close an io connection.   Any pending clients will return with an error on their pending actions. This call should be serialized with other clients that are referencing the same gre_io_t handle to avoid race conditions. A common technique for closing handles where a receiving thread may be blocked on the handle is to generate a termination event and have the receiving thread perform the close and channel cleanup.

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.

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.

gre_io_t* gre_io_open(
    const char *    io_name,  
    int             flag,  
    ...  
)  
            

Open a Storyboard IO communication channel using a named connection.

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.

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.

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.

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.

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

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

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

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.

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.