SDK Guide › Exits API › authxapi_GetObjectListValue Function

authxapi_GetObjectListValue Function

Valid on UNIX

The authxapi_GetObjectListValue function retrieves a list of values assigned to a property of an object stored in the database. Properties that have single values cannot be retrieved with this function. You retrieve single value properties with authxapi_GetObjectProperty.

If the function succeeds, it returns 0. If it fails, it sets the global variable errno and returns one of the following error codes:

int authxapi_GetObjectListValue (const char   *szClass,
                                 const char   *szObj,
                                 SEOSDB_ODF   *p_odf,
                                 const char   *szProp,
                                 SEOSDB_PDF   *p_pdf,
                                 void         ***val,
                                 unsigned int *psize,
                                 unsigned int *count);

szClass

The name of the class to which the resource belongs.

szObj

The name of the object whose property value you want to retrieve.

p_odf

A pointer to an object descriptor fetched by this function or provided by the caller from a previous call to an Exits API get function.

szProp

The name of the property whose values you want to retrieve.

p_pdf

A pointer to a property descriptor fetched by this function or provided by the caller from a previous call to an Exits API get function.

val

A pointer to a variable that is assigned the memory address of an array of pointers. The array of pointers point to the data values being retrieved. The authxapi_GetObjectListValue function allocates the memory used here.

psize

Size in bytes of the region in memory allocated to each element in the value list.

count

The number of elements in the value list. May be 0 if no elements are found.

Notes:

• If the szObj parameter is NULL, the function assumes p_odf is pointing to a valid object descriptor obtained from a previous call to one of the get functions provided by the Exits API. This speeds up processing when you are dealing with a series of objects that share the same object descriptor, since you do not spend time repeatedly fetching the same object descriptor.

  Although it is faster to use an object descriptor than an object name, it is not safe to store the object descriptors in global variables and to use them in subsequent calls to this function. This is because updates to the database may delete these objects.

• If the szProp parameter is NULL, the function assumes p_pdf is pointing to a valid property descriptor obtained from a previous call to one of the get functions provided by the Exits API. This speeds up processing when you are dealing with a series of objects that share the same property descriptor, since you do not spend time repeatedly fetching the same property descriptor.

  It is safe to store property descriptors in global variables and use them in subsequent calls to this function, as property definitions are not subject to change while the seosd daemon is active.

The authxapi_GetObjectListValue function allocates a vector of void pointers, each pointing to an allocated buffer that holds a single element in the list of values. You must declare a list variable of any type as a pointer to a pointer, such as int **. A pointer to this list variable is then passed into authxapi_GetObjectListValue, typecast as a (void ***). For example:

{
    int **list;
    unsigned int psize, count;
    int rc;
    ...
rc = authxapi_GetObjectListValue(szClass,
         szObj, &odf, szProp, &pdf,
         (void ***)&list, &psize, &count);
...
}

When authxapi_GetObjectListValue returns, the list variable points to a newly allocated area of memory containing the pointers, stored sequentially from 0 to count, pointing to each list item. Each list item is stored in yet another newly allocated memory area. Be sure to use authxapi_FreeListValues to free all the memory allocated by authxapi_GetObjectListValue.

For example, when you have a list of N data elements, your memory is allocated as follows:

Example: Retrieve List of Values of a Property Resource

The following Exits API function retrieves a list of values from a list‑type property of a resource from the database, and then loops through the list of values. The code that actually uses the information retrieved is not shown.

#include stdio.h
#include authxapi.h
#include seostype.h

int MyExitFunction(void *exit_data, SEOS_EXITRES *result)
{
    SEOS_EXITGENR *genr_data;
    SEOSDB_ODF odf;
    SEOSDB_PDF pdf;
    SEOS_ACL **access_list, *acl_element;
    int rc;
    unsigned int psize, count, counter;
    genr_data = (SEOS_EXITGENR *)exit_data;
    /* Ignore any class that is not of interest */
    if (strcmp(genr_data‑>szClass, “MyResClass”))
        return 0;
    /* Fetch the information for the ACL property of the */
    /* resource being accessed. */
    rc = authxapi_GetObjectListValue(“MyResClass”, genr_data‑>szRes
           &odf, “ACL”, &pdf, (void ***)access_list, &psize, &count);
    if (rc == 0)
    {
         /* We have the ACL now. Lets just see a demonstration */
         /* of looping through the list. */
         for (counter = 0; counter < count; counter++)
         {
               acl_element = access_list[counter];
               /*
                * > > > User Code Here < < <
                */
         }
         authxapi_FreeListValues((void ***) &access_list, &count);
    }
    return 0;
}

More information:

authxapi_FreeListValues

authxapi_GetObjectProperty Function