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.


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

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. 
        

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, or NULL to send to the default target
        event_name      The name of the event to send, or NULL to send an empty event  
        event_format    The format description of the data 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.
        

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.


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.


Parameters:

        buffer          The buffer containing the serialized data
        event_addr      Location to store the event target 
        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