ibm-information-center/dist/eclipse/plugins/i5OS.ic.apis_5.4.0.1/eimremoveaccess.htm

532 lines
18 KiB
HTML
Raw Normal View History

2024-04-02 14:02:31 +00:00
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta name="Copyright" content="Copyright (c) 2006 by IBM Corporation">
<title>eimRemoveAccess()--Remove EIM Access</title>
<!-- Begin header records -->
<!-- All rights reserved. Licensed Materials Property of IBM -->
<!-- US Government Users Restricted Rights -->
<!-- Use, duplication or disclosure restricted by -->
<!-- GSA ADP Schedule Contract with IBM Corp. -->
<!-- Change History: -->
<!-- YYMMDD USERID Change description -->
<!-- Created by Carol Budnik on 17 July 2001 -->
<!-- Edited by Kersten Jan 02 -->
<!-- End Header Records -->
<link rel="stylesheet" type="text/css" href="../rzahg/ic.css">
</head>
<body>
<!--Java sync-link-->
<script type="text/javascript" language="javascript" src="../rzahg/synch.js">
</script>
<a name="Top_Of_Page"></a>
<!-- ============================================================== -->
<!-- -->
<!-- -->
<!-- ============================================================== -->
<h2>eimRemoveAccess()--Remove
EIM Access</h2>
<!-- ============================================================== -->
<!-- -->
<!-- S Y N T A X / P A R M T A B L E -->
<!-- -->
<!-- ============================================================== -->
<div class="box" style="width: 80%;">
<br>
&nbsp;&nbsp;Syntax
<pre>
#include &lt;eim.h&gt;
int eimRemoveAccess(EimHandle * <em>eim</em>,
EimAccessUser * <em>accessUser</em>,
enum EimAccessType <em>accessType</em>,
char * <em>registryName</em>,
EimRC * <em>eimrc</em>)
</pre>
&nbsp;&nbsp;Service Program Name: QSYS/QSYEIM<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Default Public Authority: *USE<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Threadsafe: Yes<br>
<!-- iddvc RMBR -->
<br>
</div>
<!-- ============================================================== -->
<!-- -->
<!-- D E S C R I P T I O N -->
<!-- -->
<!-- ============================================================== -->
<p>The <strong>eimRemoveAccess()</strong> function removes the user
from the EIM access group identified by the access type.</p>
<br>
<!-- ============================================================== -->
<!-- -->
<!-- A U T H O R I T I E S A N D L O C K S -->
<!-- -->
<!-- ============================================================== -->
<h3>Authorities and Locks</h3>
<dl>
<dt><em>EIM Data</em></dt>
<dd>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:
<ul>
<li>EIM Administrator</li>
</ul>
</dd>
</dl>
<br>
<!-- ============================================================== -->
<!-- -->
<!-- P A R A M E T E R S -->
<!-- -->
<!-- ============================================================== -->
<h3>Parameters</h3>
<dl>
<!-- ============================================================== -->
<!-- eim -->
<!-- ============================================================== -->
<dt><strong>eim</strong>&nbsp;&nbsp;(Input)</dt>
<dd>The EIM handle returned by a previous call to eimCreateHandle().
A valid connection is required for this function.
<br><br></dd>
<!-- ============================================================== -->
<!-- accessUser -->
<!-- ============================================================== -->
<dt><strong>accessUser</strong>&nbsp;&nbsp;(Input)</dt>
<dd>A structure that contains the user information to remove access from.
<br><br>
<table cellpadding="5">
<!-- cols="25 75" -->
<tr>
<td align="left" valign="top" nowrap><em>EIM_ACCESS_LOCAL_USER</em></td>
<td align="left" valign="top">Indicates a local user name on the system
that the API is run. The local user name will be converted to the
appropriate access id for this system.</td>
</tr><tr>
<td align="left" valign="top"><em>EIM_ACCESS_KERBEROS</em></td>
<td align="left" valign="top">Indicates a kerberos principal.
The kerberos principal will be converted to the appropriate access id.
For example, petejones@therealm will be converted to
ibm-kn=petejones@threalm.</td>
</tr></table>
<p>The EimAccessUser structure layout follows:</p>
<pre>
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;
</pre>
</dd>
<!-- ============================================================== -->
<!-- accessType -->
<!-- ============================================================== -->
<dt><strong>accessType</strong>&nbsp;&nbsp;(Input)</dt>
<dd>The type of access to remove. Valid values are:
<br><br>
<table cellpadding="5">
<!-- cols="35 65" -->
<tr>
<td align="left" valign="top"><em>EIM_ACCESS_ADMIN (0)</em></td>
<td align="left" valign="top">Administrative authority to the entire EIM domain.</td>
</tr>
<tr>
<td align="left" valign="top"><em>EIM_ACCESS_REG_ADMIN (1)</em></td>
<td align="left" valign="top">Administrative authority to all registries in the EIM domain.</td>
</tr>
<tr>
<td align="left" valign="top"><em>EIM_ACCESS_REGISTRY (2)</em></td>
<td align="left" valign="top">Administrative authority to the registry specified in the <em>registryName</em> parameter.</td>
</tr>
<tr>
<td align="left" valign="top" nowrap><em>EIM_ACCESS_IDENTIFIER_ADMIN (3)</em></td>
<td align="left" valign="top">Administrative authority to all of the identifiers in the EIM domain.</td>
</tr>
<tr>
<td align="left" valign="top"><em>EIM_ACCESS_MAPPING_LOOKUP (4)</em></td>
<td align="left" valign="top">Authority to perform mapping lookup operations.</td>
</tr>
<tr>
<td align="left" valign="top"><em><img src="delta.gif" alt="Start of change">EIM_ACCESS_CREDENTIAL_DATA (5)</em></td>
<td align="left" valign="top">Authority to retrieve credential data.<img src="deltaend.gif" alt="End of change"></td>
</tr>
</table><br>
</dd>
<!-- ============================================================== -->
<!-- registryName -->
<!-- ============================================================== -->
<dt><strong>registryName</strong>&nbsp;&nbsp;(Input)</dt>
<dd>The name of the registry to remove access from. This parameter is
only used if EimAccessType is EIM_ACCESS_REGISTRY.
If EimAccessType is anything other than EIM_ACCESS_REGISTRY,
this parameter must be NULL.
<br><br></dd>
<!-- ============================================================== -->
<!-- eimrc -->
<!-- ============================================================== -->
<dt><strong>eimrc</strong>&nbsp;&nbsp;(Input/Output)</dt>
<dd>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 <a href="eimrc.htm">EimRC--EIM Return Code
Parameter</a>.
<br><br></dd>
</dl>
<!-- ============================================================== -->
<!-- -->
<!-- R E T U R N V A L U E -->
<!-- -->
<!-- ============================================================== -->
<h3>Return Value</h3>
<p>The return value from the API. Following each return value is the list of
possible values for the
<samp>messageCatalogMessageID</samp> field in the <em>eimrc</em> parameter
for that value.</p>
<dl>
<!-- ============================================================== -->
<!-- 0 -->
<!-- ============================================================== -->
<dt><strong>0</strong></dt>
<dd>Request was successful.<br>
<br>
</dd>
<!-- ============================================================== -->
<!-- EACCES -->
<!-- ============================================================== -->
<dt><strong>EACCES </strong></dt>
<dd>Access denied. Not enough permissions to access data.<br>
<br>
<table cellpadding="5">
<!-- cols="25 75" -->
<tr>
<td align="left" valign="top"><em>EIMERR_ACCESS (1)</em></td>
<td align="left" valign="top">Insufficient access to EIM data.</td>
</tr>
</table>
<br>
</dd>
<!-- ============================================================== -->
<!-- EBADDATA -->
<!-- ============================================================== -->
<dt><strong>EBADDATA </strong></dt>
<dd>eimrc is not valid.<br>
<br>
</dd>
<!-- ============================================================== -->
<!-- EBUSY -->
<!-- ============================================================== -->
<dt><strong>EBUSY </strong></dt>
<dd>Unable to allocate internal system object.<br>
<br>
<table cellpadding="5">
<!-- cols="25 75" -->
<tr>
<td align="left" valign="top"><em>EIMERR_NOLOCK (26)</em></td>
<td align="left" valign="top">Unable to allocate internal system object.</td>
</tr>
</table>
<br>
</dd>
<!-- ============================================================== -->
<!-- ECONVERT -->
<!-- ============================================================== -->
<dt><strong>ECONVERT </strong></dt>
<dd>Data conversion error.<br>
<br>
<table cellpadding="5">
<!-- cols="35 65" -->
<tr>
<td align="left" valign="top"><em>EIMERR_DATA_CONVERSION (13)</em></td>
<td align="left" valign="top">Error occurred when converting data between code pages.</td>
</tr>
</table>
<br>
</dd>
<!-- ============================================================== -->
<!-- EINVAL -->
<!-- ============================================================== -->
<dt><strong>EINVAL </strong></dt>
<dd>Input parameter was not valid.<br>
<br>
<table cellpadding="5">
<!-- cols="40 60" -->
<tr>
<td align="left" valign="top"><em>EIMERR_ACCESS_TYPE_INVAL (2)</em></td>
<td align="left" valign="top">Access type is not valid.</td>
</tr>
<tr>
<td align="left" valign="top" nowrap><em>EIMERR_ACCESS_USERTYPE_INVAL (3)</em></td>
<td align="left" valign="top">Access user type is not valid.</td>
</tr>
<tr>
<td align="left" valign="top"><em>EIMERR_HANDLE_INVAL (17)</em></td>
<td align="left" valign="top">EimHandle is not valid.</td>
</tr>
<tr>
<td align="left" valign="top"><em>EIMERR_PARM_REQ (34)</em></td>
<td align="left" valign="top">Missing required parameter. Please check API documentation.</td>
</tr>
<tr>
<td align="left" valign="top"><em>EIMERR_PTR_INVAL (35)</em></td>
<td align="left" valign="top">Pointer parameter is not valid.</td>
</tr>
<tr>
<td align="left" valign="top"><em>EIMERR_REG_MUST_BE_NULL (55)</em></td>
<td align="left" valign="top">Registry name must be NULL when access
type is not EIM_ACCESS_REGISTRY.</td>
</tr>
</table>
<br>
</dd>
<!-- ============================================================== -->
<!-- ENOMEM -->
<!-- ============================================================== -->
<dt><strong>ENOMEM </strong></dt>
<dd>Unable to allocate required space.<br>
<br>
<table cellpadding="5">
<!-- cols="25 75" -->
<tr>
<td align="left" valign="top"><em>EIMERR_NOMEM (27)</em></td>
<td align="left" valign="top">No memory available. Unable to allocate required space.</td>
</tr>
</table>
<br>
</dd>
<!-- ============================================================== -->
<!-- ENOTCONN -->
<!-- ============================================================== -->
<dt><strong>ENOTCONN </strong></dt>
<dd>LDAP connection has not been made.<br>
<br>
<table cellpadding="5">
<!-- cols="25 75" -->
<tr>
<td align="left" valign="top"><em>EIMERR_NOT_CONN (31)</em></td>
<td align="left" valign="top">Not connected to LDAP. Use eimConnect() API and
try the request again.</td>
</tr>
</table>
<br>
</dd>
<!-- ============================================================== -->
<!-- EROFS -->
<!-- ============================================================== -->
<dt><strong>EROFS </strong></dt>
<dd>LDAP connection is for read only. Need to connect to master.<br>
<br>
<table cellpadding="5">
<!-- cols="25 75" -->
<tr>
<td align="left" valign="top"><em>EIMERR_READ_ONLY (36)</em></td>
<td align="left" valign="top">LDAP connection is for read only. Use
eimConnectToMaster() to get a write connection.</td>
</tr>
</table>
<br>
</dd>
<!-- ============================================================== -->
<!-- EUNKNOWN -->
<!-- ============================================================== -->
<dt><strong>EUNKNOWN </strong></dt>
<dd>Unexpected exception.<br>
<br>
<table cellpadding="5">
<!-- cols="25 75" -->
<tr>
<td align="left" valign="top"><em>EIMERR_LDAP_ERR (23)</em></td>
<td align="left" valign="top">Unexpected LDAP error. %s</td>
</tr>
<tr>
<td align="left" valign="top"><em>EIMERR_UNKNOWN (44)</em></td>
<td align="left" valign="top">Unknown error or unknown system state.</td>
</tr>
</table>
</dd>
</dl>
<br>
<!-- ============================================================== -->
<!-- -->
<!-- U S A G E N O T E S -->
<!-- -->
<!-- ============================================================== -->
<!-- ============================================================== -->
<!-- -->
<!-- R E L A T E D I N F O R M A T I O N -->
<!-- -->
<!-- ============================================================== -->
<h3>Related Information</h3>
<ul>
<li><a href="eimaddaccess.htm">eimAddAccess()</a>
--Add EIM Access<br>
<br>
</li>
<li><a href="eimlistaccess.htm">eimListAccess()</a>
--List EIM Access<br>
<br>
</li>
<li><a href="eimlistuseraccess.htm">eimListUserAccess()</a>
--List EIM User Access<br>
<br>
</li>
<li><a href="eimqueryaccess.htm">eimQueryAccess()</a>
--Query EIM Access<br>
<br>
</li>
</ul>
<br>
<!-- ============================================================== -->
<!-- -->
<!-- E X A M P L E -->
<!-- -->
<!-- ============================================================== -->
<h3>Example</h3>
<p>See <a href="../apiref/aboutapis.htm#codedisclaimer">Code disclaimer information</a>
for information pertaining to code examples.</p>
<p>The following example removes the user from the access group.</p>
<pre>
#include &lt;eim.h&gt;
#include &lt;stdio.h&gt;
int main(int argc, char *argv[])
{
int rc;
char eimerr[100];
EimRC * err;
EimHandle * handle;
EimAccessUser user;
<em>/* Get eim handle from input arg. */</em>
<em>/* This handle is already connected to EIM. */</em>
handle = (EimHandle *)argv[1];
<em>/* Set up error structure. */</em>
memset(eimerr,0x00,100);
err = (EimRC *)eimerr;
err->memoryProvidedByCaller = 100;
<em>/* Set user information */</em>
user.userType = EIM_ACCESS_DN;
user.user.dn="cn=pete,o=ibm,c=us";
<em>/* Remove access for this user. */</em>
if (0 != (rc = eimRemoveAccess(handle,
&amp;user,
EIM_ACCESS_ADMIN,
NULL,
err)))
{
printf("Remove access error = %d", rc);
return -1;
}
return 0;
}
</pre>
<br>
<!-- ============================================================== -->
<!-- -->
<!-- F O O T E R -->
<!-- -->
<!-- ============================================================== -->
<hr>
API introduced: V5R2
<hr>
<center>
<table cellpadding="2" cellspacing="2">
<tr align="center">
<td valign="middle" align="center"><a href="#Top_Of_Page">Top</a> | <a href=
"sec.htm">Security APIs</a> | <a href="aplist.htm">APIs by category</a></td>
</tr>
</table>
</center>
</body>
</html>