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. Valid values are:
| EIM_REGISTRYUSER_DESCRIPTION (0) |
Change the registry description. Valid
changeType is EIM_CHG (0). |
| EIM_REGISTRYUSER_ADDL_INFO (1) |
Add or remove additional information for this
user. Valid changeType is EIM_ADD (1) and EIM_RMV (2). |
| EIM_REGUSER_PASSWORD_CRED (2) |
Change the password credential
associated with the registry user.
Valid changeType is EIM_CHG (0) and EIM_RMV (2).
EIM version 3 must be supported by the local EIM APIs to specify this attribute
(see eimGetVersion()--Get EIM Version).
|
| EIM_REGUSER_PWD_CRED_STATUS (3) |
Change the status of the password credential
associated with the registry user.
Valid changeType is EIM_ENABLE (3) and EIM_DISABLE (4). This
attribute has no affect if the EIM_REGUSER_PASSWORD_CRED (2) attribute
does not exist for the registry user.
EIM version 3 must be supported by the local EIM APIs to specify this attribute
(see eimGetVersion()--Get EIM Version).
|
| EIM_REGUSER_IDCTX_CRED (4) |
Change the identity context credential
associated with the registry user.
Valid changeType is EIM_CHG (0) and EIM_RMV (2).
EIM version 3 must be supported by the local EIM APIs to specify this attribute
(see eimGetVersion()--Get EIM Version).
|
- 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.
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.
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.
| EIMERR_ACCESS (1) |
Insufficient access to EIM data. |
- EBADDATA
- eimrc is not valid.
- EBADNAME
- Registry or registry user not found or insufficient access to EIM data.
| EIMERR_NOREG (28) |
EIM Registry not found or insufficient access to
EIM data. |
| EIMERR_NOREGUSER (29) |
Registry user not found or insufficient access to
EIM data. |
- EBUSY
- Unable to allocate internal system object.
| EIMERR_NOLOCK (26) |
Unable to allocate internal system object. |
- ECONVERT
- Data conversion error.
| EIMERR_DATA_CONVERSION (13) |
Error occurred when converting data between code
pages. |
- EINVAL
- Input parameter was not valid.
| EIMERR_ATTR_INVAL (5) |
Attribute name is not valid. |
| EIMERR_CHGTYPE_INVAL (9) |
This change type is not valid with the requested
attribute. Please check the API documentation. |
| EIMERR_HANDLE_INVAL (17) |
EimHandle is not valid. |
| EIMERR_PARM_REQ (34) |
Missing required parameter. Please check API
documentation. |
| EIMERR_PTR_INVAL (35) |
Pointer parameter is not valid. |
| EIMERR_FUNCTION_NOT_SUPPORTED (70) |
The specified function is not supported
by the EIM version. |
- ENOMEM
- Unable to allocate required space.
| EIMERR_NOMEM (27) |
No memory available. Unable to allocate required
space. |
- ENOTCONN
- LDAP connection has not been made.
| EIMERR_NOT_CONN (31) |
Not connected to LDAP. Use eimConnect() API and
try the request again. |
- EROFS
- LDAP connection is for read only. Need to connect to master.
| EIMERR_READ_ONLY (36) |
LDAP connection is for read only. Use
eimConnectToMaster() to get a write connection. |
- EUNKNOWN
- Unexpected exception.
| EIMERR_LDAP_ERR (23) |
Unexpected LDAP error. %s |
| EIMERR_UNEXP_OBJ_VIOLATION (56) |
Unexpected object violation. |
| EIMERR_UNKNOWN (44) |
Unknown error or unknown system state. |
Related Information
Example
See Code disclaimer information
for information pertaining to code examples.
The following example changes the description and adds additional
information for the target registry user.
#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