eimListRegistries()--List EIM Registries


  Syntax
 #include <eim.h>

 int eimListRegistries(EimHandle            * eim,
                       char                 * registryName,
                       char                 * registryType,
                       enum EimRegistryKind   registryKind,
                       unsigned int           lengthOfListData,
                       EimList              * listData,
                       EimRC                * eimrc)
 
  Service Program Name: QSYS/QSYEIM  

  Default Public Authority: *USE

  Threadsafe: Yes

The eimListRegistries() function lists the user registries participating in the EIM domain. The following parameters can be used to filter the results returned: registryType, registryName and registryKind.


Authorities and Locks

EIM Data
Access to EIM data is controlled by EIM access groups. LDAP administrators also have access to EIM data. The access groups whose members have authority to the EIM data for this API follow:
  • EIM Administrator
  • EIM Registries Administrator
  • EIM Identifiers Administrator
  • EIM Mapping Lookup
  • EIM authority to an individual registry

The list returned contains only the information that the user has authority to access.


Parameters

eim  (Input)
The EIM handle returned by a previous call to eimCreateHandle(). A valid connection is required for this function.

registryName  (Input)
The name of the EIM registry to list. The name may contain the wild card char (*). This is used as a filter to determine which registries to return. This parameter may be NULL in which case no filtering would be done by name.

registryType  (Input)
A string form of an OID that represents the registry type and a user name normalization method. The normalization method is necessary because some registries are case-independent and others are case-dependent. EIM uses this information to make sure the appropriate search occurs. See eim.h for a list of defined types. This parameter may be NULL in which case no filtering would be done by type.

registryKind  (Input)
The kind of registry to list. This parameter is passed by value. Valid values are:


lengthOfListData  (Input)
The number of bytes provided by the caller for the listData parameter. The minimum size required is 20 bytes. This parameter is passed by value.

listData  (Output)
A pointer to the data to be returned.

The EimList structure contains information about the returned data. The API will return as much data as space has been provided. The data returned is a linked list of EimRegistry structures. firstEntry is used to get to the first EimRegistry structure in the linked list.

EimList structure:

   typedef struct EimList
   {
       unsigned int bytesReturned;     /* Number of bytes actually returned
                                        by the API                       */
       unsigned int bytesAvailable;    /* Number of bytes of available data
                                        that could have been returned by
                                        the API                          */
       unsigned int entriesReturned;   /* Number of entries actually
                                        returned by the API              */
       unsigned int entriesAvailable;  /* Number of entries available to be
                                        returned by the API              */
       unsigned int firstEntry;        /* Displacement to the first linked
                                        list entry. This byte offset is
                                        relative to the start of the
                                        EimList structure.               */
   } EimList;

EimRegistry structure:

   typedef struct EimRegistry
   {
       unsigned int nextEntry;         /* Displacement to next entry.  This
                                        byte offset is relative to the
                                        start of this structure          */
       enum EimRegistryKind  kind;     /* Kind of registry               */
       EimListData name;               /* Registry name                  */
       EimListData type;               /* Registry type                  */
       EimListData description;        /* Description                    */
       EimListData entryUUID;          /* Entry UUID                     */
       EimListData URI;                /* URI                            */
       EimListData systemRegistryName; /* System registry name           */
       EimSubList  registryAlias;      /* EimRegistryAlias sublist       */
       enum EimStatus  mappingLookup;  /* Mapping lookup attribute       */
       enum EimStatus  policyAssociations; /* Policy associations
					       attribute                 */
       EimSubList  registryMembers;    /* EimRegistryName sublist        */
       EimSubList  registryGroups;     /* EimRegistryName sublist        */
   } EimRegistry;

Registries may have a number of aliases defined. In the EimRegistry structure, the registryAlias EimSubList gives addressability to the first EimRegistryAlias structure.

