Subscriber Profile Module (PROFILE)

#include ``profile.h''

ReturnCode
PROFILE_open(char * pProfileName,
             void ** phProfile);

void
PROFILE_close(void * hProfile);

ReturnCode
PROFILE_addAttribute(void * hProfile,
                     char * pAttributeName,
                     OS_Uint32 type,
                     OS_Boolean (* pfEqual)(char * pValue1,
                                            char * pValue2,
                                            OS_Uint32 type));

ReturnCode
PROFILE_searchByAttribute(void * hProfile,
                          char * pAttributeName,
                          char * pSearchValue,
                          void ** phSearch);


ReturnCode
PROFILE_searchByType(void * hProfile,
                     OS_Uint32 type,
                     char * pSearchValue,
                     void ** phSearch);


ReturnCode
PROFILE_getAttributeValue(void * hProfile,
                          void * hSearch,
                          char * pAttributeName,
                          char ** ppValue);

The PROFILE module constructs searchable Profiles from Profile libraries. As shown in the following diagram, a Profile is a set of Attributes and Attribute Values. The same set of Attributes may apply to different Entities. Each Entity may use different Values for the same set of Attributes.

entity_i
   attribute_1 value_a
   attribute_2 value_b
        .
        .
        .

entity_j
   attribute_1 value_x
   attribute_2 value_y
        .
        .
        .

Each Attribute is assigned a Type by the user. When searching Profiles, searches may be issued based on finding a particular Attribute with a particular Value, or on finding a particular Value within any Attribute which is of a specified Type.

Open and Close a Profile Library

ReturnCode
PROFILE_open(char * pProfileName,
             void ** phProfile);
Returns:
   Success
   ResourceError
   <depending upon the implementation, other non-Success Values>

void
PROFILE_close(void * hProfile);

PROFILE_open opens the Profile library hProfile. In some portations, this may be a file name. phProfile is a pointer to a location in which a handle for this Profile Library will be placed.

PROFILE_close releases resources allocated on behalf of the user, for accessing a Profile library. hProfile is a handle to a Profile Library, previously provided by PROFILE_open.

Add an Attribute to a Profile

ReturnCode
PROFILE_addAttribute(void * hProfile,
                     char * pAttributeName,
                     OS_Uint32 type,
                     OS_Boolean (* pfEqual)(char * pValue1,
                                            char * pValue2,
                                            OS_Uint32 type));

Returns:
    Success
    Fail

PROFILE_addAttribute adds an Attribute contained in a Profile library to a searchable, local list of Attributes. It is not necessary to add all Attributes in the library to this list. Only those Attributes of concern to the application making this call need be added. These Attributes are the ones that will be searched by PROFILE_searchByAttribute and PROFILE_searchByType.

There is one exception to the above rule. The "key" Attribute must be added, and must be the very first Attribute added. The key field is, in this INI-file-based implementation, the INI Section name (in square brackets). In a real database implementation, there would be a primary key, possibly some secondary keys (irrelavent to a profile), and a bunch of record attributes.

hProfile

A handle to a Profile library, previously provided by PROFILE_open.

pAttributeName

The name of an Attribute within the Profile library.

type

A caller-defined value defining the Type of the Attribute. If multiple Attributes have the same Type, then PROFILE_searchByType will search all of those Attributes for a particular Value.

Note: The caller-defined portion of this Value is the low-order 31 bits. The high-order bit is reserved for OR-ing with PROFILE_MULTIVALUE. See the following section.

pfEqual

A pointer to a function which is called, during searches, to compare the specified search Value against the Attribute Value in the profile. This function need not be a simple string compare. For example, in comparing an email address, we want to do case-insensitive string compares. In other cases, the user of the profile package might want to strip out some of the information in one or the other of the strings prior to doing the comparison.

PROFILE_MULTIVALUE

If an Attribute Type has the PROFILE_MULTIVALUE bit set, the Attribute name will have a space with sequential numbers appended to it in order to create a list of values for that attribute. If, for example, for the attribute ATTR_ID, PROFILE_addAttribute() is called as follows:

          rc = PROFILE_addAttribute(hProfile,
                                    "Id",
                                    ATTR_ID | PROFILE_MULTIVALUE,
                                    compareFunction);

when PROFILE_searchByAttribute() is called (see below), multiple attributes will be searched for. The attribute names will be:

          Id 1
          Id 2
            .
            .
            .

The search will complete when a match is found, or no more attributes in the set of Values are found.

Search a Profile

ReturnCode
PROFILE_searchByAttribute(void * hProfile,
                          char * pAttributeName,
                          char * pSearchValue,
                          void ** phSearch);

ReturnCode
PROFILE_searchByType(void * hProfile,
                     OS_Uint32 type,
                     char * pSearchValue,
                     void ** phSearch);

Returns:
    Success
    Fail

PROFILE_searchByAttribute searches the specified Profile for an Entity that contains a particular Attribute matching a specified Value.

PROFILE_searchByType searches the specified Profile for an Entity that contains any Attribute with the specified Type, matching a specified Value.

In both cases, the search is sequential, so if there is more than one possible search outcome only the first one is returned.

hProfile

Handle to a Profile library, previously provided by PROFILE_open.

pAttributeName

Name of the Attribute which is to be compared to the search Attribute Value.

type

Value specifying the Attribute types to be scanned for the specified search Value.

pSearchValue

Attribute Value to be searched for.

phSearch

Pointer to a location in which a search handle is placed upon successful completion of this function. This search handle points to an Entity and may be passed to PROFILE_getAttributeValue() to obtain other Attributes from the Entity found in this search.

Get an Attribute Value

ReturnCode
PROFILE_getAttributeValue(void * hProfile,
                          void * hSearch,
                          char * pAttributeName,
                          char ** ppValue);

Returns:
    Success
    Fail

PROFILE_getAttributeValue obtains Attribute Values from the Entity determined by PROFILE_searchByAttribute or PROFILE_searchByType.

Profile

Handle to a Profile library, previously provided by PROFILE_open.

hSearch

Search handle, previously provided by PROFILE_searchByAttribute or PROFILE_searchByType.

pAttributeName

Name of the Attribute whose Value is desired.

ppValue

Pointer to the location in which a pointer to the character string representation of the requested Value is placed.