eimChangeRegistryUser() --Change EIM Registry User


  Syntax 
 #include <eim.h>

 int eimChangeRegistryUser(EimHandle                * eim,
                           char                     * registryName,
                           char                     * registryUserName,
                           enum EimRegistryUserAttr   attrName,
                           char                     * attrValue,
                           enum EimChangeType         changeType,
         EimRC                    * eimrc)
  Service Program Name: QSYS/QSYEIM  

  Default Public Authority: *USE

  Threadsafe: Yes

The eimChangeRegistryUser() function changes the attributes of a registry user entry. A registry user is implicitly added to a registry when a target association for an identity in that registry is added. However, the attribute fields are not set at that time.

There are situations when more than one user can be returned on a mapping lookup operation. Applications can choose to use information in the additional information field to distinguish between which returned target identity to use. For example, assume Joe has two identities in a specific registry X, joeuser and joeadmin. An application provider can tell the administrator to add additional information, for example, "appname-admin," to the appropriate registry user -- in this case, joeadmin. The application can provide this additional information on the lookup APIs, eimGetTargetFromSource() and eimGetTargetFromIdentifier().


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 authority to an individual registry

Must be a member of EIM Administrator or have EIM authority to an individual registry to change the EIM_REGUSER_PASSWORD_CRED (2), EIM_REGUSER_PWD_CRED_STATUS (3), and EIM_REGUSER_IDCTX_CRED (4) attributes.

Note that if the registry existed prior to EIM Version 3, the first time credential information is added to a user in that registry, it must be added by a member of EIM Administrator. After the first credential information is added, then EIM authority to an individual registry is sufficient to change or remove credential information for any user in the registry.


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 registry that contains this user.

registryUserName  (Input)
The name of the user in this registry to change.

attrName
The attribute to be updated. This parameter is passed by value. Valid values are:


attrValue  (Input)
The new value for the attribute.

If the attribute being changed is EIM_REGUSER_PASSWORD_CRED or EIM_REGUSER_IDCTX_CRED and the changeType is EIM_RMV (2), or the attribute being changed is EIM_REGUSER_PWD_CRED_STATUS, this value must be NULL.

If the attribute being changed is EIM_REGUSER_IDCTX_CRED and the changeType is EIM_CHG (0), then this value must be a pointer to an EimBinaryData structure. The layout of the EimBinaryData structure follows:

   typedef struct EimBinaryData
   {
       int              length;
       unsigned char  * data;
   } EimBinaryData;
changeType  (Input)
The type of change to make. This could be add, remove, change, enable, or disable. This parameter is passed by value.  attrName parameter indicates which type is allowed for each attribute.

eimrc  (Input/Output)
The structure in which to return error code information. If the return value is not 0, eimrc will be 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.

EBADNAME
Registry or registry user not found or insufficient access to EIM data.


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.


EROFS
LDAP connection is for read only. Need to connect to master.


EUNKNOWN
Unexpected exception.


Related Information


Example

The following example changes the description and adds additional information for the target registry user.

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

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

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

    /* 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;

    /* Change the registry user's description       */
    if (0 != (rc = eimChangeRegistryUser(handle,
                                         "MyRegistry",
                                         "mjjones",
                                         EIM_REGISTRYUSER_DESCRIPTION,
                                         "cool customer",
                                         EIM_CHG,
                                         err)))
    {
        printf("Change registry user error = %d", rc);
        return -1;
    }
    
    /* Add additional information to the registry user*/
    if (0 != (rc = eimChangeRegistryUser(handle,
                                         "MyRegistry",
                                         "mjjones",
                                         EIM_REGISTRYUSER_ADDL_INFO,
                                         "security officer",
                                         EIM_ADD,
                                         err)))
    {
        printf("Change registry user error = %d", rc);
        return -1;
    }
    
    /* Add additional information to the registry user*/
    if (0 != (rc = eimChangeRegistryUser(handle,
                                         "MyRegistry",
                                         "mjjones",
                                         EIM_REGISTRYUSER_ADDL_INFO,
                                         "administrator",
                                         EIM_ADD,
                                         err)))
    {
        printf("Change registry user error = %d", rc);
        return -1;
    }
              
    return 0;
}

API introduced: V5R2

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