EimRegistryAlias structure:

   typedef struct EimRegistryAlias
   {
       unsigned int nextEntry;         /* Displacement to next entry.  This
                                        byte offset is relative to the
                                        start of this structure          */
       EimListData type;               /* Alias type                     */
       EimListData value;              /* Alias value                    */
   } EimRegistryAlias;

Group registries may have a number of members defined. In the EimRegistry structure, the registryMembers EimSubList gives addressability to the first EimRegistryName structure. Registry members will only exist for registries that have a type of group registry.

Registries may have a number of group registries of which they are a member. In the EimRegistry structure, the registryGroups EimSubList gives addressability to the first EimRegistryName structure. Registry groups will only exist for registries that are not group registries.

EimRegistryName structure:

   typedef struct EimRegistryName
   {
       unsigned int nextEntry;         /* Displacement to next entry.  This
                                        byte offset is relative to the
                                        start of this structure          */
       EimListData name;               /* Name.                          */
   } EimRegistryName;

EimSubList structure:

   typedef struct EimSubList
   {
       unsigned int listNum;           /* Number of entries in the list  */
       unsigned int disp;              /* Displacement to sublist. This
                                        byte offset is relative to the
                                        start of the parent structure;
                                        that is, the structure containing 
                                        this structure.                  */
   } EimSubList;

EimListData structure:

   typedef struct EimListData
   {
       unsigned int length;            /* Length of data                 */
       unsigned int disp;              /* Displacement to data.  This byte
                                        offset is relative to the start of
                                        the parent structure; that is, the
                                        structure containing this
                                        structure.                       */
   } EimListData;
eimrc  (Input/Output)
The structure in which to return error code information. If the return value is not 0, eimrc is set with additional information. This parameter may be NULL. For the format of the structure, see EimRC--EIM Return Code Parameter.

Return Value

The return value from the API. Following each return value is the list of possible values for the messageCatalogMessageID field in the eimrc parameter for that value.

0
Request was successful.

EACCES
Access denied. Not enough permissions to access data.


EBADDATA
eimrc is not valid.

EBUSY
Unable to allocate internal system object.


ECONVERT
Data conversion error.


EINVAL
Input parameter was not valid.


ENOMEM
Unable to allocate required space.


ENOTCONN
LDAP connection has not been made.


EUNKNOWN
Unexpected exception.


Related Information


Example

The following example lists all registries found.

Note: By using the code examples, you agree to the terms of the Code license and disclaimer information.

#include <eim.h>
#include <stddef.h>
#include <stdio.h>
#include <stdlib.h>


void printRegistryKind(int kind);
void printListResults(EimList * list);
void printListData(char * fieldName,
                   void * entry,
                   int offset);
void printAliasSubList(void * entry,
                       int offset);
void printNameSubList(void * entry,
                      int offset);


int main (int argc, char *argv[])
{
    int           rc;
    char          eimerr[100];
    EimRC       * err;
    EimHandle   * handle;

    char          listData[1000];
    EimList     * list = (EimList * ) listData;

    /* Get eim handle from input arg.           */
    /* This handle is already connected to EIM. */
    handle = (EimHandle *)argv[1];

    /* Set up error structure.                  */
    memset(eimerr,0x00,100);
    err = (EimRC *)eimerr;
    err->memoryProvidedByCaller = 100;

    /* Get all registries                       */
    if (0 != (rc = eimListRegistries(handle,
                                     NULL,
                                     NULL,
                                     EIM_ALL_REGISTRIES,
                                     1000,
                                     list,
                                     err)))
    {
        printf("List registries error = %d", rc);
        return -1;
    }

    /* Print the results                        */
    printListResults(list);
    
    return 0;
      
}
            
