Appendix B. Storyboard IO API

Table of Contents

Storyboard IO API
gre_io_add_mdata
gre_io_close
gre_io_free_buffer
gre_io_grow_buffer
gre_io_open
gre_io_receive
gre_io_send
gre_io_send_mdata
gre_io_serialize
gre_io_size_buffer
gre_io_unserialize
gre_io_zero_buffer
gre_io_get_error_codes
gre_io_get_error_message

Storyboard IO API

The details the functions available in the Storyboard IO library, libgreio.a, are also documented in the Storyboard IO header file gre/greio.h>.

gre_io_add_mdata

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
        

gre_io_close

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.


Parameters:

        handle  A valid handle created with gre_io_open()
            

gre_io_free_buffer

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
            

gre_io_grow_buffer

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.

Note

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_open

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 opened.  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.
        

gre_io_receive

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.

gre_io_send

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.
        

gre_io_send_mdata

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_serialize

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_size_buffer

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
        

gre_io_unserialize

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

gre_io_zero_buffer

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
        

gre_io_get_error_codes

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

gre_io_get_error_message

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.