KID User Library Usage

Introduction

In order to handle more than an input data source at a time, the KID user library is handler-based; one handler has to be opened for every input data source in use. Once a valid handler has been returned, the associated data will be delivered until the data source get closed (by the user or by an external event).

For every input data source, the user has to follow the following steps:

obtain a valid handler
retrieve the data using that handler
dispose the handler

See the following paragraphs for a more detailed description of the single steps.

Obtaining a handler

Obtaining a new handler is a very basic operation; only the kid_in_open or the kid_in_try_open function has to be called.

The definition of the kid_in_open and the kid_in_try_open functions are:

int kid_in_open(const char *uri, KID_IN_id *hptr)
int kid_in_try_open(const char *uri, KID_IN_id *hptr)

where

uri is a valid KID URI

The return values are:

if the function returns KID_IN_ERROR_OK, the hptr variable will be assigned a valid handler
else an error occured and a handler is not returned

The difference between the two functions is in the way they treat the error conditions:

kid_in_open returns a valid handler, only and only if the specified KID URI can be opened. If this is not the case, KID_IN_ERROR_NOT_FOUND is returned.
kid_in_try_open is instead less demanding; a valid handler is returned also in case the specified KID URI cannot be opened. In that case, the returned handler will be in the closed state.

An example:

#include <kid_in.h>
...
KID_IN_id handler;
int err;
...
err = kid_in_open("spy:/tmp/B_1_1",&handler);
if (err!=KID_IN_ERROR_OK)
  {
    Print_Error();
    return ERROR;
  }
...

During the life of a handler, a user can decide to look at another input data source but still maintain the same handler (for example, a pointer to the handler could be stored in some data structure the user don't want to modify). To do so, the kid_in_switch can be used.

The definition of the kid_in_switch function is:

int kid_in_switch(KID_IN_id handler, const char *uri)

where

handler is a valid handler
uri is a valid KID URI

If the function returns KID_IN_ERROR_OK, the handler will point to the new KID URI, else an error occured and the handler will be in an undefined state. (although still valid)

Retrieving the data

Once the user have a valid handler, it can start retrieving data from it.

The functions to use are:

kid_in_get_dynamic
kid_in_get_static
kid_in_get_reference

The difference between the three is in the way they return the data found:

kid_in_get_dynamic allocates dynamically a buffer for each request and copies the input data inside it. It is user duty to free that buffer when it is of no use anymore.
kid_in_get_static copies the input data into a user specified buffer. If that buffer is not large enough to hold the input data, an error is returned.
kid_in_get_reference returns a pointer directly to the input data, stored in an internal structure of the KID user library. The data pointed by that pointer are guaranteed to be usefull until the next call to the KID user library on the same handler, but can get corrupted afterwards.

The use of one or another function is context dependant; kid_in_get_reference is surelly the fastest one, but can be error prone and requires carfull code planning; kid_in_get_dynamic is the easiest to use, but is also the least efficient. It is up to the user to decide wheater it is worth the pain to use the more efficient ones instead of simplifying the code.

The definition of kid_in_dynamic, kid_in_get_static and kid_in_get_reference functions are:

int kid_in_get_dynamic(KID_IN_id handler, kevent **ppbuf, int *pbufsize)
int kid_in_get_static(KID_IN_id handler, kevent *pbuf, int *pbufsize1)
int kid_in_get_reference(KID_IN_id handler, kevent **ppbuf, int *pbufsize)

where

handler is a valid handler
pbuf is a pointer to a pre-allocated buffer of size *pbufsize1

If the function returns:

KID_IN_ERROR_OK, the ppbuf variable will point to valid data, that must be disposed by the caller in case of kid_in_dynamic, or the data was copied into the user specified buffer in case of kid_in_get_static. Furthermore, pbufsize(or pbufsize1) will be assigned the size of the returned data.
KID_IN_ERROR_SIZE (only for kid_in_get_static), the input data was to large to fit into the user specified buffer. pbufsize1 contains the size of the data to be returned. No data is consumed.
KID_IN_ERROR_EMPTY, if no data available at this time
KID_IN_ERROR_CLOSED, if there is no more data to be read
KID_IN_ERROR_AT_START, if this is the first time a get function is called on an input source and the signalling is enabled. No data is consumed.
KID_IN_ERROR_AT_END, if this is the first time a get function is called after the last event beeing read from an input source and the signalling is enabled. No data is obviously consumed.
else an error occured

An example

#include <kdata.h>
#include <kid_in.h>

int print_one(KID_IN_id handler)
{
  kevent *event;
  int evsize;
  int err;

  while ((err = kid_in_get_reference(handler,&event,&evsize))==KID_IN_ERROR_EMPTY)
   {
     sleep(1);
   }

  /* Do not consider _AT_START and _AT_END in this example */
  if (err==KID_IN_ERROR_OK)
    {
      print_event(event);
      return OK;
    }
  else
    return ERROR;
}

Disposal of a handler

Once an input data source is of no use anymore for the user, he (or she) should dispose the handler, using the kid_in_close function, to free the resources used by it.

The definition of the kid_in_close function is:

void kid_in_close(KID_IN_id handler)

where

handler is a valid handler

#include <kid_in.h>
...
KID_IN_id handler;
int err;
...
err = kid_in_open("spy:/tmp/B_1_1",&handler);
if (err==KID_IN_ERROR_OK)
  {
    Do_Whatever_Needed(handler);
    kid_in_close(handler);
  }
...

Send comments to: Igor Sfiligoi

Last modified: Fri Sep 8 10:40:07 MET DST