void printListResults(EimList * list)
{
    int i;
    EimRegistry * entry;

    printf("___________\n");
    printf("   bytesReturned    = %d\n", list->bytesReturned);
    printf("   bytesAvailable   = %d\n", list->bytesAvailable);
    printf("   entriesReturned  = %d\n", list->entriesReturned);
    printf("   entriesAvailable = %d\n", list->entriesAvailable);
    printf("\n");

    entry = (EimRegistry *)((char *)list + list->firstEntry);
    for (i = 0; i < list->entriesReturned; i++)
    {
        printf("\n");
        printf("===============\n");
        printf("Entry %d.\n", i);
        
        /* Registry kind */
        printRegistryKind(entry->kind);
        
        /* Print out results */
        printListData("Registry Name",
                      entry,
                      offsetof(EimRegistry, name));
        printListData("Registry Type",
                      entry,
                      offsetof(EimRegistry, type));
        printListData("description",
                      entry,
                      offsetof(EimRegistry, description));
        printListData("entryUUID",
                      entry,
                      offsetof(EimRegistry, entryUUID));
        printListData("URI",
                      entry,
                      offsetof(EimRegistry, URI));
        printListData("system registry name",
                      entry,
                      offsetof(EimRegistry, systemRegistryName));
        printAliasSubList(entry,
                          offsetof(EimRegistry, registryAlias));
        printf("List of member registries:\n");
        printNameSubList(entry,
                         offsetof(EimRegistry, registryMembers));
        printf("List of group registries:\n");
        printNameSubList(entry,
                         offsetof(EimRegistry, registryGroups));

        /* advance to next entry */
        entry = (EimRegistry *)((char *)entry + entry->nextEntry);

    }
    printf("\n");


}

void printRegistryKind(int kind)
{
    switch(kind)
    {
        case EIM_SYSTEM_REGISTRY:
            printf("    System Registry.\n");
            break;
        case EIM_APPLICATION_REGISTRY:
            printf("Application Registry.\n");
            break;
        case EIM_GROUP_REGISTRY:
            printf("Group Registry.\n");
            break;
        default:
            printf("ERROR - unknown registry kind.\n");
            break;
    }
}

void printListData(char * fieldName,
                   void * entry,
                   int offset)
{
    EimListData * listData;
    char * data;
    int dataLength;

    printf("     %s = ",fieldName);
    /* Address the EimListData object */
    listData = (EimListData *)((char *)entry + offset);
    
    /* Print out results */
    data = (char *)entry + listData->disp;
    dataLength = listData->length;
    
    if (dataLength > 0)
        printf("%.*s\n",dataLength, data);
    else
        printf("Not found.\n");
        
}
                   

void printAliasSubList(void * entry,
                       int offset)
{
    int i;
    EimSubList * subList;
    EimRegistryAlias * subentry;

    /* Address the EimSubList object */
    subList = (EimSubList *)((char *)entry + offset);

    if (subList->listNum > 0)
    {

        subentry = (EimRegistryAlias *)((char *)entry +
                                        subList->disp);
        for (i = 0; i < subList->listNum; i++)
        {

            /* Print out results */
            printListData("Registry alias type",
                          subentry,
                          offsetof(EimRegistryAlias, type));
            printListData("Registry alias value",
                          subentry,
                          offsetof(EimRegistryAlias, value));

            /* advance to next entry */
            subentry = (EimRegistryAlias *)((char *)subentry +
                                            subentry->nextEntry);
        }
    }
        
}
                   

void printNameSubList(void * entry,
                      int offset)
{
    int i;
    EimSubList * subList;
    EimRegistryName * subentry;

    /* Address the EimSubList object */
    subList = (EimSubList *)((char *)entry + offset);

    if (subList->listNum > 0)
    {

        subentry = (EimRegistryName *)((char *)entry +
                                       subList->disp);
        for (i = 0; i < subList->listNum; i++)
        {

            /* Print out results */
            printListData("Registry name",
                          subentry,
                          offsetof(EimRegistryName, name));

            /* advance to next entry */
            subentry = (EimRegistryName *)((char *)subentry +
                                           subentry->nextEntry);
        }
    }
        
}


API introduced: V5R2

[ Back to top | Security APIs | APIs by category ]