eimQueryAccess

Purpose

Queries to check if the user has the specified access.

Format

#include <eim.h>

int eimQueryAccess(EimHandle          * eim,
                   EimAccessUser      * accessUser,
                   enum EimAccessType   accessType,
                   char               * registryName,
                   unsigned int       * accessIndicator,
                   EimRC              * eimrc)

Parameters

eim
(Input) The EIM handle that a previous call to eimCreateHandle returns. A valid connection is required.
accessUser
(Input) A structure that contains the user information for which to query access.
EIM_ACCESS_DN
Indicates a distinguished name defined in an LDAP directory that you can use to bind to the EIM domain.
EIM_ACCESS_LOCAL_USER
(z/OS does not support this. Use EIM_ACCESS_DN instead.) It indicates a local user name on the system where the API runs. The local user name is converted to the appropriate access ID for this system.
EIM_ACCESS_KERBEROS
Indicates a Kerberos identity. The Kerberos identity is converted to the appropriate access ID. For example, EIM converts petejones@therealm to ibm-kn=petejones@threalm.
The EimAccessUser structure layout follows:
   enum EimAccessUserType {
       EIM_ACCESS_DN,
       EIM_ACCESS_KERBEROS,
       EIM_ACCESS_LOCAL_USER
   };

 
   typedef struct EimAccessUser
   {
       union {
           char * DN;
           char * kerberosPrincipal;
           char * localUser;
       } user;
       enum EimAccessUserType userType;
   } EimAccessUser;
accessType
(Input) The type of access to check. Valid values are:
EIM_ACCESS_ADMIN (0)
Administrative authority to the entire EIM domain.
EIM_ACCESS_REG_ADMIN (1)
Administrative authority to all registries in the EIM domain.
EIM_ACCESS_REGISTRY (2)
Administrative authority to the registry specified in the registryName parameter.
EIM_ACCESS_IDENTIFIER_ADMIN (3)
Administrative authority to all of the identifiers in the EIM domain.
EIM_ACCESS_MAPPING_LOOKUP (4)
Authority to perform mapping lookup operations.
registryName
(Input) The name of the EIM registry for which to check the access. Registry names are case-independent (not case-sensitive). This parameter is used only if accessType is EIM_ACCESS_REGISTRY. If accessType is anything other than EIM_ACCESS_REGISTRY, this parameter must be NULL.
The following special characters are not allowed in registry names: 
, = + < > # ; \ *
accessIndicator
(Output) Indicates whether access is found.
EIM_ACCESS_NO (0)
Access not found.
EIM_ACCESS_YES (1)
Access found.
eimrc
(Input/Output) The structure in which to return error code information. If the return value is not 0, EIM sets eimrc with additional information. This parameter can be NULL. For the format of the structure, see EimRC -- EIM return code parameter for C/C++.

Related Information

See the following:

Authorization

EIM data
EIM access groups control access to EIM data. 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
z/OS authorization
No special authorization is needed.

Return Values

The following table lists the return values from the API. Following each return value is the list of possible values for the messageCatalogMessageID field in the eimrc parameter for that value.
Return Value Meaning
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.
EIMERR_NOLOCK (26)
(z/OS does not return this value.) Unable to allocate internal system object.
ECONVERT Data conversion error.
EIMERR_DATA_CONVERSION (13)
(z/OS does not return this value.) Error occurred when converting data between code pages.
EINVAL Input parameter was not valid.
EIMERR_ACCESS_TYPE_INVAL (2)
Access type is not valid.
EIMERR_ACCESS_USERTYPE_INVAL (3)
Access user type is not valid.
EIMERR_HANDLE_INVAL (17)
EimHandle is not valid.
EIMERR_PARM_REQ (34)
Missing required parameter. Please check the API documentation.
EIMERR_PTR_INVAL (35)
(z/OS does not return this value.) Pointer parameter is not valid.
EIMERR_REG_MUST_BE_NULL (55)
Registry name must be NULL when access type is not EIM_ACCESS_REGISTRY.
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 either the eimConnect or eimConnectToMaster API and try the request again.
EUNKNOWN Unexpected exception.
EIMERR_LDAP_ERR (23)
Unexpected LDAP error.
EIMERR_UNKNOWN (44)
Unknown error or unknown system state.

Example

The following illustrates a query to see if the distinguished name "cn=pete,o=ibm,c=us" is a member of the "EIM Administrator" access group. 
#include <eim.h>

 
.
	.
	.
    int           rc;
    char          eimerr[200];
    EimRC       * err;
    EimHandle     handle;
    EimAccessUser user; 
    unsigned int indicator;
	.
	.
	.
    /* Set up error structure.                  */
    memset(eimerr,0x00,200);
    err = (EimRC *)eimerr;
    err->memoryProvidedByCaller = 200;
	.
	.
	.
    /* Set up access user info                  */
    user.userType = EIM_ACCESS_DN;
    user.user.DN="cn=pete,o=ibm,c=us";
    
    /* Query access for this user.              */
    rc = eimQueryAccess(&handle,
                        &user,
                        EIM_ACCESS_ADMIN,
                        NULL,
                        &indicator,
                        err);
	.
	.
	.