Archive the libary api

The Library API

This document describes the API available to the library developer. There are operations to verify library version information, manage instance data, and execute IPC operations.

The Versioning System

This section describes the data structure and API used to verify a user specified version value according to the SA Forum.

The Version Database

A version database is a list of versions supported by the library. It is a static structure declared in the C library as follows:

static SaVersionT supported_versions[] = {
        {'B', 0x01, 0x01}
};
static struct saVersionDatabase my_version_database = {
        sizeof (supported_versions) / sizeof (SaVersionT),
        supported_versions
};

The Version Verfication API

The version database is verified with the code segment:

error = saVersionVerify (&my_version_database, version)
if (error != SA_AIS_OK) {
        goto error_exit;
}

The Handle System

The handle system is a mapping of values to pointers in memory used to store data. The handle database system automatically allocates the required storage based upon the size requested during a handle creation operation. The handle then has a reference count which is used to keep track of garbage collection of the handle's storage area. The advantage of this referencing system is that invalid references can be detected.

The Handle Database

A handle database is described by the structure in a library:

static void my_destructor (void *instance)
{
/*
 * Do some destruction
 */
}

static struct saHandleDatabase my_db = {
        .handleCount = 0,
        .handles = NULL,
        .mutex = PTHREAD_MUTEX_INITIALIZER,
        .handleInstanceDestructor = my_destructor
};

The my_destructor function can be NULL or execute cleanup operations. It will be called when the reference count of the instance drops to zero, meaning there are no more references. After my_destructor is called, the data associated with the reference is freed so it must not be used later by the library.

Creating a Handle Instance

The following code segment will create a handle instance

uint64_t handle;

error = saHandleCreate (&my_db, sizeof (struct lib_instance), &handle);
if (error != SA_AIS_OK) {
        goto error_exit
}

After calling this code segment, the handle will be created with the size of the lib_instance data structure. The handle will be returned to the user in the handle 64 bit value.

The handle is a combination of 2 32 bit values. The LSB 32 bits are an index into an array, the MSB 32 bits are a 32 bit random number used to verify the handle is the intended handle from the user.

The appropriate error will be returned according to SA Forum specifications if the handle is invalid, or a memory allocation failure occurs, otherwise SA_AIS_OK will be returned.