home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
OS/2 Shareware BBS: 10 Tools
/
10-Tools.zip
/
dceapref.zip
/
DCEAPREF.INF
(
.txt
)
Wrap
OS/2 Help File
|
1998-05-08
|
2MB
|
72,544 lines
ΓòÉΓòÉΓòÉ 1. Notices ΓòÉΓòÉΓòÉ
Second Edition (June 1996)
The following paragraph does not apply to the United Kingdom or any country
where such provisions are inconsistent with local law: INTERNATIONAL BUSINESS
MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY
KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states
do not allow disclaimer of express or implied warranties in certain
transactions, therefore, this statement may not apply to you.
This publication could include technical inaccuracies or typographical errors.
Changes are periodically made to the information herein; these changes will be
incorporated in new editions of the publication. IBM may make improvements
and/or changes in the product(s) and/or the program(s) described in this
publication at any time.
It is possible that this publication may contain reference to, or information
about, IBM products (machines and programs), programming, or services that are
not announced in your country. Such references or information must not be
construed to mean that IBM intends to announce such IBM products, programming,
or services in your country.
Requests for technical information about IBM products should be made to your
IBM reseller or IBM marketing representative.
ΓòÉΓòÉΓòÉ 1.1. Copyright Notices ΓòÉΓòÉΓòÉ
COPYRIGHT LICENSE: This publication contains printed sample application
programs in source language, which illustrate OS/2 programming techniques. You
may copy, modify, and distribute these sample programs in any form without
payment to IBM, for the purposes of developing, using, marketing or
distributing application programs conforming to the OS/2 application
programming interface.
Each copy of any portion of these sample programs or any derivative work, which
is distributed to others, must include a copyright notice as follows: "(C)
(your company name) (year). All rights reserved."
(C)Copyright International Business Machines Corporation 1992, 1996. All
rights reserved.
Note to U.S. Government Users - Documentation related to restricted rights -
Use, duplication or disclosure is subject to restrictions set forth in GSA ADP
Schedule Contract with IBM Corp.
ΓòÉΓòÉΓòÉ 1.2. Disclaimers ΓòÉΓòÉΓòÉ
References in this publication to IBM products, programs, or services do not
imply that IBM intends to make these available in all countries in which IBM
operates. Any reference to an IBM product, program or service is not intended
to state or imply that only that IBM product, program, or service may be used.
Subject to IBM's valid intellectual property or other legally protectable
rights, any functionally equivalent product, program, or service may be used
instead of the IBM product, program, or service. The evaluation and
verification of operation in conjunction with other products, except those
expressly designated by IBM, are the responsibility of the user.
IBM may have patents or pending patent applications covering subject matter in
this document. The furnishing of this document does not give you any license to
these patents. You can send license inquiries, in writing, to:
IBM Director of Licensing
IBM Corporation
500 Columbus Avenue
Thornwood, NY 10594
U.S.A.
Licensees of this program who wish to have information about it for the
purpose of enabling: (i) the exchange of information between independently
created programs and other programs (including this one) and (ii) the mutual
use of the information which has been exchanged, should contact IBM
Corporation, Department LZKS, 11400 Burnet Road, Austin, TX 78758 U.S.A. Such
information may be available, subject to appropriate terms and conditions,
including in some cases, payment of a fee.
Asia-Pacific users can inquire, in writing, to the IBM Director of
Intellectual Property and Licensing, IBM World Trade Asia Corporation, 2-31
Roppongi 3-chome, Minato-ku, Tokyo 106, Japan.
ΓòÉΓòÉΓòÉ 1.3. Trademarks ΓòÉΓòÉΓòÉ
The following terms are trademarks of the IBM Corporation in the United States
or other countries or both:
AIX
IBM
OS/2
The following terms are trademarks of other companies:
OSF Open Software Foundation
UNIX Registered trademark in the United States and other countries,
licensed exclusively through X/Open Company Limited.
Other company, product, and service names, which may be denoted by a double
asterisk (**), may be trademarks or service marks of others.
ΓòÉΓòÉΓòÉ 2. How This Book is Organized ΓòÉΓòÉΓòÉ
This reference is organized in sections according to the Distributed Computing
Environment (DCE) component technologies. The sections are as follows:
1. The DCE Routines describes the routines used to return information based
on the contents of the local DCE configuration file.
2. The DCE Threads API describes a set of routines that you can call to
create a multithreaded program.
3. The DCE Remote Procedure Call API describes the Remote Procedure Call
(RPC) Application Programming Interface (API).
4. Directory Service API describes the Directory Service routines and header
files.
5. The DCE Distributed Time Service API describes the Distributed Time
Service (DTS), which allows you to obtain and manipulate timestamps.
6. DCE Security Services API describes the Security Services API, which
allows you to create network services that can access the authentication
and authorization capabilities of DCE Security.
7. DCE Event Management Service API describes the Event Management Service
(EMS) routines.
8. DCE SNMP Management Information Base describes Simple Network Management
Protocol (SNMP) information.
ΓòÉΓòÉΓòÉ 3. The DCE Routines ΓòÉΓòÉΓòÉ
The DCE routines provide several facilities that are applicable across more
than one DCE component. They can be divided into the following major areas:
The DCE C Runtime Routines These routines are used only on the OS/2 platform.
They are entry points within the DCE Dynamic Link
Libraries (DLLs) that call C runtime routines bound into
the DCE DLLs.
The DCE ACL Interface Routines These routines enable servers to perform
DCE-conformant authorization checks at runtime. This ACL
Library provides an implementation of the ACL Manager
Interface and the ACL Network Interface. It supports
development of ACL managers for DCE servers.
The DCE Attribute Interface API These routines allow applications to define
and access attribute types (schema entries) in a schema of
your choice. They are based on the Extended Registry
Attribute (ERA) interface, which defines and accesses
attribute types in the register database schema.
DCE Audit API The DCE Audit API allows applications to perform auditing
and to analyze audit trails.
The DCE Configuration Routines These routines return information based on the
contents of the local DCE configuration file, which is
created during the DCE cell-configuration or
machine-configuration process.
The DCE Backing Store Interface These routines allow you to maintain typed
data between program invocations. The backing store
routines can be used in servers, in clients, or in
stand-alone programs that do not involve remote procedure
calls (RPC).
The DCE Messaging Interface These routines give you access to message
catalogs, to specific message texts and message IDs, and
to in-memory message tables.
The DCE Server Routines These routines are used by servers to register
themselves with DCE. This includes RPC runtime, the local
endpoint mapper, and the namespace. Routines are also
available to set up DCE security so that servers can
receive and invoke authenticated RPCs.
The DCE Serviceability Interface These routines are intended for use by
servers that export the serviceability interface defined
in service.idl. There is also a set of DCE serviceability
macros can be used for diagnostic purposes, and to create
a serviceability handle.
For information about the individual DCE serviceability
macros, see The DCE Serviceability Macros.
The DCE Host Daemon Routines These routines give management applications
remote access to various data, servers, and services on
DCE hosts.
ΓòÉΓòÉΓòÉ 3.1. The DCE C Runtime Routines ΓòÉΓòÉΓòÉ
The DCE dce_free Routine
The dce_free routine is used to free allocated memory. A number of DCE routines
allocate memory using the C runtime routine malloc. When these routines are
finished with the allocated memory, they need to be followed with a routine to
free the memory. Typically, this is done by calling the C free routine.
However, on OS/2 platforms, unpredictable results can occur using free. The
reason is that the DCE routines that allocate the memory use the version of the
C runtime that is bound into the DCE Dynamic Link Libraries (DLLs). But, the
application that frees the memory uses whatever C runtime to which it is
linked. Therefore, you must use the dce_free routine to replace the standard C
free routine. The dce_free routine is an entry point within the DCE DLLs that
call the C free routine.
For more information about the use of this routine and a list of the routines
that must be followed by a call to dce_free, see dce_free.
The DCE dce_getenv and dce_putenv Routines
The dce_getenv routine is used to obtain DCE environment variable values. The
dce_putenv routine is used to modify or add environment variables in the DCE
environment string. Typically, this is done by calling the getenv and putenv C
runtime routines. The C runtime has a buffer where the environment string is
stored. However, on OS/2 platforms, DCE uses the version of the C runtime that
is bound into the DCE Dynamic Link Libraries (DLLs). But, the application uses
whatever C runtime (whose getenv and putenv use a different buffer) to which it
is bound. In order to access variables in the DCE environment string,
applications must use the dce_getenv and dce_putenv to replace the standard C
getenv and putenv routines. The dce_getenv and dce_putenv routines are entry
points within the DCE DLLs that call the C getenv and putenv routines,
respectively.
ΓòÉΓòÉΓòÉ 3.1.1. dce_free ΓòÉΓòÉΓòÉ
Purpose
Frees memory allocated by DCE routines.
Format
#include <dce\dcefree.h>
void dce_free(
void *ptr);
Parameters
Input
ptr The block of storage to be freed. This block of storage
must have been allocated by a call to one of the DCE
routines listed in Usage.
Usage
The dce_free routine is used on the OS/2 platforms to free memory
allocated by the following DCE routines:
dce_msg_get
dce_msg_get_msg
dce_sprintf
dce_pgm_sprintf
dce_aud_print
dce_cf_find_name_by_key
dce_cf_get_cell_name
dce_cf_get_host_name
dce_cf_dced_entry_from_host
dce_cf_get_csrgy_filename
dce_db_header_fetch
Notes
This routine is not a general routine for freeing memory, nor is it a
replacement for other DCE routines that free memory (for example,
rpc_string_free).
Because dce_free is only used on OS/2, you should make sure that any
calls to dce_free are within the bounds of an #ifdef for portability.
Examples
This example shows the use of dce_free within an #ifdef.
#ifdef OS2
dce_free (ptr);
#else
free (ptr);
#endif
Another approach is:
#ifndef OS2
#define dce_free
#endif
Related Information
Routines:
dce_msg_get
dce_msg_get_msg
dce_sprintf
dce_pgm_sprintf
dce_aud_print
dce_cf_find_name_by_key
dce_cf_get_cell_name
dce_cf_get_host_name
dce_cf_dced_entry_from_host
dce_cf_get_csrgy_filename
dce_db_header_fetch
ΓòÉΓòÉΓòÉ 3.1.2. dce_getenv ΓòÉΓòÉΓòÉ
Purpose
Enables the application to obtain the string value of a variable name
from the DCE environment string.
Format
#include <dce\dcegetenv.h>
char * dce_getenv(
const char *varname);
Parameters
Input
varname A character string that is the variable name in the DCE
environment string whose value the application is
trying to obtain.
Usage
The dce_getenv routine is used only on the OS/2 platforms to retrieve
values of DCE environment variables from the DCE environment string.
As a result, you should make sure that any calls to dce_getenv are
within the bounds of an #ifdef for portability.
Examples
This example shows the use of dce_getenv within an #ifdef.
#ifdef OS2
ptr = dce_getenv ("TRY_PE_SITE");
#else
rc = getenv ("TRY_PE_SITE");
#endif
Return Codes
This routine returns a pointer to the character string value of the
variable name if found in the DCE environment string. If varname was
not found in the DCE environment string, the routine sets the pointer
to NULL.
ΓòÉΓòÉΓòÉ 3.1.3. dce_putenv ΓòÉΓòÉΓòÉ
Purpose
Enables the application to modify DCE environment variables or place
additional variables into the DCE environment string.
Format
#include <dce\dceputenv.h>
int dce_putenv(
const char *string);
Parameters
Input
string A character string of the format varname=varstring
where varname is the name of the environment variable
to be added or modified and varstring is the value of
the variable.
Usage
The dce_putenv routine is used only on OS/2 platforms to modify
existing DCE environment variables or add environment variables to
the DCE environment string. As a result, you should make sure that
any calls to dce_putenv are within the bounds of an #ifdef for
portability.
Return Codes
On successful completion the routine returns 0. Otherwise, it returns
-1.
Examples
This example shows the use of dce_putenv within an #ifdef.
#ifdef OS2
rc = dce_putenv ("TRY_PE_SITE=1");
#else
rc = putenv ("TRY_PE_SITE=1");
#endif
ΓòÉΓòÉΓòÉ 3.2. The DCE ACL Interface Routines ΓòÉΓòÉΓòÉ
The ACL Library API, dce_acl_xxx, is a local interface that provides the
server-side implementation of the ACL network interface.
The ACL library consists of the following parts:
o Initialization routine
An ACL manager calls the following routine to initialize and define
objects:
dce_acl_register_object_type Registers an object type,
once for each type of
object that the server
manages.
o Server queries
The ACL library provides several routines to automate the most common
uses of DCE ACLs:
dce_acl_inq_client_permset Returns client
permissions, corresponding
to an ACL.
dce_acl_inq_client_creds Returns client
credentials.
dce_acl_inq_permset_for_creds Determines a client's
complete extent of access
to an object.
dce_acl_inq_acl_from_header Retrieves the UUID of an
ACL from the header of an
object in the backing
store.
dce_acl_inq_prin_and_group Inquires for the principal
and group of an RPC
caller.
dce_acl_is_client_authorized Checks whether client
credentials are
authenticated, and if so,
that they grant the
desired access.
dce_acl_is_unauthenticated Checks whether credentials
are unauthenticated.
o Creating ACL objects
The following convenience routines can be used by an application
programmer to create ACL objects in other servers or clients:
dce_acl_copy_acl Copies an ACL.
dce_acl_obj_init Initializes an ACL for
an object.
dce_acl_obj_free_entries Frees space used by ACL
entries.
dce_acl_obj_add_user_entry Adds permissions for a
user ACL entry to the
given ACL.
dce_acl_obj_add_group_entry Adds permissions for a
group ACL entry to the
given ACL.
dce_acl_obj_add_id_entry Adds permissions for an
ACL entry to the given
ACL.
dce_acl_obj_add_unauth_entry Adds permissions for an
"unauthenticated" ACL
entry to the given ACL.
dce_acl_obj_add_obj_entry Adds permissions for an
"obj" ACL entry to the
given ACL.
dce_acl_obj_add_foreign_entry Adds permissions for
the ACL entry for a
foreign user or group
to the given ACL.
dce_acl_obj_add_any_other_entry Adds permissions for
the "any_other" ACL
entry to a given ACL.
o Implementing rdacl
In order to implement the rdacl interface, the server must register the
rdacl interface with the RPC runtime and with the endpoint mapper. The
server must provide a resolution routine that maps the rdacl parameters
into the UUID of the desired ACL object. The library includes two such
routines:
dce_acl_resolve_by_name Finds an ACL's UUID, given an
object name.
dce_acl_resolve_by_uuid Finds an ACL's UUID, given an
object UUID.
For situations in which neither of these resolver routines is
appropriate, application developers must provide their own.
ΓòÉΓòÉΓòÉ 3.2.1. dce_acl_copy_acl ΓòÉΓòÉΓòÉ
Purpose
Copies an ACL.
Format
#include <dce\dce.h>
#include <dce\aclif.h>
void dce_acl_copy_acl(
sec_acl_t *source,
sec_acl_t *target,
error_status_t *status);
Parameters
Input
source A pointer to the ACL to be copied.
target A pointer to the new ACL that is to receive the copy.
Output
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns rpc_s_no_memory, which indicates
that the rpc_sm_allocate routine could not obtain
memory.
Usage
The dce_acl_copy_acl routine makes a copy of a specified ACL. The
caller passes the space for the target ACL, but the space for the
sec_acl_entries array is allocated. To free the allocated space, call
dce_acl_obj_free_entries, which frees the entries, but not the ACL
itself.
Related Information
Routines:
dce_acl_obj_free_entries
ΓòÉΓòÉΓòÉ 3.2.2. dce_acl_inq_acl_from_header ΓòÉΓòÉΓòÉ
Purpose
Retrieves the UUID of an ACL from an item's header in a backing
store.
Format
#include <dce\dce.h>
#include <dce\aclif.h>
void dce_acl_inq_acl_from_header(
dce_db_header_t db_header,
sec_acl_type_t sec_acl_type,
uuid_t *acl_uuid,
error_status_t *status);
Parameters
Input
db_header The backing store header containing the ACL
object.
sec_acl_type The type of ACL to be identified:
sec_acl_type_object,
sec_acl_type_default_object, or
sec_acl_type_default_container.
Output
acl_uuid A pointer to the UUID of the ACL object.
status A pointer to the completion status. On
successful completion, the routine returns
error_status_ok. Otherwise, it returns one
of the following errors:
db_s_key_not_found The specified key
was not found in the backing
store. (This error is passed
through from dce_db_fetch.)
db_s_bad_index_type The key's type is
wrong, or else the backing store
is not indexed by name or by UUID.
(This error is passed through from
dce_db_fetch.)
sec_acl_invalid_type The sec_acl_type
parameter does not contain a valid
type.
Usage
The dce_acl_inq_acl_from_header routine gets the UUID for an ACL
object of the specified type from the specified backing store header.
Related Information
Routines:
dce_acl_resolve_by_name
dce_acl_resolve_by_uuid
ΓòÉΓòÉΓòÉ 3.2.3. dce_acl_inq_client_creds ΓòÉΓòÉΓòÉ
Purpose
Returns the client's credentials.
Format
#include <dce\dce.h>
#include <dce\aclif.h>
void dce_acl_inq_client_creds(
handle_t handle,
rpc_authz_cred_handle_t *creds,
error_status_t *status);
Parameters
Input
handle The remote procedure call binding handle.
Output
creds The address of an rpc_authz_cred_handle_t structure in
which to return the client's credentials, or NULL if
unauthorized.
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns one of the following errors:
rpc_s_authn_authz_mismatch Either the client, or
the server, or both is not using the
rpc_c_authz_dce authorization service.
rpc_s_invalid_binding Invalid RPC binding handle.
rpc_s_wrong_kind_of_binding Wrong kind of binding
for the operation.
rpc_s_binding_has_no_auth Binding has no
authentication information. The client or
the server should have called
rpc_binding_set_auth_info.
Usage
The dce_acl_inq_client_creds routine returns the client's security
credentials found through the RPC binding handle.
Related Information
Routines:
dce_acl_inq_client_permset
dce_acl_inq_permset_for_creds
dce_acl_register_object_type
ΓòÉΓòÉΓòÉ 3.2.4. dce_acl_inq_client_permset ΓòÉΓòÉΓòÉ
Purpose
Returns the client's permissions corresponding to an ACL.
Format
#include <dce\dce.h>
#include <dce\aclif.h>
void dce_acl_inq_client_permset(
handle_t handle,
uuid_t *mgr_type,
uuid_t *acl_uuid,
sec_acl_permset_t *permset,
error_status_t *status);
Parameters
Input
handle The remote procedure call binding handle.
mgr_type A pointer to the UUID identifying the type of the ACL
manager in question. There may be more than one type
of ACL manager protecting the object whose ACL is bound
to the input handle. Use this parameter to distinguish
them.
acl_uuid A pointer to the UUID of the ACL.
Output
permset The set of permissions allowed to the client.
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns acl_s_bad_manager_type, which
indicates that the mgr_type parameter does not match
the manager type in the ACL itself.
Usage
The dce_acl_inq_client_permset routine returns the client's
permissions that correspond to the ACL. It finds the ACL in the
database as defined for this ACL manager type with
dce_acl_register_object_type. The client's credentials are determined
from the binding handle. The ACL and credentials determine the
permission set.
Related Information
Routines:
dce_acl_inq_client_creds
dce_acl_inq_permset_for_creds
dce_acl_register_object_type
ΓòÉΓòÉΓòÉ 3.2.5. dce_acl_inq_permset_for_creds ΓòÉΓòÉΓòÉ
Purpose
Determines a principal's complete extent of access to an object.
Format
#include <dce\dce.h>
#include <dce\aclif.h>
void dce_acl_inq_permset_for_creds(
rpc_authz_cred_handle_t creds,
sec_acl_t *ap,
uuid_t *owner_id,
uuid_t *group_id,
sec_acl_posix_semantics_t posix_semantics,
sec_acl_permset_t *perms,
error_status_t *status);
Parameters
Input
creds The security credentials that represent the principal.
ap The ACL that represents the object.
owner_id Identifies the owner of the object that is protected by
the specified ACL. If the sec_acl_e_type_user_obj ACLE
(ACL entry) exists, then the owner_id (uuid_t pointer)
cannot be NULL. If it is, then the error
sec_acl_expected_user_obj is returned.
group_id Identifies the group that the object that is protected
by the specified ACL belongs to. If a
sec_acl_e_type_group_obj ACLE exists, the group_id
(uuid_t pointer) cannot be NULL. If it is, the error
sec_acl_expected_group_obj is returned.
posix_semantics This parameter is currently unused in OSF
implementation.
Output
perms A bit mask containing a bit with a value of 1 for each
permission granted by the ACL and 0 bits elsewhere.
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Usage
The dce_acl_inq_permset_for_creds routine returns a principal's
"complete extent of access" to some object. This routine is useful
for implementing operations such as the conventional UNIX access
function.
The values allowed for the credentials representing the principal
include NULL or unauthenticated.
The routine normally returns TRUE, even when the access permissions
are determined to be all 0 bits (dce_acl_c_no_permissions). It
returns FALSE only on illogical error conditions (such as unsupported
ACL Entry types), in which case the status output gets the error
status code and the perms is set to dce_acl_c_no_permissions.
The following ACL entry types (of type sec_acl_entry_type_t) are
supported by this routine. The categories are checked in the order
shown.
ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
Γöé ACL ENTRY TYPE Γöé MEANING Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé sec_acl_e_type_user Γöé At most, one can match. Γöé
Γöé sec_acl_e_type_foreign_user Γöé Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé sec_acl_e_type_group Γöé The union of all permissions for Γöé
Γöé sec_acl_e_type_foreign_group Γöé each matching group. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé sec_acl_e_type_other_obj Γöé Matching local realm accesses. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé sec_acl_e_type_foreign_other Γöé At most, one can match. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé sec_acl_e_type_any_other Γöé Anything not in the other types. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé sec_acl_e_type_unauthenticatedΓöé The sec_acl_e_type_unauthenticated Γöé
Γöé Γöé type is a mask that is used for all Γöé
Γöé Γöé matches on unauthenticated creden- Γöé
Γöé Γöé tials. It is also intersected with Γöé
Γöé Γöé sec_acl_e_type_any_other for NULL Γöé
Γöé Γöé credentials. Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
Note: The meanings of the permission bits have no effect on the
action of the dce_acl_inq_permset_for_creds routine. The
interpretation of the bits is left entirely to the
application.
Related Information
Routines:
dce_acl_inq_client_creds
dce_acl_inq_client_permset
dce_acl_register_object_type
ΓòÉΓòÉΓòÉ 3.2.6. dce_acl_inq_prin_and_group ΓòÉΓòÉΓòÉ
Purpose
Gets the principal and group of an RPC caller.
Format
#include <dce\dce.h>
#include <dce\aclif.h>
void dce_acl_inq_prin_and_group(
handle_t handle,
uuid_t *principal,
uuid_t *group,
error_status_t *status);
Parameters
Input
handle The remote procedure call binding handle.
Output
principal The UUID of the principal of the caller of the RPC.
group The UUID of the group of the caller of the RPC.
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns an error.
The dce_acl_inq_prin_and_group routine can return
errors from dce_acl_inq_client_creds,
sec_cred_get_initiator, and sec_cred_get_pa_data. It
generates no error messages of its own.
Usage
The dce_acl_inq_prin_and_group routine finds the principal and group
of the caller of a remote procedure call. This information is useful
for filling in the owner_id and group_id fields of standard data or
object headers. Setting the owner and group makes sense only if your
ACL manager handles owners and groups, which you specify with the
dce_acl_c_has_owner and dce_acl_c_has_groups flags to
dce_acl_register_object_type.
If the caller is unauthenticated, the principal and group are filled
with the NIL UUID, generated through uuid_create_nil.
Examples
dce_db_std_header_init(db, &data, ..., &st);
dce_acl_inq_prin_and_group(h, &data.h.owner_id,
&data.h.group_id, &st);
Related Information
Routines:
dce_acl_register_object_type
ΓòÉΓòÉΓòÉ 3.2.7. dce_acl_is_client_authorized ΓòÉΓòÉΓòÉ
Purpose
Checks whether the client credentials are authenticated.
Format
#include <dce\dce.h>
#include <dce\aclif.h>
void dce_acl_is_client_authorized(
handle_t handle,
uuid_t *mgr_type,
uuid_t *acl_uuid,
uuid_t *owner_id,
uuid_t *group_id,
sec_acl_permset_t desired_perms,
boolean32 *authorized,
error_status_t *status);
Parameters
Input
handle The client binding handle.
mgr_type A pointer to the UUID identifying the type of the ACL
manager in question. There may be more than one type
of ACL manager protecting the object whose ACL is bound
to the input handle. Use this parameter to distinguish
them.
acl_uuid A pointer to the UUID of the ACL.
owner_id Identifies the owner of the object that is protected by
the specified ACL. If the sec_acl_e_type_user_obj ACLE
(ACL entry) exists, then the owner_id (uuid_t pointer)
cannot be NULL. If it is, then the error
sec_acl_expected_user_obj is returned.
group_id Identifies the group in which the object that is
protected by the specified ACL belongs. If a
sec_acl_e_type_group_obj ACLE exists, the group_id
(uuid_t pointer) cannot be NULL. If it is, the error
sec_acl_expected_group_obj is returned.
desired_perms A permission set containing the desired privileges.
This is a 32-bit set of permission flags. The flags can
represent the conventional file system permissions
(read, write, and execute), the extended AFS
permissions (owner, insert, and delete), or some other
permissions supported by the specific application ACL
manager. For example, a bit that is unused for file
system permissions can mean withdrawals are allowed for
a bank ACL manager, while it can mean matrix inversions
are allowed for a CPU ACL manager. The mgr_type
identifies the semantics of the bits.
Output
authorized A pointer to the TRUE or FALSE return value of the
routine.
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns acl_s_bad_manager_type, which
indicates that the mgr_type does not match the manager
type in the ACL itself.
Usage
The dce_acl_is_client_authorized routine returns TRUE in the
authorized parameter if, and only if, all of the desired permissions
(represented as bits in desired_perms) are included in the actual
permissions corresponding to the handle, the mgr_type, and the
acl_uuid UUID. Otherwise, the returned value is FALSE.
Note: The routine's return value is void. The returned boolean32
value is contained in the authorized parameter.
ΓòÉΓòÉΓòÉ 3.2.8. dce_acl_is_unauthenticated ΓòÉΓòÉΓòÉ
Purpose
Checks whether credentials are unauthenticated.
Format
#include <dce/dce.h>
#include <dce/aclif.h>
boolean32 dce_acl_is_unauthenticated(
rpc_authz_cred_handle_t cred_h);
Parameters
Output
cred_h Returns an opaque handle of type
rpc_authz_cred_handle_t to the authorization
information for the client that made the remote
procedure call on cred_h. The data referenced by this
parameter is read-only and cannot be modified by the
server. If the server wants to preserve any of the
returned data, it must copy the data into
server-allocated memory.
Usage
The dce_acl_is_unauthenticated routine checks whether credentials are
unauthenticated. The caller is unauthenticated if
rpc_binding_inq_auth_caller returns no_authen.
Related Information
Routines:
rpc_binding_inq_auth_caller
ΓòÉΓòÉΓòÉ 3.2.9. dce_acl_obj_add_any_other_entry ΓòÉΓòÉΓòÉ
Purpose
Adds permissions for access to a sec_acl_e_type_any_other ACL entry
to a given ACL.
Format
#include <dce\dce.h>
#include <dce\aclif.h>
void dce_acl_obj_add_any_other_entry(
sec_acl_t *acl,
sec_acl_permset_t permset,
error_status_t *status);
Parameters
Input
acl A pointer to the ACL that is to be modified.
permset The permissions to be granted for access to the
sec_acl_e_type_any_other entry.
Output
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns the following error:
sec_acl_cant_allocate_memory The requested
operation requires more memory than is
available.
Usage
The dce_acl_obj_add_any_other_entry routine adds an ACL entry for
sec_acl_e_type_any_other access to the specified ACL. It is
equivalent to calling the dce_acl_obj_add_obj_entry routine with the
sec_acl_e_type_any_other entry type, but is more convenient.
The data type that stores an ACL has a limited size. Attempting to
add too many entries generates a sec_acl_cant_allocate_memory error.
Related Information
Routines:
dce_acl_obj_add_obj_entry
ΓòÉΓòÉΓòÉ 3.2.10. dce_acl_obj_add_foreign_entry ΓòÉΓòÉΓòÉ
Purpose
Adds permissions for an ACL entry for a foreign user or group to the
given ACL.
Format
#include <dce\dce.h>
#include <dce\aclif.h>
void dce_acl_obj_add_foreign_entry(
sec_acl_t *acl,
sec_acl_entry_type_t entry_type,
sec_acl_permset_t permset,
uuid_t *realm,
uuid_t *id,
error_status_t *status);
Parameters
Input
acl A pointer to the ACL that is to be modified.
entry_type Must be one of the following types:
sec_acl_e_type_foreign_user
sec_acl_e_type_foreign_group
sec_acl_e_type_for_user_deleg
sec_acl_e_type_for_group_deleg
permset The permissions to be granted to the foreign group or
foreign user.
realm The UUID of the foreign cell.
id The UUID identifying the foreign group or foreign user.
Output
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns one of the following errors:
sec_acl_cant_allocate_memory The requested
operation requires more memory than is
available.
sec_acl_invalid_entry_type The type specified in
entry_type is not one of the four specified
types.
Usage
The dce_acl_obj_add_foreign_entry routine adds an ACL entry for
sec_acl_e_type_foreign_xxx access to the specified ACL.
The data type that stores an ACL has a limited size. Attempting to
add too many entries generates a sec_acl_cant_allocate_memory error.
Related Information
Routines:
dce_acl_obj_add_id_entry
sec_id_parse_name
ΓòÉΓòÉΓòÉ 3.2.11. dce_acl_obj_add_group_entry ΓòÉΓòÉΓòÉ
Purpose
Adds permissions for a group ACL entry to the given ACL.
Format
#include <dce\dce.h>
#include <dce\aclif.h>
void dce_acl_obj_add_group_entry(
sec_acl_t *acl,
sec_acl_permset_t permset,
uuid_t *group,
error_status_t *status);
Parameters
Input
acl A pointer to the ACL that is to be modified.
permset The permissions to be granted to the group.
group The UUID identifying the group.
Output
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns the following error:
sec_acl_cant_allocate_memory The requested
operation requires more memory than is
available.
Usage
The dce_acl_obj_add_group_entry routine adds a group ACL entry to the
given ACL. It is equivalent to calling the dce_acl_obj_add_id_entry
routine with the sec_acl_e_type_group entry type, but is more
convenient.
The data type that stores an ACL has a limited size. Attempting to
add too many entries generates a sec_acl_cant_allocate_memory error.
Related Information
Routines:
dce_acl_obj_add_id_entry
ΓòÉΓòÉΓòÉ 3.2.12. dce_acl_obj_add_id_entry ΓòÉΓòÉΓòÉ
Purpose
Adds permissions for an ACL entry to the given ACL.
Format
#include <dce\dce.h>
#include <dce\aclif.h>
void dce_acl_obj_add_id_entry(
sec_acl_t *acl,
sec_acl_entry_type_t entry_type,
sec_acl_permset_t permset,
uuid_t *id,
error_status_t *status);
Parameters
Input
acl A pointer to the ACL that is to be modified.
entry_type Must be one of the following types:
sec_acl_e_type_user
sec_acl_e_type_group
sec_acl_e_type_foreign_other
sec_acl_e_type_user_deleg
sec_acl_e_type_group_deleg
sec_acl_e_type_for_other_deleg
permset The permissions to be granted that give access to the
user, group, or foreign_other entry.
id The UUID identifying the user, group, or foreign_other
entry to be added.
Output
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns one of the following errors:
sec_acl_cant_allocate_memory The requested
operation requires more memory than is
available.
sec_acl_invalid_entry_type The type specified in
entry_type is not one of the six specified
types.
Usage
The dce_acl_obj_add_id_entry routine adds an ACL entry (user or
group, domestic or foreign) to the given ACL.
The data type that stores an ACL has a limited size. Attempting to
add too many entries generates a sec_acl_cant_allocate_memory error.
Related Information
Routines:
dce_acl_obj_add_group_entry
dce_acl_obj_add_user_entry
ΓòÉΓòÉΓòÉ 3.2.13. dce_acl_obj_add_obj_entry ΓòÉΓòÉΓòÉ
Purpose
Adds permissions for an object (obj) ACL entry to the given ACL.
Format
#include <dce\dce.h>
#include <dce\aclif.h>
void dce_acl_obj_add_obj_entry(
sec_acl_t *acl,
sec_acl_entry_type_t entry_type,
sec_acl_permset_t permset,
error_status_t *status);
Parameters
Input
acl A pointer to the ACL that is to be modified.
entry_type Must be one of these types:
sec_acl_e_type_unauthenticated
sec_acl_e_type_any_other
sec_acl_e_type_user_obj_deleg
sec_acl_e_type_group_obj_deleg
sec_acl_e_type_other_obj_deleg
sec_acl_e_type_any_other_deleg
permset The permissions to be granted.
Output
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns one of the following errors:
sec_acl_invalid_entry_type The type specified in
entry_type is not one of the six specified
types.
sec_acl_cant_allocate_memory The requested
operation requires more memory than is
available.
Usage
The dce_acl_obj_add_obj_entry routine adds an obj ACL entry to the
given ACL.
The data type that stores an ACL has a limited size. Attempting to
add too many entries generates a sec_acl_cant_allocate_memory error.
Related Information
Routines:
dce_acl_obj_add_any_other_entry
dce_acl_obj_add_unauth_entry
ΓòÉΓòÉΓòÉ 3.2.14. dce_acl_obj_add_unauth_entry ΓòÉΓòÉΓòÉ
Purpose
Adds permissions for an unauthenticated ACL entry to the given ACL.
Format
#include <dce\dce.h>
#include <dce\aclif.h>
void dce_acl_obj_add_unauth_entry(
sec_acl_t *acl,
sec_acl_permset_t permset,
error_status_t *status);
Parameters
Input
acl A pointer to the ACL that is to be modified.
permset The permissions to be granted for access to a
sec_acl_e_type_unauthenticated entry.
Output
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns sec_acl_cant_allocate_memory,
which indicates that the requested operation requires
more memory than is available.
Usage
The dce_acl_obj_add_unauth_entry routine adds an ACL entry for access
to a sec_acl_e_type_unauthenticated entry to the given ACL. It is
equivalent to calling the dce_acl_obj_add_obj_entry routine with the
sec_acl_e_type_unauthenticated entry type, but it is more convenient.
The data type that stores an ACL has a limited size. Attempting to
add too many entries generates a sec_acl_cant_allocate_memory error.
Related Information
Routines:
dce_acl_obj_add_obj_entry
ΓòÉΓòÉΓòÉ 3.2.15. dce_acl_obj_add_user_entry ΓòÉΓòÉΓòÉ
Purpose
Adds permissions for a user ACL entry to the given ACL.
Format
#include <dce\dce.h>
#include <dce\aclif.h>
void dce_acl_obj_add_user_entry(
sec_acl_t *acl,
sec_acl_permset_t permset,
uuid_t *user,
error_status_t *status);
Parameters
Input
acl A pointer to the ACL that is to be modified.
permset The permissions to be granted to the user.
user The UUID identifying the user to be added.
Output
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns sec_acl_cant_allocate_memory,
which indicates that the requested operation requires
more memory than is available.
Usage
The dce_acl_obj_add_user_entry routine adds a user ACL entry to the
given ACL. It is equivalent to calling the dce_acl_obj_add_id_entry
routine with the sec_acl_e_type_user entry type, but it is more
convenient.
The data type that stores an ACL has a limited size. Attempting to
add too many entries generates a sec_acl_cant_allocate_memory error.
Related Information
Routines:
dce_acl_obj_add_id_entry
ΓòÉΓòÉΓòÉ 3.2.16. dce_acl_obj_free_entries ΓòÉΓòÉΓòÉ
Purpose
Frees space used by an ACL's entries.
Format
#include <dce\dce.h>
#include <dce\aclif.h>
void dce_acl_obj_free_entries(
sec_acl_t *acl,
error_status_t *status);
Parameters
Input
acl A pointer to the ACL that is to be freed.
Output
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns an error.
Usage
The dce_acl_obj_free_entries routine frees space used by an ACL's
entries, and then sets the pointer to the ACL entry array to NULL and
the entry count to 0 (zero).
Related Information
Routines:
dce_acl_obj_init
ΓòÉΓòÉΓòÉ 3.2.17. dce_acl_obj_init ΓòÉΓòÉΓòÉ
Purpose
Initializes an ACL.
Format
#include <dce\dce.h>
#include <dce\aclif.h>
void dce_acl_obj_init(
uuid_t *mgr_type,
sec_acl_t *acl,
error_status_t *status);
Parameters
Input
mgr_type A pointer to the UUID identifying the type of the ACL
manager in question. There can be more than one type of
ACL manager protecting the object whose ACL is bound to
the input handle. Use this parameter to distinguish
them.
acl A pointer to the ACL that is to be created.
Output
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns an error.
Usage
The dce_acl_obj_init routine initializes an ACL. The caller passes in
the pointer to the existing ACL structure (of type sec_acl_t), for
which the caller provides the space.
Examples
The following example shows the use of dce_acl_obj_init and the
corresponding routine to free the entries, dce_acl_obj_free_entries.
sec_acl_t acl;
extern uuid_t my_mgr_type;
error_status_t status;
dce_acl_obj_init(&my_mgr_type, &acl, &status);
/* ... use the ACL ... */
dce_acl_obj_free_entries(&acl, &status);
Related Information
Routines:
dce_acl_obj_free_entries
ΓòÉΓòÉΓòÉ 3.2.18. dce_acl_register_object_type ΓòÉΓòÉΓòÉ
Purpose
Registers an ACL manager's object type.
Format
#include <dce\dce.h>
#include <dce\aclif.h>
void dce_acl_register_object_type(
dce_db_handle_t db,
uuid_t *mgr_type,
unsigned32 printstring_size,
sec_acl_printstring_t *printstring,
sec_acl_printstring_t *mgr_info,
sec_acl_permset_t control_perm,
sec_acl_permset_t test_perm,
dce_acl_resolve_func_t resolver,
void *resolver_arg,
unsigned32 flags,
error_status_t *status);
Parameters
Input
db Specifies the handle to the backing store database
where the ACL objects are stored. The backing store
must be indexed by UUID and must not use backing store
headers. The database is obtained through dce_db_open,
which is called prior to this routine.
mgr_type A pointer to the UUID identifying the type of the ACL
manager in question. There can be more than one type of
ACL manager protecting the object whose ACL is bound to
the input handle. Use this parameter to distinguish
them.
printstring_size The number of items in the printstring array.
printstring An array of sec_acl_printstring_t structures containing
the printable representation of each specified
permission. These are the print strings used by dcecp
or other ACL editors.
mgr_info A single sec_acl_printstring_t containing the name and
short description for the given ACL manager.
control_perm The permission set needed to change an ACL, typically
sec_acl_perm_control. If the value is 0, anyone is
allowed to change the ACL. The permission must be
listed in printstring.
test_perm The permission set needed to test an ACL, typically
sec_acl_perm_test. If the value is 0, anyone is allowed
to test the ACL. The permissions must be listed in
printstring.
resolver The routine for finding the UUID for an ACL.
resolver_arg The parameter to pass to the resolver routine. If using
dce_acl_resolve_by_name or dce_acl_resolve_by_uuid,
pass the database handle to the name or UUID backing
store database. The backing store must use the standard
backing store header. See dce_db_open.
flags A bit mask with the following possible bit values:
dce_acl_c_orphans_ok If this bit is specified, it
is possible to replace an ACL with one in
which no control bits are turned on in any of
the ACL entries. (Use the rdacl_replace
operation to replace an ACL.) This is a
write-once operation and, after it has been
done, no one can change the ACL.
dce_acl_c_has_owner If this bit is set, the ACL
manager supports the concept of user owners
of objects. This is required to use ACL
entries of type user_obj and user_obj_deleg.
dce_acl_c_has_groups A similar bit for group
owners of objects.
Output
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns one of the following errors:
acl_s_owner_not_allowed In a rdacl_replace
operation an attempt was made to add an ACL
entry of type sec_acl_e_type_user_obj or
sec_acl_e_type_user_obj_deleg to a manager
that does not support object user ownership.
acl_s_group_not_allowed In a rdacl_replace
operation an attempt was made to add an ACL
entry of type sec_acl_e_type_group_obj or
sec_acl_e_type_group_obj_deleg to a manager
that does not support object group ownership.
acl_s_no_control_entries In a rdacl_replace
operation an attempt was made to replace the
ACL where no entries have control permission.
Usage
The dce_acl_register_object_type routine registers the object types
of an ACL manager with the ACL library.
The resolver routine may be the dce_acl_resolve_by_name or the
dce_acl_resolve_by_uuid routine if the application uses the standard
header in the backing store database, or it may be some other
user-supplied routine. A user-supplied routine must be of type
dce_acl_resolve_func_t. The resolver routine finds the UUID of the
ACL of the given object. The resolver's parameters must match the
type dce_db_convert_func_t defined in the file <dce\aclif.h>. See the
following examples for use of the resolver routine
dce_acl_convert_func.
Unless the dce_acl_c_orphans_ok bit is set in the flags parameter,
all ACLs must always have someone able to modify the ACL.
Another way to express this is that if dce_acl_c_orphans_ok is
cleared in a call to dce_acl_register_object_type where a
control_perm value is specified, a subsequent ACL replacement using
an ACL that has no control bits set in any non-delegation entry will
fail, resulting in the acl_s_no_control_entries error. If
dce_acl_c_orphans_ok is set, but no control_perm bits are specified,
then dce_acl_c_orphans_ok is ignored, and the replacement works in
all cases.
Examples
The dce_acl_register_object_type routine should be called once for
each type of object that the server manages. A typical call follows.
The sample code defines three variables: the manager print string,
the ACL print strings, and the ACL database. Note that the manager
print string does not define any permission bits; they are set by the
library to be the union of all permissions in the ACL print string.
The code also uses the global my_uuid as the ACL manager type UUID.
The ACL print string uses the standard sec_acl_perm_xxx bits.
include <dce\aclif.h>
/* Manager help. */
sec_acl_printstring_t my_acl_help = {
"me", "My manager"
};
/*
* ACL permission descriptions; these are from /usr/include/dce/aclbase.idl
* This example refrains from redefining any of the conventionally
* established bits.
*/
sec_acl_printstring_t my_printstring[] = {
{ "r", "read", sec_acl_perm_read },
{ "f", "foobar", sec_acl_perm_unused_00000080 },
{ "w", "write", sec_acl_perm_write },
{ "d", "delete, sec_acl_perm_delete },
{ "c", "control", sec_acl_perm_control }
};
dce_db_open("my_acldb", NULL,
dce_db_c_std_header | dce_db_c_index_by_uuid,
(dce_db_convert_func_t)dce_acl_convert_func,
&dbh, &st);
dce_acl_register_object_type(dbh, &my_manager_uuid,
sizeof my_printstring / sizeof my_printstring[0],
my_printstring, &my_acl_help, sec_acl_perm_control,
0, xxx_resolve_func, NULL, 0, &st);
If the ACL manager can use the standard collection of ACL bits (that
is, has not defined any special ones), then it can use the global
variable dce_acl_g_printstring that predefines a print string. Here
is an example of its use:
dce_acl_register_object_type(acl_db, &your_mgr_type,
sizeof dce_acl_g_printstring / sizeof dce_acl_g_printstring[0],
dce_acl_g_printstring, &your_acl_help,
dced_perm_control, dced_perm_test, your_resolver, NULL, 0, st);
Related Information
Routines:
dce_db_open
dce_acl_resolve_by_name
dce_acl_resolve_by_uuid
Files:
\usr\include\dce\aclif.h - Definition of dce_acl_resolve_func_t.
ΓòÉΓòÉΓòÉ 3.2.19. dce_acl_resolve_by_name ΓòÉΓòÉΓòÉ
Purpose
Finds the UUID for an ACL, given an object name.
Format
#include <dce\dce.h>
#include <dce\aclif.h>
void dce_acl_resolve_by_name(
handle_t handle,
sec_acl_component_name_t component_name,
sec_acl_type_t sec_acl_type,
uuid_t *mgr_type,
boolean32 writing,
void *resolver_arg,
uuid_t *acl_uuid,
error_status_t *status);
Parameters
Input
handle A client binding handle passed into the server stub.
Use sec_acl_bind to create this handle.
component_name A character string containing the name of the target
object.
sec_acl_type The type of ACL to be resolved: sec_acl_type_object,
sec_acl_type_default_object, or
sec_acl_type_default_container.
mgr_type A pointer to the UUID identifying the type of the ACL
manager in question. There can be more than one type of
ACL manager protecting the object whose ACL is bound to
the input handle. Use this parameter to distinguish
them.
writing This parameter is ignored in the OSF implementation.
resolver_arg This argument is passed into
dce_acl_register_object_type. It should be a handle for
a backing store indexed by name.
Output
acl_uuid The ACL UUID, as resolved by dce_acl_resolve_by_name.
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns an error.
Usage
The dce_acl_resolve_by_name routine finds a UUID for an ACL, given an
object's name, as provided in the component_name parameter. The user
does not call this routine directly. It is an instance of the kind of
routine provided to the resolver argument of
dce_acl_register_object_type.
If dce_acl_resolve_by_name and dce_acl_resolve_by_uuid are
inappropriate, the user of dce_acl_register_object_type must provide
some other resolver routine.
Related Information
Routines: dce_db_header_fetch
dce_db_open
dce_acl_register_object_type
dce_acl_resolve_by_uuid
ΓòÉΓòÉΓòÉ 3.2.20. dce_acl_resolve_by_uuid ΓòÉΓòÉΓòÉ
Purpose
Finds the UUID for an ACL, given an object's UUID.
Format
#include <dce\dce.h>
#include <dce\aclif.h>
dce_acl_resolve_func_t dce_acl_resolve_by_uuid(
handle_t handle,
sec_acl_component_name_t component_name,
sec_acl_type_t sec_acl_type,
uuid_t *mgr_type,
boolean32 writing,
void *resolver_arg,
uuid_t *acl_uuid,
error_status_t *status);
Parameters
Input
handle A client binding handle passed into the server stub.
Use sec_acl_bind to create this handle.
component_name A character string containing the name of the target
object. (The dce_acl_resolve_by_uuid routine ignores
this parameter.)
sec_acl_type The type of ACL to be resolved: sec_acl_type_object,
sec_acl_type_default_object, or
sec_acl_type_default_container.
mgr_type A pointer to the UUID identifying the type of the ACL
manager in question. There might be more than one type
of ACL manager protecting the object whose ACL is bound
to the input handle. Use this parameter to distinguish
them.
writing This parameter is ignored in OSF's implementation.
resolver_arg This argument is passed into
dce_acl_register_object_type. It should be a handle for
a backing store indexed by UUID.
Output
acl_uuid The ACL UUID, as resolved by dce_acl_resolve_by_uuid.
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns an error.
Usage
The dce_acl_resolve_by_uuid routine finds a UUID for an ACL, given an
object's UUID, as provided through the handle parameter. The user
does not call this routine directly. It is an instance of the kind of
routine provided to the resolver argument of
dce_acl_register_object_type.
If dce_acl_resolve_by_uuid and dce_acl_resolve_by_name are
inappropriate, the user of dce_acl_register_object_type must provide
some other resolver routine.
Related Information
Routines: dce_db_header_fetch
dce_db_open
dce_acl_register_object_type
dce_acl_resolve_by_name
ΓòÉΓòÉΓòÉ 3.3. The DCE Attribute Interface API ΓòÉΓòÉΓòÉ
The DCE Attribute Interface API allows applications to define and access
attributes types (schema entries) in a schema of your choice. It is based on
the Extended Registry Attribute (ERA) interface, which defines and accesses
attribute types in the registry database schema. Except for the binding
methods, the two APIs are similar.
Note however, that the ERA API provides routines to create attribute types in
the registry schema, to create and manipulate attribute instances, and to
attach those instances to objects. The DCE Attribute Interface in its current
state provides routines to create attribute types only.
See the following topics for more information:
The DCE Attribute Interface Routines
Attribute Interface Data Types and Structures
ΓòÉΓòÉΓòÉ 3.3.1. The DCE Attribute Interface Routines ΓòÉΓòÉΓòÉ
The DCE Attribute Interface consists of the following routines:
dce_attr_sch_aclmgr_strings Returns printable ACL strings associated
with an ACL manager protecting a schema
object.
dce_attr_sch_bind Returns an opaque handle of type
dce_attr_sch_handle_t to a schema object
specified by name and sets authentication
and authorization parameters for the
handle.
dce_attr_sch_bind_free Releases an opaque handle of type
dce_attr_sch_handle_t.
dce_attr_sch_create_entry Creates a schema entry in a schema bound to
with dce_attr_sch_bind.
dce_attr_sch_cursor_alloc Allocates resources to a cursor used with
dce_attr_sch_scan. The
dce_attr_sch_cursor_alloc routine is a
local operation.
dce_attr_sch_cursor_init Allocates resources to and initializes a
cursor used with dce_attr_sch_scan. The
dce_attr_sch_cursor_init routine makes a
remote call that also returns the current
number of schema entries in the schema.
dce_attr_sch_cursor_release Releases states associated with a cursor
created by dce_attr_sch_cursor_alloc or
dce_attr_sch_cursor_init.
dce_attr_sch_cursor_reset Reinitializes a cursor used with
dce_attr_sch_scan. The reset cursor can
then be reused without releasing and
re-allocating.
dce_attr_sch_delete_entry Deletes a schema entry in a schema bound to
with dce_attr_sch_bind.
dce_attr_sch_get_acl_mgrs Retrieves the manager types of the ACLs
protecting objects dominated by a named
schema.
dce_attr_sch_lookup_by_id Reads a schema entry identified by
attribute type UUID.
dce_attr_sch_lookup_by_name Reads a schema entry identified by
attribute name.
dce_attr_sch_scan Reads a specified number of schema entries.
dce_attr_sch_update_entry Updates a schema entry in a schema bound to
with dce_attr_sch_bind.
ΓòÉΓòÉΓòÉ 3.3.2. Attribute Interface Data Types and Structures ΓòÉΓòÉΓòÉ
dce_attr_sch_handle_t An opaque handle to a schema object. Use
dce_attr_sch_bind to acquire the handle.
dce_attr_component_name_t A pointer to a character string used to
further specify a schema object.
dce_bind_auth_info_t An enumeration that defines whether the
binding is authenticated. This data type is
defined exactly as the
sec_attr_bind_auth_info_t data type in the
ERA interface. See DCE Security Services
API for more information on
sec_attr_bind_auth_info_t.
dce_attr_schema_entry_t A structure that defines a complete
attribute entry for the schema catalog.
This data type is defined exactly as the
sec_attr_schema_entry_t data type in the
ERA interface. See DCE Security Services
API for more information on
sec_attr_schema_entry_t.
dce_attr_cursor_t A structure that provides a pointer into a
database and is used for multiple database
operations. This cursor must minimally
represent the object indicated by
dce_attr_sch_handle_t. The cursor can
additionally represent an entry within that
schema.
dce_attr_schema_entry_parts_t A 32-bit bitset containing flags that
specify the schema entry fields that can be
modified on a schema entry update
operation. This data type is defined
exactly as the
sec_attr_schema_entry_parts_t data type in
the ERA interface. See DCE Security
Services API for more information on
sec_attr_schema_entry_parts_t.
ΓòÉΓòÉΓòÉ 3.3.3. dce_attr_sch_aclmgr_strings ΓòÉΓòÉΓòÉ
Purpose
Retrieves printable ACL strings for each permission bit that the
acl_mgr_type will support.
Format
#include <dce\dce_attr_sch.h>
void dce_attr_sch_aclmgr_strings(
dce_attr_sch_handle_t *h,
uuid_t *acl_mgr_type,
unsigned32 size_avail,
uuid_t *acl_mgr_type_chain,
sec_acl_print_string_t *acl_mgr_info,
boolean32 *tokenize,
unsigned32 *total_num_printstrings,
unsigned32 *size_used,
sec_acl_printstring_t permstrings[],
error_status_t *status);
Parameters
Input
h An opaque handle to the schema on which this operation
is being performed.
acl_mgr_type The UUID of the acl_mgr_type for which the printstrings
are to be returned.
size_avail The size of the permstrings array.
Output
acl_mgr_type_chain If not uuid_nil, identifies the next acl_mgr_type
UUID in a chain supporting ACL managers with more than
32 permission bits.
acl_mgr_info Printstrings containing the name, help information, and
complete set of supported permission bits for this ACL
manager.
tokenize If TRUE, permission bit strings should be tokenized. If
FALSE, permission print strings are unambiguous and
print strings for various permissions can be
concatenated.
total_num_permstrings The total number of permission print strings
supported by this acl_mgr_type.
size_used The number of perm print strings returned.
permstrings[] An array containing the print strings for each
permission supported by this acl_mgr_type.
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns dce_attr_s_not_implemented.
Usage
The dce_attr_sch_aclmgr_strings routine retrieves printable
representations for each permission bit that the input acl_mgr_type
will support. There can be aliases for common permission
combinations; by convention, simple entries should appear at the
beginning of the array, and combinations should appear at the end.
When FALSE, the tokenize flag indicates that permission print strings
are unambiguous and therefore can be concatenated for various
permissions. When TRUE, however, this property does not hold and the
strings should be tokenized before input or output.
The acl_mgr_info string provides a name and help information for the
manager type as well as the complete set of supported permission
bits. The total_num_printstrings parameter contains the total number
of ACL print strings supported by this ACL manager type. If
total_num_printstrings is greater than size_avail, this routine
should be invoked again with a buffer of the appropriate size.
If acl_mgr_type supports more than 32 permission bits, multiple
manager types can be used, one for each 32-bit-wide slice of
permissions. When this is the case the acl_mgr_type_chain parameter
is set to the UUID of the next manager type in the set. The final
result for the chain returns uuid_nil in the manager_type_chain
parameter.
Related Information
Files:
\usr\include\dce\dce_attr_sch.idl - The idl file from which
dce\dce_attr_sch.h was derived.
ΓòÉΓòÉΓòÉ 3.3.4. dce_attr_sch_bind ΓòÉΓòÉΓòÉ
Purpose
Returns an opaque handle to a schema object.
Format
#include <dce\dce_attr_base.h>
void dce_attr_sch_bind(
dce_attr_component_name_t schema_name,
dce_bind_auth_info_t *auth_info,
dce_attr_sch_handle_t *h,
error_status_t *status);
Parameters
Input
schema_name A pointer to a value of type dce_attr_component_name_t
that specifies the name of the schema object to which
to bind.
auth_info A value of type dce_bind_auth_info_t that defines the
authentication and authorization parameters to use with
the binding handle. If set to NULL, the default
authentication and authorization parameters are used.
Output
h An opaque handle of type dce_attr_sch_handle_t to the
named schema object for use with dce_attr_sch
operations.
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns one of the following errors:
dce_attr_s_bad_name
sec_login_s_no_current_context
rpc_s_entry_not_found
rpc_s_no_more_bindings
dce_attr_s_unknown_auth_info_type
dce_attr_s_no_memory
Usage
The dce_attr_sch_bind routine returns an opaque handle of type
dce_attr_sch_handle_t to a named schema object. The returned handle
can then be used for subsequent dce_attr_sch operations performed on
the object.
Permissions Required
The dce_attr_sch_bind routine requires appropriate permissions on the
schema object. These permissions are managed by the target server.
Related Information
Routines:
dce_attr_sch_bind_free
Files:
\usr\include\dce\dce_attr_base.idl - The idl file from which
dce\dce_attr_base.h was derived.
ΓòÉΓòÉΓòÉ 3.3.5. dce_attr_sch_bind_free ΓòÉΓòÉΓòÉ
Purpose
Releases an opaque handle of type dce_attr_sch_handle_t to a schema
object.
Format
#include <dce\dce_attr_base.h>
void dce_attr_sch_bind_free(
dce_attr_sch_handle_t *h,
error_status_t *status);
Parameters
Input
h An opaque handle of type dce_attr_sch_handle_t.
Output
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns an error.
Usage
The dce_attr_sch_bind_free routine releases an opaque handle of type
dce_attr_sch_handle_t. The handle was returned with the
dce_attr_sch_bind routine and used to perform dce_attr_sch
operations.
Permissions Required
The dce_attr_sch_bind_free routine requires appropriate permissions
on the schema object. These permissions are managed by the target
server.
Related Information
Routines:
dce_attr_sch_bind
Files:
\usr\include\dce\dce_attr_sch.idl - The idl file from which
dce\dce_attr_sch.h was derived.
ΓòÉΓòÉΓòÉ 3.3.6. dce_attr_sch_create_entry ΓòÉΓòÉΓòÉ
Purpose
Creates a schema entry in a schema bound to by a previous
dce_attr_sch_bind routine.
Format
#include <dce\dce_attr_base.h>
void dce_attr_sch_create_entry(
dce_attr_sch_handle_t h,
dce_attr_schema_entry_t *schema_entry,
error_status_t *status);
Parameters
Input
h An opaque handle bound to a schema object. Use
dce_attr_sch_bind to acquire the handle.
schema_entry A pointer to a dce_attr_schema_entry_t that contains
the schema entry values for the schema where the entry
is to be created.
Output
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns dce_attr_s_bad_binding.
Usage
The dce_attr_sch_create_entry routine creates schema entries that
define attribute types in the schema object bound to by h.
Permissions Required
The dce_attr_sch_create_entry routine requires appropriate
permissions on the schema object. These permissions are managed by
the target server.
Related Information
Routines:
dce_attr_sch_delete_entry
dce_attr_sch_update_entry
Files:
\usr\include\dce\dce_attr_base.idl - The idl file from which
dce\dce_attr_base.h was derived.
ΓòÉΓòÉΓòÉ 3.3.7. dce_attr_sch_cursor_alloc ΓòÉΓòÉΓòÉ
Purpose
Allocates resources to a cursor used with the dce_attr_sch_scan
routine.
Format
#include <dce\dce_attr_sch.h>
void dce_rgy_attr_cursor_alloc(
dce_attr_cursor_t *cursor,
error_status_t *status);
Parameters
Output
cursor A pointer to a dce_attr_cursor_t.
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns dce_attr_s_no_memory.
Usage
The dce_attr_sch_cursor_alloc routine allocates resources to a cursor
used with the dce_attr_sch_scan routine. This routine, which is a
local operation, does not initialize cursor.
The dce_attr_sch_cursor_init routine, which makes a remote call,
allocates and initializes the cursor. In addition,
dce_attr_sch_cursor_init returns the total number of entries found in
the schema as an output parameter; dce_attr_sch_cursor_alloc does
not.
Permissions Required
The dce_attr_sch_cursor_alloc routine requires appropriate
permissions on the schema object. These permissions are managed by
the target server.
Related Information
Routines:
dce_attr_sch_cursor_init
dce_attr_sch_cursor_release
dce_attr_sch_scan
Files:
\usr\include\dce\dce_attr_base.idl - The idl file from which
dce\dce_attr_base.h was derived.
ΓòÉΓòÉΓòÉ 3.3.8. dce_attr_sch_cursor_init ΓòÉΓòÉΓòÉ
Purpose
Initializes and allocates a cursor used with the dce_attr_sch_scan
routine.
Format
#include <dce\dce_attr_base.h>
void dce_rgy_attr_cursor_init(
dce_attr_sch_handle_t h,
unsigned32 *cur_num_entries,
dce_attr_cursor_t *cursor,
error_status_t *status);
Parameters
Input
h An opaque handle bound to a schema object. Use
dce_attr_sch_bind to acquire the handle.
Output
cur_num_entries A pointer to an unsigned 32-bit integer that
specifies the total number of entries contained in the
schema at the time of this call.
cursor A pointer to a dce_attr_cursor_t that is initialized to
the first entry in the schema.
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns one of the following errors:
dce_attr_s_bad_binding
dce_attr_s_no_memory
Usage
The dce_attr_sch_cursor_init routine initializes and allocates a
cursor used with the dce_attr_sch_scan routine. This routine makes
remote calls to initialize the cursor. To limit the number of remote
calls, use the dce_attr_sch_cursor_alloc routine to allocate cursor,
but not initialize it. If the cursor input to dce_attr_sch_scan has
not been initialized, the dce_attr_sch_scan routine initializes it;
if it has been initialized, dce_attr_sch_scan advances it.
Unlike the dce_attr_sch_cursor_alloc routine,
dce_attr_sch_cursor_init supplies the total number of entries found
in the schema as an output parameter.
Related Information
Routines:
dce_attr_sch_cursor_release
dce_attr_sch_scan
dce_attr_sch_cursor_alloc
Files:
\usr\include\dce\dce_attr_base.idl - The idl file from which
dce\dce_attr_base.h was derived.
ΓòÉΓòÉΓòÉ 3.3.9. dce_attr_sch_cursor_release ΓòÉΓòÉΓòÉ
Purpose
Releases states associated with a cursor that has been allocated with
either dce_attr_sch_cursor_init or dce_attr_sch_cursor_alloc.
Format
#include <dce\dce_attr_base.h>
void dce_attr_sch_cursor_init(
dce_attr_cursor_t *cursor,
error_status_t *status);
Parameters
Input\Output
cursor A pointer to a dce_attr_cursor_t. As an input
parameter, cursor must have been initialized to the
first entry in a schema. As an output parameter,
cursor is uninitialized with all resources released.
Output
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns an error.
Usage
The dce_attr_sch_cursor_init routine releases the resources allocated
to a cursor that has been allocated by either a
dce_attr_sch_cursor_init or dce_attr_sch_cursor_alloc. This routine
is a local operation and makes no remote calls.
Related Information
Routines:
dce_attr_sch_cursor_alloc
dce_attr_sch_cursor_init
dce_attr_sch_cursor_reset
dce_attr_sch_scan
Files:
\usr\include\dce\dce_attr_base.idl - The idl file from which
dce\dce_attr_base.h was derived.
ΓòÉΓòÉΓòÉ 3.3.10. dce_attr_sch_cursor_reset ΓòÉΓòÉΓòÉ
Purpose
Resets a cursor that has been allocated with either
dce_attr_sch_cursor_init or dce_attr_sch_cursor_alloc.
Format
#include <dce\dce_attr_base.h>
void dce_attr_cursor_reset(
dce_attr_cursor_t *cursor,
error_status_t *status);
Parameters
Input\Output
cursor A pointer to a dce_attr_cursor_t. As an input
parameter, cursor is an initialized cursor. As an
output parameter, cursor is reset to the first
attribute in the schema.
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns an error.
Usage
The dce_attr_sch_cursor_reset routine resets a dce_attr_cursor_t that
has been allocated by either dce_attr_sch_cursor_init or
dce_attr_sch_cursor_alloc. The reset cursor can then be used to
process a new dce_attr_sch_scan query by reusing the cursor instead
of releasing and re-allocating it. This is a local operation and
makes no remote calls.
Related Information
Routines:
dce_attr_sch_cursor_alloc
dce_attr_sch_cursor_init
dce_attr_sch_scan
Files:
\usr\include\dce\dce_attr_sch.idl - The idl file from which
dce\dce_attr_sch.h was derived.
ΓòÉΓòÉΓòÉ 3.3.11. dce_attr_sch_delete_entry ΓòÉΓòÉΓòÉ
Purpose
Deletes a schema entry.
Format
#include <dce\dce_attr_sch.h>
void dce_attr_sch_delete_entry(
dce_attr_sch_handle_t h,
uuid_t *attr_id,
error_status_t *status);
Parameters
Input
h An opaque handle bound to a schema object. Use
dce_attr_sch_bind to acquire the handle.
attr_id A pointer to a uuid_t that identifies the schema entry
to be deleted in the schema bound to by h.
Output
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns dce_attr_s_bad_binding.
Usage
The dce_attr_sch_delete_entry routine deletes a schema entry. Because
this is a radical operation that invalidates any existing attributes
of this type on objects dominated by the schema, access to this
operation should be severely limited.
Permissions Required
The dce_attr_sch_delete_entry routine requires appropriate
permissions on the schema object. These permissions are managed by
the target server.
Related Information
Routines:
dce_attr_sch_bind
dce_attr_sch_create_entry
dce_attr_sch_update_entry
Files:
\usr\include\dce\dce_attr_base.idl - The idl file from which
dce\dce_attr_base.h was derived.
ΓòÉΓòÉΓòÉ 3.3.12. dce_attr_sch_get_acl_mgrs ΓòÉΓòÉΓòÉ
Purpose
Retrieves the manager types of the ACLs protecting the objects
dominated by a named schema.
Format
#include <dce\dce_attr_base.h>
void dce_attr_sch_get_acl_mgrs(
dce_attr_sch_handle_t h,
unsigned32 size_avail,
unsigned32 *size_used,
unsigned32 *num_acl_mgr_types,
uuid_t acl_mgr_types[],
error_status_t *status);
Parameters
Input
h An opaque handle bound to a schema object. Use
dce_attr_sch_bind to acquire the handle.
size_avail An unsigned 32-bit integer containing the allocated
length of the acl_manager_types array.
Output
size_used An unsigned 32-bit integer containing the number of
output entries returned in the acl_mgr_types array.
num_acl_mgr_types An unsigned 32-bit integer containing the number of
types returned in the acl_mgr_types array. This might
be greater than size_used if there was not enough space
allocated by size_avail for all the manager types in
the acl_manager_types array.
acl_mgr_types An array of the length specified in size_avail to
contain UUIDs (of type uuid_t) identifying the types of
ACL managers protecting the target object.
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns dce_attr_s_not_implemented.
Usage
The dce_attr_sch_get_acl_mgrs routine returns a list of the manager
types protecting the schema object identified by h.
ACL editors and browsers can use this operation to determine the ACL
manager types protecting a selected schema object. Then, using the
dce_attr_sch_aclmgr_strings routine, they can determine how to format
for display the permissions supported by that ACL manager type.
Permissions Required
The dce_attr_sch_get_acl_mgrs routine requires appropriate
permissions on the schema object for which the ACL manager types are
to be returned. These permissions are managed by the target server.
Related Information
Routines:
dce_attr_sch_bind
Files:
\usr\include\dce\dce_attr_base.idl - The idl file from which
dce\dce_attr_base.h was derived.
ΓòÉΓòÉΓòÉ 3.3.13. dce_attr_sch_lookup_by_id ΓòÉΓòÉΓòÉ
Purpose
Reads a schema entry identified by UUID.
Format
#include <dce\dce_attr_base.h>
void dce_attr_sch_lookup_by_id(
dce_attr_sch_handle_t h,
uuid_t *attr_id,
dce_attr_schema_entry_t *schema_entry,
error_status_t *status);
Parameters
Input
h An opaque handle bound to a schema object. Use
dce_attr_sch_bind to acquire the handle.
attr_id A pointer to a uuid_t that identifies a schema entry.
Output
schema_entry A dce_attr_schema_entry_t that contains an entry
identified by attr_id.
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns dce_attr_s_bad_binding.
Usage
The dce_attr_sch_lookup_by_id routine reads a schema entry identified
by attr_id. This routine is useful for access by applications.
Permissions Required
The dce_attr_sch_lookup_by_id routine requires appropriate
permissions on the schema object. These permissions are managed by
the target server.
Related Information
Routines:
dce_attr_sch_bind
dce_attr_sch_lookup_by_name
dce_attr_sch_scan
Files:
\usr\include\dce\dce_attr_base.idl - The idl file from which
dce\dce_attr_base.h was derived.
ΓòÉΓòÉΓòÉ 3.3.14. dce_attr_sch_lookup_by_name ΓòÉΓòÉΓòÉ
Purpose
Reads a schema entry identified by name.
Format
#include <dce\dce_attr_base.h>
void dce_attr_sch_lookup_by_name(
dce_attr_sch_handle_t h,
char *attr_name,
dce_attr_schema_entry_t *schema_entry,
error_status_t *status);
Parameters
Input
h An opaque handle bound to a schema object. Use
dce_attr_sch_bind to acquire the handle.
attr_name A pointer to a character string that identifies the
schema entry.
Output
schema_entry A dce_attr_schema_entry_t that contains the schema
entry identified by attr_name.
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns dce_attr_s_bad_binding.
Usage
The dce_attr_sch_lookup_by_name routine reads a schema entry
identified by name. This routine is useful with an interactive
editor.
Permissions Required
The dce_attr_sch_lookup_by_name routine requires appropriate
permissions on the schema object. These permissions are managed by
the target server.
Related Information
Routines:
dce_attr_sch_bind
dce_attr_sch_lookup_by_id
dce_attr_sch_scan
Files:
\usr\include\dce\dce_attr_base.idl - The idl file from which
dce\dce_attr_base.h was derived.
ΓòÉΓòÉΓòÉ 3.3.15. dce_attr_sch_scan ΓòÉΓòÉΓòÉ
Purpose
Reads a specified number of schema entries.
Format
#include <dce\dce_attr_base.h>
void dce_attr_sch_scan(
dce_attr_sch_handle_t h,
dce_attr_cursor_t *cursor,
unsigned32 num_to_read,
unsigned32 *num_read,
dce_attr_schema_entry_t schema_entries[ ],
error_status_t *status);
Parameters
Input
h An opaque handle bound to a schema object. Use
dce_attr_sch_bind to acquire the handle.
num_to_read An unsigned 32-bit integer specifying the size of the
schema_entries[] array and the maximum number of
entries to be returned.
Input\Output
cursor A pointer to a dce_attr_cursor_t. As input, cursor must
be allocated and can be initialized. If cursor is not
initialized, dce_attr_sch_scan initializes it. As
output, cursor is positioned at the first schema entry
after the returned entries.
Output
num_read A pointer to an unsigned 32-bit integer specifying the
number of entries returned in schema_entries[].
schema_entries[] A dce_attr_schema_entry_t that contains an array of
the returned schema entries.
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns one of the following errors:
o dce_attr_s_bad_binding
o edce_attr_s_bad_cursor
Usage
The dce_attr_sch_scan routine reads schema entries. The read begins
at the entry where the input cursor is positioned and ends after the
number of entries specified in num_to_read.
The input cursor must have been allocated by either the
dce_attr_sch_cursor_init or the dce_attr_sch_cursor_alloc routine. If
the input cursor is not initialized, dce_attr_sch_scan initializes
it. If cursor is initialized, dce_attr_sch_scan advances it.
To read all entries in a schema, make successive dce_attr_sch_scan
calls. When all entries have been read, the call returns the message
no_more_entries.
This routine is useful as a browser.
Permissions Required
The dce_attr_sch_scan routine requires appropriate permissions on the
schema object. These permissions are managed by the target server.
Related Information
Routines:
dce_attr_sch_bind
dce_attr_sch_cursor_init
dce_attr_sch_cursor_alloc
dce_attr_sch_cursor_release
Files:
\usr\include\dce\dce_attr_base.idl - The idl file from which
dce\dce_attr_base.h was derived.
ΓòÉΓòÉΓòÉ 3.3.16. dce_attr_sch_update_entry ΓòÉΓòÉΓòÉ
Purpose
Updates a schema entry.
Format
#include <dce\dce_attr_sch.h>
void dce_attr_sch_update_entry(
dce_attr_sch_handle_t h,
dce_attr_schema_entry_parts_t modify_parts,
dce_attr_schema_entry_t *schema_entry,
error_status_t *status);
Parameters
Input
h An opaque handle bound to a schema object. Use
dce_attr_sch_bind to acquire the handle.
modify_parts A value of type dce_attr_schema_entry_parts_t that
identifies the fields in the schema bound to by h that
can be modified.
schema_entry A pointer to a dce_attr_schema_entry_t that contains
the schema entry values for the schema entry to be
updated.
Output
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns dce_attr_s_bad_binding.
Usage
The dce_attr_sch_update_entry routine modifies schema entries. Only
those schema entry fields set to be modified in the
dce_attr_schema_entry_parts_t data type can be modified.
Some schema entry components can never be modified. Instead, to make
any changes to these components, the schema entry must be deleted
(which deletes all attribute instances of that type) and re-created.
These components are:
o Attribute name
o Reserved flag
o Apply defaults flag
o Intercell action flag
o Trigger binding
o Comment
Fields that are arrays of structures (such as acl_mgr_set and
trig_binding) are completely replaced by the new input array. This
operation cannot be used to add a new element to the existing array.
Permissions Required
The dce_attr_sch_update_entry routine requires appropriate
permissions on the schema object. These permissions are managed by
the target server.
Related Information
Routines:
dce_attr_sch_create_entry
dce_attr_sch_delete_entry
Files:
\usr\include\dce\dce_attr_base.idl - The idl file from which
dce\dce_attr_base.h was derived.
ΓòÉΓòÉΓòÉ 3.4. DCE Audit API ΓòÉΓòÉΓòÉ
The DCE Audit Application Program Interface (API) allows applications to
perform auditing and to analyze audit trails. The following give general
information about the DCE Audit API and an overview of the parts of the DCE
Audit API:
o Audit API Routines
o Audit Data Types
o Environment Variables
o Permissions Required
o Related Information
ΓòÉΓòÉΓòÉ 3.4.1. Audit API Routines ΓòÉΓòÉΓòÉ
The following is an alphabetical list of the Audit API routines and their
descriptions. The types of application programs that are most likely to call
the routines are enclosed in parentheses.
dce_aud_clean Resets and rewinds the specified the audit trail (audit
trail analysis and examination tools).
dce_aud_close Closes an audit trail (client/server applications, audit
trail analysis and examination tools).
dce_aud_collect Appends the contents of one audit trail file to the end of
another audit trail file (audit trail administration and
examination tools).
dce_aud_commit Performs the audit actions (client/server applications).
dce_aud_discard Discards an audit record that releases the memory
(client/server applications, audit trail analysis and
examination tools).
dce_aud_first_record Reads the first audit record from a specified audit trail
file into a buffer.
dce_aud_free_ev_info Frees the memory allocated for an event information
structure returned from calling the dce_aud_get_ev_info
routine (audit trail analysis and examination tools).
dce_aud_free_header Frees the memory allocated to a designated audit record
header structure (audit trail analysis and examination
tools).
dce_aud_get_ev_info Gets the event-specific information of a specified audit
record (audit trail analysis and examination tools).
dce_aud_get_header Gets the header of a specified audit record (audit trail
analysis and examination tools).
dce_aud_last_record Reads the last audit record from a specified audit trail
file into a buffer.
dce_aud_length Gets the length of a specified audit record (client/server
applications, audit trail analysis and examination tools).
dce_aud_modify_sstrategy Modifies the storage strategy of the audit daemon.
dce_aud_next Reads the next audit record from a specified audit trail
into a buffer (audit trail analysis and examination
tools).
dce_aud_open Opens a specified audit trail for read or write
(client/server applications, audit trail analysis and
examination tools).
dce_aud_print Formats an audit record into a human-readable form (audit
trail analysis and examination tools).
dce_aud_prev Reads the previous audit record from a specified audit
trail file into a buffer (audit trail analysis and
examination tools).
dce_aud_put_ev_info Adds event-specific information to a specified audit
record buffer (client/server applications).
dce_aud_rename Renames the specified audit trail (audit trail analysis
and examination tools).
dce_aud_rewind Rewinds the specified audit trail (audit trail analysis
and examination tools).
dce_aud_save Saves the specified audit trail file (audit trail analysis
and examination tools).
dce_aud_set_local_cell_uuid Obtains the cell's UUID.
dce_aud_set_trail_size_limit Sets a limit to the audit trail size
(client/server applications).
dce_aud_start Determines whether a specified event should be audited,
given the client's binding information and the event
outcome. If the event should be audited or if it is not
yet known whether the event should be audited because the
event outcome is still unknown, memory for the audit
record descriptor is allocated and the address of this
memory is returned to the caller (client/server
applications).
dce_aud_start_with_name Determines whether a specified event should be
audited, given the client/server name and the event
outcome. If the event should be audited or if it is not
yet known whether the event should be audited because the
event outcome is still unknown, memory for the audit
record descriptor is allocated and the address of this
memory is returned to the caller (client/server
applications).
dce_aud_start_with_pac Determines whether a specified event should be audited,
given the client's privilege attribute certificate (PAC)
and the event outcome. If the event should be audited or
if it is not yet known whether the event should be audited
because the event outcome is still unknown, memory for the
audit record descriptor is allocated and the address of
this memory is returned to the caller (client/server
applications).
dce_aud_start_with_server_binding Determines whether a specified event should
be audited, given the server's binding information and the
event outcome. If the event should be audited or if it is
not yet known whether the event should be audited because
the event outcome is still unknown, memory for the audit
record descriptor is allocated and the address of this
memory is returned to the caller (client/server
applications).
dce_aud_start_with_uuid Determines whether a specified event should be
audited, given the client/server UUID and the event
outcome. If the event should be audited, or if the outcome
of the event is not yet known, the memory for the audit
record descriptor is allocated and the address of this
structure is returned to the caller (client/server
applications).
get_event_name_from_event_number Returns the event name from the event number
(trail analysis and examination tools).
get_event_number_from_event_name Returns the event number from the event name
(trail analysis and examination tools).
ΓòÉΓòÉΓòÉ 3.4.2. Audit Data Types ΓòÉΓòÉΓòÉ
The following sections list the data types and structures used by applications
to perform auditing and to analyze audit trails.
Event-Specific Information The Audit API routines allow applications to
include event-specific information in audit records.
Event-specific information must be represented as
information items using the following data type:
typedef struct {
unsigned16 format;
union {
idl_small_int small_int;
idl_short_int short_int;
idl_long_int long_int;
idl_hyper_int hyper_int;
idl_usmall_int usmall_int;
idl_ushort_int ushort_int;
idl_ulong_int ulong_int;
idl_uhyper_int uhyper_int;
idl_short_float short_float;
idl_long_float long_float;
idl_boolean boolean;
uuid_t uuid;
utc_t utc;
sec_acl_t *acl;
idl_byte *byte_string;
idl_char *char_string;
} data;
} dce_aud_ev_info_t;
The format field of the preceding data structure defines
formatting information that is used to determine the type
of the data referenced by the data field. The following
table shows possible values of the format field, their
corresponding data types, and their sizes.
ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
Γöé Table 1. Event Data Format Specifiers Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé SPECIFIER Γöé DATA TYPE Γöé SIZE Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé aud_c_evt_info_small_int Γöé idl_small_int Γöé 1 byte Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé aud_c_evt_info_short_int Γöé idl_short_int Γöé 2 bytes Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé aud_c_evt_info_long_int Γöé idl_long_int Γöé 4 bytes Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé aud_c_evt_info_hyper_int Γöé idl_hyper_int Γöé 8 bytes Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé aud_c_evt_info_usmall_int Γöé idl_usmall_int Γöé 1 bytes Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé aud_c_evt_info_ushort_int Γöé idl_ushort_int Γöé 2 bytes Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé aud_c_evt_info_ulong_int Γöé idl_ulong_int Γöé 4 bytes Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé aud_c_evt_info_uhyper_int Γöé idl_uhyper_int Γöé 8 bytes Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé aud_c_evt_info_short_float Γöé idl_short_float Γöé 4 bytes Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé aud_c_evt_info_long_float Γöé idl_long_float Γöé 8 bytes Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé aud_c_evt_info_boolean Γöé idl_boolean Γöé 1 byte Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé aud_c_evt_info_uuid Γöé uuid_t Γöé 16 bytes Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé aud_c_evt_info_utc Γöé utc_t Γöé 16 bytes Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé aud_c_evt_info_acl Γöé sec_acl_t * Γöé variable size Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé aud_c_evt_info_byte_string Γöé idl_byte * Γöé variable size Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé aud_c_evt_info_char_string Γöé idl_char * Γöé variable size Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
Byte strings and character strings are terminated with a 0
(zero) byte. New data types can be added to this list, if
they are used frequently. Servers can use the pickling
service of the IDL compiler to encode complex data types
into byte strings that are to be included in an audit
record.
Audit Record Header Data Structure The following data structure is used to
store header information obtained from an audit record.
This structure is normally used only by audit trail
analysis and examination tools. That is, it is hidden from
client/server applications.
typedef struct {
unsigned32 format;
uuid_t server;
unsigned32 event;
unsigned16 outcome;
unsigned16 authz_st;
uuid_t client;
uuid_t cell;
unsigned16 num_groups;
utc_t time;
char *addr;
uuid_t *groups;
} dce_aud_hdr_t;
format Contains the version number of the
tail format of the event used for the
event-specific information. With this
format version number, the audit
analysis tools can accommodate changes
in the formats of the event-specific
information. For example, the
event-specific information of an event
can initially be defined to be a
32-bit integer, and later changed to a
character string. Format version 0
(zero) is assigned to the initial
format for each event.
server Contains the UUID of the server that
generates the audit record.
event Contains the event number.
outcome Indicates whether the event failed or
succeeded. If the event failed, the
reason for the failure is given.
authz_st Indicates how the client is
authorized: by a name or by a DCE
privilege attribute certificate (PAC).
client Contains the UUID of the client.
cell Contains the UUID of the client cell.
num_groups Contains the number of local group
privileges the client used for access.
groups Contains the UUIDs of the local group
privileges that are used by the client
for the access. By default, the group
information is not included in the
header (num_groups is set to 0 in this
case), to minimize the size of the
audit records. If the group
information is deemed as important, it
can be included.
Information about foreign groups
(global groups that do not belong to
the same cell where the client is
registered) is not included in this
version of the audit header but can be
included in later versions when global
groups are supported.
time Contains a timestamp of utc_t type
that records the time when the server
committed the audit record (that is,
after providing the event information
through Audit API routine calls).
Recording this time, rather than
recording the time when the audit
record is appended to an audit trail,
better maintains the sequence of
events. The implementation of the
audit subsystem can involve
communication between the server and a
remote audit daemon, incurring
indefinite delays by network problems
or intruders. The inaccuracy in the
utc_t timestamp can be useful for
correlating events. When searching for
events in an audit trail that occur
within a time interval, if the results
of the comparisons between the time of
an event and the interval starting and
ending times is maybe (because of
inaccuracies), the event should be
returned.
addr Records the client address (port
address of the caller). Port addresses
are not authenticated. A caller can
provide a fraudulent port address to a
DCE server. However, if this
unauthenticated port address is deemed
to be useful information, a DCE server
can record this information using this
field.
The identity of the server cell is not
recorded in the header, because of the
assumption that all audit records in
an audit trail are for servers within
a single cell, and implicitly, that
the server cell is the local cell.
audit record descriptor An opaque data type, dce_aud_rec_t, is used to
represent an audit record descriptor. An audit record
descriptor can be manipulated by the following routines:
o These routines return a record descriptor:
dce_aud_start
dce_aud_start_with_pac
dce_aud_start_with_name
dce_aud_start_with_server_binding
dce_aud_next
o dce_aud_put_ev_info adds event information to an
audit record through a record descriptor.
o These routines get the event and record information
through a record descriptor:
dce_aud_get_header
dce_aud_get_ev_info
dce_aud_length
o The dce_aud_commit routine commits an audit record
through its descriptor.
o The routine dce_aud_discard disposes of a record
descriptor. The routine dce_aud_discard is necessary
only after reading the record (that is, after calling
dce_aud_next).
Audit Trail Descriptor An opaque data type, dce_aud_trail_t, is used to
represent an audit trail descriptor. The dce_aud_open
routine opens an audit trail and returns a trail
descriptor; dce_aud_next obtains an audit record from this
descriptor; and dce_aud_commit commits an audit record
from and to an opened audit trail through this descriptor.
The dce_aud_close routine disposes of this descriptor.
ΓòÉΓòÉΓòÉ 3.4.3. Environment Variables ΓòÉΓòÉΓòÉ
The Audit API routines use the following environment variables:
DCEAUDITOFF If this environment variable is defined at the
time the application is started, auditing is
turned off.
DCEAUDITON If this environment variable is defined at the
time the application is started, auditing is
turned on.
DCEAUDITFILTERON If this environment variable is defined,
filtering is enabled.
DCEAUDITTRAILSIZE Sets the limit of the audit trail size. This
variable overrides the limit set by the
dce_aud_set_trail_size_limit routine.
Note: If both the DCEAUDITOFF and DCEAUDITON environment variables are set
before starting the Audit daemon, DCEAUDITOFF takes precedence.
ΓòÉΓòÉΓòÉ 3.4.4. Permissions Required ΓòÉΓòÉΓòÉ
To use an Audit daemon's audit record logging service, you need the log (l)
permission to the Audit daemon.
ΓòÉΓòÉΓòÉ 3.4.5. Related Information ΓòÉΓòÉΓòÉ
Books:
DCE for OS/2 Warp: Administration Command Reference
DCE for OS/2 Warp: Application Development Guide - Core Components
ΓòÉΓòÉΓòÉ 3.4.6. dce_aud_clean ΓòÉΓòÉΓòÉ
Purpose
Resets and rewinds the specified audit trail file. This routine is
used by the audit trail analysis and examination tools.
Format
#include <dce\audit.h>
void dce_aud_clean(
dce_aud_trail_t at,
unsigned32 *status);
Parameters
Input
at A pointer to the descriptor of an audit trail file
previously opened for writing by the dce_aud_open
routine.
Output
status The status code returned by this routine. On successful
completion, the routine returns aud_s_ok. Otherwise,
the status code is one of the following:
aud_s_invalid_trail_descriptor The audit trail
descriptor is invalid.
aud_s_clean_trail_file The chsize call failed on
the trail file.
aud_s_clean_index_file The chsize call failed on
the index file.
Usage
The dce_aud_clean routine resets and rewinds the audit trail file to
zero size. This routine can be used to clean up the audit trail file
instantly when the audit trail file is no longer needed The
dce_aud_open routine must be called to specify the desired audit
trail to be reset and rewound. Otherwise, the audit trail file that
is currently set in at will be reset and rewound.
If the call is successful, the file cursors are set to the beginning
of the files.
Storage allocated by this routine must be explicitly freed by a call
to dce_aud_discard with ard as the input parameter.
Related Information
Routines: dce_aud_open
dce_aud_save
ΓòÉΓòÉΓòÉ 3.4.7. dce_aud_close ΓòÉΓòÉΓòÉ
Purpose
Closes an audit trail file. This routine is used by client/server
applications and audit trail analysis and examination tools.
Format
#include <dce\audit.h>
void dce_aud_close(
dce_aud_trail_t at,
unsigned32 *status);
Parameters
Input
at A pointer to an audit trail descriptor returned by a
previous call to dce_aud_open.
Output
status A pointer to the completion status. On successful
completion, the routine returns aud_s_ok. Otherwise, it
returns an error.
Usage
The dce_aud_close routine releases data structures of file openings,
RPC bindings, and other memory associated with the audit trail that
is specified by the audit trail descriptor.
Related Information
Routines:
dce_aud_open
ΓòÉΓòÉΓòÉ 3.4.8. dce_aud_collect ΓòÉΓòÉΓòÉ
Purpose
Appends the contents of one audit trail file to the end of another
audit trail file. This routine is used by the trail administration
and and examination tools.
Format
#include <dce\audit.h>
void dce_aud_collect(
dce_aud_trail_t from,
dce_aud_trail_t to,
unsigned32 *status);
Parameters
Input
from A pointer to the audit trail file descriptor whose
contents are to be copied.
to A pointer to the audit trail file descriptor whose
contents are to be appended with the from audit trail
file.
Output
status A pointer to the completion status. On successful
completion, the routine returns aud_s_ok. Otherwise, it
returns one of the following errors:
aud_s_invalid_trail_descriptor The audit trail
descriptor is invalid.
aud_s_cannot_open_trail_file_rc The fopen call
failed on the trail file.
aud_s_cannot_open_index_file_rc The fopen call
failed on the index file.
Usage
The dce_aud_collect routine collects the data from one trail file
(specified in from) and move them to another trail file (specified in
to). This routine is useful when analyzing the audit trail files of
different releases or different systems in a network.
The from and to parameters are returned from a successful
dce_aud_open invocation.
Related Information
Routines: dce_aud_open
dce_aud_save
ΓòÉΓòÉΓòÉ 3.4.9. dce_aud_commit ΓòÉΓòÉΓòÉ
Purpose
Writes the audit record in the audit trail file. This routine is used
by client/server applications.
Format
#include <dce\audit.h>
void dce_aud_commit(
dce_aud_trail_t at,
dce_aud_rec_t ard,
unsigned32 options,
unsigned16 format,
unsigned32 outcome,
unsigned32 *status);
Parameters
Input
at Designates an audit trail file to which the completed
audit record is written. The audit trail file must have
been previously opened by a successful call to the
dce_aud_open routine.
ard Designates an audit record descriptor that was returned
by a previously successful call to one of the
dce_aud_start_xxx routines. The content of this record
buffer is appended to the audit trail specified by at.
options Bitwise OR of option values described below. A value of
0 for options results in the default operation (normal
writing to the file without flushing to stable
storage). The possible option values are:
aud_c_evt_commit_sync Flushes the audit record to
stable storage before the routine returns.
aud_c_evt_always_ems Unconditionally sends the
audit record to EMS as an audit event.
aud_c_evt_always_log Unconditionally logs the
audit record to the audit trail.
aud_c_evt_always_alarm Unconditionally displays
the audit record on the console. If the
storage or audit logging service is not
available (for example, when the audit trail
file is full), the routine keeps on trying
until it is able to do a successful write to
the stable storage.
aud_c_evt_commit_sync_no_wait Flush the audit
record to stable storage. Returns an error
status if the storage or audit logging
service is not available.
format The tail format of the event used for the
event-specific information. This format can be
configured by the user. With this format version
number, the servers and audit analysis tools can
accommodate changes in the formats of the event
specific information, or use different formats
dynamically.
outcome The event outcome to be stored in the header. The
possible values are:
aud_c_esl_cond_success The event completed
successfully.
aud_c_esl_cond_denial The event failed because of
access denial.
aud_c_esl_cond_failure The event failed because of
reasons other than access denial.
aud_c_esl_cond_pending The event is in an
intermediate state, and the outcome is
pending, being one in a series of connected
events, where the application waits to record
the real outcome only after the last event.
aud_c_esl_cond_unknown The event outcome (denial,
failure, pending, or success) is not known.
This outcome exists only between a
dce_aud_start (all varieties of this routine)
and the next dce_aud_commit call. You can
also use 0 to specify this outcome.
Output
status Returns the status code from this routine. On
successful completion, the routine returns aud_s_ok.
Otherwise, the status code is one of the following:
aud_s_wrong_protection_level Client used the wrong
protection level.
aud_s_dmn_disabled The daemon is disabled for
logging.
aud_s_log_access_denied The client's access to the
audit log was denied.
aud_s_cannot_gettime The audit library cannot back
up a trail file because the utc_gettime
routine failed.
aud_s_cannot_getgmtime The audit library cannot
back up a trail file because the utc_gmtime
routine failed.
aud_s_rename_trail_file_rc Cannot rename the audit
trail file.
aud_s_cannot_reopen_trail_file_rc Internally, the
audit trail file was being reopened and the
reopening of the file failed.
aud_s_rename_trail_index_file_rc Internally, the
audit trail index file was being renamed and
the renaming of the file failed.
aud_s_cannot_reopen_trail_index_file_rc
Internally, the audit trail index file was
being reopened and the reopening of the file
failed.
aud_s_invalid_record_descriptor The audit record
descriptor is not valid.
aud_s_invalid_outcome The event outcome parameter
that was provided is not valid.
aud_s_outcomes_inconsistent The event outcome
parameter is inconsistent with the outcome
parameter provided in the dce_aud_start
routine.
aud_s_trl_write_failure The audit record cannot be
written to stable storage.
Status codes passed from dce_aud_discard.
Status codes passed from
rpc_binding_inq_auth_caller
Status codes passed from
dce_acl_is_client_authorized
Status codes passed from
audit_pickle_dencode_ev_info (RPC idl compiler)
Usage
The dce_aud_commit routine determines whether the event should be
audited, given the event outcome. If it should be audited, the
routine completes the audit record identified by ard and writes it to
the audit trail designated by at. If any of the aud_c_evt_always_log
or aud_c_evt_always_alarm options is selected, the event is always
audited (logged, or an alarm message sent to the standard output).
If the aud_c_evt_commit_sync option is selected, the routine attempts
to flush the audit record to stable storage. If the stable storage
write cannot be performed, the routine either continues to try until
the stable-storage write is completed or returns an error status.
Upon successful completion, dce_aud_commit calls dce_aud_discard
internally to release the memory of the audit record that is being
committed.
The caller should not change the outcome between the dce_aud_start
and dce_aud_commit routines arbitrarily. In this case, the outcome
can be made more specific; for example, from aud_c_esl_cond_unknown
to aud_c_esl_cond_success or from aud_c_esl_cond_pending to
aud_c_esl_cond_success.
An outcome change from aud_c_esl_cond_success to
aud_c_esl_cond_denial is not logically correct because the outcome
aud_c_esl_cond_success can have caused a NULL ard to be returned in
this routine. If the final outcome can be aud_c_esl_cond_success, it
should be specified in this routine, or use aud_c_esl_cond_unknown.
Related Information
Routines:
dce_aud_put_ev_info
dce_aud_start
dce_aud_start_with_pac
dce_aud_start_with_name
dce_aud_start_with_server_binding
dce_aud_open
ΓòÉΓòÉΓòÉ 3.4.10. dce_aud_discard ΓòÉΓòÉΓòÉ
Purpose
Discards an audit record (releases the memory). This routine is used
by client/server applications and trail analysis and examination
tools.
Format
#include <dce\audit.h>
void dce_aud_discard
dce_aud_rec_t ard,
unsigned32 *status);
Parameters
Input
ard Designates an audit record descriptor that was returned
by a previously successful call to one of the
dce_aud_start_xxx routines or the dce_aud_next routine.
Output
status The status code returned by this routine. If completed
successfully, the routine returns aud_s_ok. Otherwise,
the status code is passed from dce_aud_free_header.
Usage
The dce_aud_discard routine releases the memory used by the audit
record descriptor and the associated audit record that is to be
discarded.
Related Information
Routines:
dce_aud_free_header
dce_aud_next
dce_aud_open
dce_aud_prev
dce_aud_start
dce_aud_start_with_name
dce_aud_start_with_pac
dce_aud_start_with_server_binding
ΓòÉΓòÉΓòÉ 3.4.11. dce_aud_first_record ΓòÉΓòÉΓòÉ
Purpose
Reads the first audit record from a specified audit trail file into a
buffer. Used by the trail analysis and examination tools.
Format
#include <dce\audit.h>
void dce_aud_first_record(
dce_aud_trail_t at,
unsigned16 format,
dce_aud_rec_t *ard,
unsigned32 *status);
Parameters
Input
at A pointer to the descriptor of an audit trail file
previously opened for reading by the dce_aud_open
routine.
format The event's tail format used for the event-specific
information. This format can be configured by the user.
With this format version number, the servers and audit
analysis tools can accommodate changes in the formats
of the event specification information, or use
different formats dynamically.
Output
ard A pointer to the audit record descriptor containing the
returned record.
status The status code returned by this routine. On
successful completion, the routine returns aud_s_ok.
Otherwise, it returns one of the following errors:
aud_s_invalid_trail_descriptor The audit trail
descriptor is invalid.
aud_s_trail_file_corrupted The audit trail file is
corrupted.
aud_s_index_file_corrupted The audit index trail
file is corrupted.
aud_s_cannot_allocate_memory_rc The malloc call
failed.
Status codes passed from
idl_es_decode_buffer.
Status codes passed from
idl_es_handle_free.
Status codes passed from
audit_pickle_dencode_ev_info.
Usage
The dce_aud_first_record routine reads the first record from the
audit trail file which is specified by the audit trail descriptor,
at. The routine can be used to examine the first audit record written
to the audit trail file. It is very useful after the audit trail file
is wrapped around or cleaned up.
If no record is found, a value of zero (NULL) is returned in ard. The
value in ard can be supplied as an input parameter to the following
routines:
dce_aud_discard
dce_aud_get_ev_info
dce_aud_get_event
dce_aud_get_header
dce_aud_length
dce_aud_print
If the routine successfully reads an audit trail record, the cursor
associated with the audit trail descriptor, at, is moved to the
second record in the audit trail file. If no record can be found in
the audit trail file, an ard value of NULL is returned and the cursor
is set back to the beginning of the audit trail. If a call is
unsuccessful, the position of the cursor does not change.
Notes
Storage allocated by this routine must be explicitly freed by a call
to dce_aud_discard with ard as the input parameter.
Related Information
Routines: dce_aud_next
dce_aud_prev
dce_aud_get_header
dce_aud_get_ev_info
dce_aud_open
dce_aud_discard
dce_aud_print
dce_aud_get_event
ΓòÉΓòÉΓòÉ 3.4.12. dce_aud_free_ev_info ΓòÉΓòÉΓòÉ
Purpose
Frees the memory allocated for an event information structure
returned from calling dce_aud_get_ev_info. This routine is used by
the audit trail analysis and examination tools.
Format
#include <dce\audit.h>
void dce_aud_free_ev_info(
dce_aud_ev_info_t *event_info,
unsigned32 *status);
Parameters
Input
event_info Designates an event-specific information item returned
from a previously successful call to the
dce_aud_get_ev_info routine.
Output
status The status code returned by this routine. If
successful, the routine returns aud_s_ok.
Usage
The dce_aud_free_ev_info routine frees the memory allocated for an
event information structure returned by a previously successful call
to the dce_aud_get_ev_info routine.
Related Information
Routines: dce_aud_get_ev_info
dce_aud_next
ΓòÉΓòÉΓòÉ 3.4.13. dce_aud_free_header ΓòÉΓòÉΓòÉ
Purpose
Frees the memory allocated to a designated audit record header
structure. This routine is used by the audit trail analysis and
examination tools.
Format
#include <dce\audit.h>
void dce_aud_free_header(
dce_aud_hdr_t *header,
unsigned32 *status);
Parameters
Input
ard Designates a pointer to an audit record header
structure that was returned by a previously successful
call to the dce_aud_get_header routine.
Output
status The status code returned by this routine. If
successful, the routine returns aud_s_ok.
Usage
The dce_aud_free_header frees the memory allocated to a designated
audit record header structure. The designated audit record header is
usually obtained from an audit record by calling dce_aud_get_header.
Related Information
Routines:
dce_aud_get_header
dce_aud_open
dce_aud_next
ΓòÉΓòÉΓòÉ 3.4.14. dce_aud_get_ev_info ΓòÉΓòÉΓòÉ
Purpose
Returns a pointer to an event information structure
(dce_aud_ev_info_t). This routine is used by the audit trail analysis
and examination tools.
Format
#include <dce\audit.h>
void dce_aud_get_ev_info(
dce_aud_rec_t ard,
dce_aud_ev_info_t **event_info,
unsigned32 *status);
Parameters
Input
ard Designates an audit record descriptor that was returned
by a previously successful call to the dce_aud_next
routine.
Output
event_info Returns an event-specific information item of the
designated audit record. Returns NULL if there are no
more information items.
status The status code returned by this routine. If
successful, the routine returns aud_s_ok. If not, the
status code contains the following error:
aud_s_invalid_record_descriptor The audit record
descriptor is not valid.
Usage
The dce_aud_get_ev_info routine returns a pointer to an event
information structure. The designated record is usually obtained from
an audit trail by calling dce_aud_open and dce_aud_next. If there is
more than one item of event-specific information in the audit record,
one item is returned through one call to dce_aud_get_ev_info. The
order the items are returned in is the same as the order that they
were included in the audit record through dce_aud_put_ev_info
routines. This routine allocates the memory to hold the
human-readable representation of the audit record and returns the
address of this memory.
Related Information
Routines:
dce_aud_next
dce_aud_open
dce_aud_prev
ΓòÉΓòÉΓòÉ 3.4.15. dce_aud_get_event ΓòÉΓòÉΓòÉ
Purpose
Searches and gets an event in the audit trail file. This routine is
used by the trail administration and examination tools.
Format
#include <dce\audit.h>
void dce_aud_get_event(
dce_aud_trail_t at,
unsigned32 event,
int order,
dce_aud_rect_t *ard,
unsigned32 *status);
Parameters
Input
at A pointer to the descriptor of an audit trail file
previously opened for reading by the dce_aud_open
routine.
event The event to be searched.
order The type of search: successor (1) or predecessor (0).
Output
ard A pointer to the audit record descriptor containing the
returned record.
status The status code returned by this routine. If
successful, the routine returns aud_s_ok. If not, the
status code contains one of the following:
aud_s_invalid_trail_descriptor The audit trail
descriptor is not valid.
aud_s_cannot_allocate_memory_rc The malloc call
failed.
Status codes from idl_es_decode_buffer.
Status codes from idl_es_handle_free.
Status codes from
audit_pickle_dencode_ev_info.
Usage
The dce_aud_get_event routine attempts to search a specified event in
the audit trail file. This routine uses the fast Two-Dimensional
Algorithm to search and read the record into the buffer. The search
can be specified in successor order (order is 1) or predecessor order
(order is 0). A subsequence call searches and reads one record after
or one record before into the buffer as do the dce_aud_next and
dce_aud_prev routines.
The dce_aud_get_event routine can be used to search for all the event
records that have the same event number recorded in the audit trail
file. Although dce_aud_next or dce_aud_prev can output the same
results when the predicate parameter is set to EVENT=value, they
sequentially read all the records in the audit trail file from top to
bottom or vice versa to search for the right ones. Therefore, the
search is very slow.
If a call is successful (that is, an appropriate record matched the
event number) the record is read into the buffer. The value of ard
can be supplied as an input parameter value to the following
routines:
dce_aud_print
dce_aud_get_header
dce_aud_get_ev_info
dce_aud_discard
dce_aud_length
If no appropriate record matched the event number, an ard value of
NULL is returned.
Related Information
Routines:
dce_aud_next
dce_aud_open
dce_aud_prev
ΓòÉΓòÉΓòÉ 3.4.16. dce_aud_get_header ΓòÉΓòÉΓòÉ
Purpose
Gets the header of a specified audit record. This routine is used by
the audit trail analysis and examination tools.
Format
#include <dce\audit.h>
void dce_aud_get_header(
dce_aud_rec_t ard,
dce_aud_hdr_t **header,
unsigned32 *status);
Parameters
Input
ard Designates an audit record descriptor that was returned
by a previously successful call to the dce_aud_next
routine.
Output
header Returns the header information of the designated audit
record.
status The status code returned by this routine. If
successful, the routine returns aud_s_ok. If not, the
status code contains the following error:
aud_s_invalid_record_descriptor The audit record
descriptor is not valid.
Usage
The dce_aud_get_header routine gets the header information of a
designated audit record. The designated record is usually obtained
from an audit trail by calling dce_aud_open and dce_aud_next.
Related Information
Routines:
dce_aud_next
dce_aud_open
dce_aud_prev
ΓòÉΓòÉΓòÉ 3.4.17. dce_aud_last_record ΓòÉΓòÉΓòÉ
Purpose
Reads the last audit record from a specified audit trail file into a
buffer. Used by the trail analysis and examination tools.
Format
#include <dce\audit.h>
void dce_aud_last_record(
dce_aud_trail_t at,
unsigned16 format,
dce_aud_rec_t *ard,
unsigned32 *status);
Parameters
Input
at A pointer to the descriptor of an audit trail file
previously opened for reading by the dce_aud_open
routine.
format The event's tail format used for the event-specific
information. This format can be configured by the user.
With this format version number, the servers and audit
analysis tools can accommodate changes in the formats
of the event specification information, or use
different formats dynamically.
Output
ard A pointer to the audit record descriptor containing the
returned record.
status The status code returned by this routine. On
successful completion, the routine returns aud_s_ok.
Otherwise, it returns one of the following errors:
aud_s_invalid_trail_descriptor The audit trail
descriptor is invalid.
aud_s_trail_file_corrupted The audit trail file is
corrupted.
aud_s_index_file_corrupted The audit index file is
corrupted.
aud_s_cannot_allocate_memory_rc The malloc call
failed.
Status codes passed from
idl_es_decode_buffer.
Status codes passed from
idl_es_handle_free
Status codes passed from
audit_pickle_dencode_ev_info.
Usage
The dce_aud_last_record routine reads the last record from the audit
trail file which is specified by the audit trail descriptor, at. The
routine can be used to examine the latest (current) audit record
written to the audit trail file. It is very useful after the audit
trail file is wrapped around or cleaned up.
If no record is found, a value of zero (NULL) is returned in ard. The
value in ard can be supplied as an input parameter to the following
routines:
dce_aud_discard
dce_aud_get_ev_info
dce_aud_get_event
dce_aud_get_header
dce_aud_length
dce_aud_print
If the routine successfully reads an audit trail record, the cursor
associated with the audit trail descriptor, at, is moved to the
second record in the audit trail file. If no record can be found in
the audit trail file, an ard value of NULL is returned and the cursor
is set back to the beginning of the audit trail. If a call is
unsuccessful, the position of the cursor does not change.
Notes
Storage allocated by this routine must be explicitly freed by a call
to dce_aud_discard with ard as the input parameter.
Related Information
Routines: dce_aud_next
dce_aud_prev
dce_aud_get_header
dce_aud_get_ev_info
dce_aud_open
dce_aud_discard
dce_aud_print
dce_aud_get_event
dce_aud_length
ΓòÉΓòÉΓòÉ 3.4.18. dce_aud_length ΓòÉΓòÉΓòÉ
Purpose
Gets the length of a specified audit record. This routine is used by
client/server applications and trail analysis and examination tools.
Format
#include <dce\audit.h>
unsigned32 dce_aud_length(
dce_aud_rec_t ard,
unsigned32 *status);
Parameters
Input
ard Designates an audit record descriptor that was returned
by a previously successful call to dce_aud_next, or one
of the dce_aud_start_xxx routines.
Output
status The status code returned by this routine. If
successful, the routine returns aud_s_ok. If not, the
status code contains one of the following errors:
aud_s_invalid_record_descriptor The audit record
descriptor is not valid.
Status codes passed from idl_es_encode_dyn_buffer.
Status codes passed from
audit_pickle_dencode_ev_info (RPC IDL compiler).
Status codes passed from idl_es_handle_free.
Status codes passed from rpc_sm_client_free.
Usage
The dce_aud_length routine gets the length of a designated audit
record. The designated record (in binary format) can be obtained from
an audit trail by calling the dce_aud_open and dce_aud_next routines.
Applications can use this routine to know how much space an audit
record uses before it is committed. This routine can also be used by
audit trail analysis and examination tools to determine the space
that a previously committed audit record uses before it is read.
Return Values
The size of the specified audit record in number of bytes.
Related Information
Routines:
dce_aud_next
dce_aud_open
dce_aud_prev
dce_aud_put_ev_info
dce_aud_start
dce_aud_start_with_name
dce_aud_start_with_pac
dce_aud_start_with_server_binding
ΓòÉΓòÉΓòÉ 3.4.19. dce_aud_modify_sstrategy ΓòÉΓòÉΓòÉ
Purpose
Modifies the storage strategy of the audit daemon.
Format
#include <dce\audit.h>
void dce_aud_modify_sstrategy(
dce_aud_trail_t h,
unsigned32 *strgy,
error_status_t *status);
Parameters
Input
h A pointer to the descriptor of an audit trail file
previously opened by dce_aud_open.
strgy This states the storage strategy. Possible values for
strgy are:
SAVE The trail, when full, is backed up,
renamed with a timestamp, and then
written to the original trail again.
WRAP The trail, when full, returns to the
beginning of the file, and overwrites
previously written records.
Output
status A pointer to the completion status. On successful
completion, the routine returns aud_s_ok.
Usage
The dce_aud_modify_sstrategy routine is an administrative operation
that modifies the storage strategy on the audit deamon. It defines
what the daemon does if the audit trail storage is full.
Related Information
Routines:
dce_aud_open
ΓòÉΓòÉΓòÉ 3.4.20. dce_aud_next ΓòÉΓòÉΓòÉ
Purpose
Reads the next audit record from a specified audit trail file into a
buffer. This routine is used by the trail analysis and examination
tools.
Format
#include <dce\audit.h>
void dce_aud_next(
dce_aud_trail_t at,
char *predicate,
unsigned16 format,
dce_aud_rec_t *ard,
unsigned32 *status;
Parameters
Input
at A pointer to the descriptor of an audit trail file
previously opened for reading by the routine
dce_aud_open.
predicate Criteria for selecting the audit records that are to be
read from the audit trail file. A predicate statement
consists of an attribute and its value, separated by
any of the following operators: = (equal to), < (less
than), and > (greater than):
o attribute=value
o attribute>value
o attribute<value
Attribute names are case-sensitive, and no space is
allowed within a predicate expression. Multiple
predicates are delimited by a comma, of the form:
attribute1=value1,attribute2>value2,...
No space is allowed between predicates.
Note: When multiple predicates are defined the values
are logically ANDed together.
The possible attribute names, their values, and
allowable operators are:
SERVER The UUID of the server
principal that generated the
record. The attribute value
must be a UUID string.
Operator allowed: =.
EVENT The audit event number. The
attribute value must be an
integer. Operator allowed: =.
OUTCOME The event outcome of the
record. The possible attribute
values are SUCCESS, FAILURE,
DENIAL, and PENDING. Operator
allowed: =.
STATUS The authorization status of
the client. The possible
attribute values are DCE for
DCE authorization (PAC based),
and NAME for name-based
authorization. Operator
allowed: =.
CLIENT The UUID of the client
principal. The attribute value
must be a UUID string.
Operator allowed: =.
TIME The time the record was
generated. The attribute value
must be a null-terminated
string that expresses an
absolute time. Operators
allowed: <=, <, >=, and >.
CELL The UUID of the client's cell.
The attribute value must be a
UUID string. Operator allowed:
=.
GROUP The UUID of one of the
client's groups. The attribute
value must be a UUID string.
Operator allowed: =.
ADDR The address of the client. The
attribute is typically the
string representation of an
RPC binding handle. Operator
allowed: =.
FORMAT The format version number of
the audit event record. The
attribute value must be an
integer. Operators allowed: =,
<, and >.
If the predicate parameter is a NULL pointer, the next
record in the audit trail file is returned.
format The event tail format used for the event-specific
information. This format can be configured by the user.
With this format version number, the servers and audit
analysis tools can accommodate changes in the formats
of the event-specific information, or use different
formats dynamically.
Output
ard A pointer to the audit record descriptor containing the
returned record.
status Returns the status code from this routine. If
successful, the routine returns aud_s_ok. If not, the
status code contains one of the following errors:
aud_s_invalid_trail_descriptor The audit trail
descriptor is not valid.
aud_s_trail_file_corrupted The trail file is
corrupted.
aud_s_cannot_allocate_memory The malloc routine
failed.
Status codes passed from idl_es_decode_buffer.
Status codes passed from idl_es_handle_free.
Status codes passed from
audit_pickle_dencode_ev_info (RPC IDL compiler).
Usage
The dce_aud_next routine attempts to read the next record from the
audit trail that is specified by the audit trail descriptor, at. This
routine also defines the predicate to be used to search for the next
record and returns a matching record if one exists. The dce_aud_next
routine can be used to search for successive records in the trail
that match the defined predicate. By default, if no predicate is
explicitly defined, the routine returns the next record read from the
audit trail.
If no record satisfies the predicate specified for the call, a value
of 0 (zero) is returned in ard.
The value returned in ard can be supplied as an input parameter to
the routines dce_aud_get_header, dce_aud_length, dce_aud_get_ev_info,
and dce_aud_discard.
Storage allocated by this routine must be explicitly freed by a call
to dce_aud_discard with ard as the input parameter.
If the routine successfully reads an audit trail record, the cursor
associated with the audit trail descriptor at is advanced to the next
record in the audit trail.
If no appropriate record can be found in the audit trail, an ard
value of 0 (zero) is returned and the cursor is advanced to the end
of the audit trail. If a call is unsuccessful, the position of the
cursor does not change.
Related Information
Routines:
dce_aud_discard
dce_aud_get_ev_info
dce_aud_get_header
dce_aud_length
dce_aud_open
dce_aud_prev
ΓòÉΓòÉΓòÉ 3.4.21. dce_aud_open ΓòÉΓòÉΓòÉ
Purpose
Opens a specified audit trail file for read or write. This routine is
used by client/server applications and trail analysis and examination
tools.
Format
#include <dce\audit.h>
void dce_aud_open(
unsigned32 flags,
char *description,
unsigned32 first_evt_number,
unsigned32 num_of_evts,
dce_aud_trail_t *at,
unsigned32 *status);
Parameters
Input
flags Specifies the mode of opening. The flags parameter is
set to the bitwise OR of the following values:
aud_c_trl_open_read
aud_c_trl_open_write
aud_c_trl_open_write_no_filter
aud_c_trl_ss_save
aud_c_trl_ss_wrap
description A character string specifying an audit trail file to be
opened. If description is NULL, the default audit trail
file is opened. When the audit trail file is opened for
write, the default audit trail is an RPC interface to a
local Audit daemon.
first_evt_num The lowest assigned audit event number used by the
calling server.
num_of_evts The number of audit events defined for the calling
server.
Output
at A pointer to an audit trail descriptor. When the audit
trail descriptor is no longer needed, it must be
released by calling the dce_aud_close routine.
status Returns the status code from this routine. If
successful, the routine returns aud_s_ok. If not, the
status code contains one of the following errors:
aud_s_trl_invalid_open_flags The flags parameter
must include either aud_c_trl_open_read or
aud_c_trl_open_write flag, but not both.
aud_s_cannot_open_dmn_binding_file The local audit
daemon trail file is designated, but the
daemon's binding file cannot be opened.
Status codes passed from
sec_login_get_current_context When the local audit
daemon trail file is designated, a login
context is needed for making a secure audit
logging RPC to the audit daemon.
aud_s_cannot_open_dmn_identity_file The local
audit daemon trail file is designated, but
the daemon's identity file cannot be opened.
Status codes passed from rpc_binding_set_auth_info
When the local audit daemon trail file is
designated, dce_aud_open sets authentication
information in the RPC binding handle for
making a secure audit logging RPC to the
audit daemon. This is done by calling
rpc_binding_set_auth_info.
aud_s_cannot_open_trail_file_rc Cannot open a
local trail file.
aud_s_cannot_allocate_memory Memory allocation
failed.
aud_s_cannot_init_trail_mutex Audit trail mutex
initialization failed.
Status codes passed from rpc_server_inq_bindings
When filtering is turned on, dce_aud_open
gets the caller's RPC bindings to be used for
registering an RPC interface in receiving
filter update notification from the local
audit daemon. This is done by calling
rpc_server_inq_bindings.
Status codes passed from
rpc_binding_to_string_binding When filtering is
turned on, the caller's RPC bindings are
converted to string bindings before they are
stored in a file. This is done by calling
rpc_binding_to_string_binding.
aud_s_cannot_mkdir Cannot create a directory for
storing the bindings file for the filter
update notification interface.
Usage
The dce_aud_open routine opens the audit trail file specified by the
description parameter. If description is NULL, the routine uses the
default audit trail, which is an RPC interface to the local Audit
daemon.
This routine must be invoked after the server has finished
registering with RPC and before calling rpc_server_listen.
If the flags parameter is set to aud_c_trl_open_read, the specified
file (description cannot be NULL in this case) is opened for reading
audit records, using the dce_aud_next routine. If flags is set to
aud_c_trl_open_write, the specified file or the default audit trail
device is opened and initialized for appending audit records using
the dce_aud_commit routine. Only one of the aud_c_trl_open_read and
aud_c_trl_open_write flags can be specified in any call to
dce_aud_open. If the flags parameter is set to aud_c_trl_ss_wrap, the
audit trail operation is set to wrap mode. The aud_c_trl_ss_wrap flag
has meaning only if you specify the aud_c_trl_open_write flag.
If the audit trail specified is a file and the calling server does
not have the read and write permissions to the file, a NULL pointer
is returned in at, and status is set to
aud_s_cannot_open_trail_file_rc. The same values are returned if the
default audit trail file is used (that is, through an audit daemon)
and if the calling server is not authorized to use the audit daemon
to log records.
Related Information
Routines:
dce_aud_commit
dce_aud_next
dce_aud_prev
dce_aud_start
dce_aud_start_with_name
dce_aud_start_with_pac
dce_aud_start_with_server_binding
ΓòÉΓòÉΓòÉ 3.4.22. dce_aud_prev ΓòÉΓòÉΓòÉ
Purpose
Reads the previous audit record from a specified audit trail file
into a buffer. This routine is used by the audit trail examination
and analysis tools.
Format
#include <dce\audit.h>
void dce_aud_prev(
dce_aud_trail_t at,
char *predicate,
unsigned16 format,
dce_aud_rec_t *ard,
unsigned32 *status);
Parameters
Input
at A pointer to the descriptor of an audit trail file
previously opened for reading by the dce_aud_open
routine.
predicate Criteria for selecting the audit records that are to be
read from the Audit trail file. A predicate statement
consists of an attribute and its value, separated by
any of the following operators:
= (equal to) (for example, attribute=value)
> (greater than) (for example, attribute>value)
< (less than) (for example, attribute<value)
>= (greater than or equal to) (for example,
attribute>=value)
<= (less than or equal to) (for example,
attribute<=value)
Attribute names are case sensitive, and no space is
allowed within a predicate expression. Multiple
predicates are delimited by a comma, of the form:
attribute1=value1,attribute2>value2,...).
No space is allowed between predicates.
Note: When multiple predicates are defined, the values
are logically ANDed together.
The possible attributes names, their values, and
allowable operators are:
SERVER The UUID of the server principal that
generated the record. The attribute
value must be a UUID string. Operator
allowed: =.
EVENT The audit event number. The attribute
value must be a heximal number.
Operator allowed: =.
OUTCOME The event outcome of the record. The
possible attribute values are
SUCCESS, FAILURE, DENIAL, and
PENDING. Operator allowed: =.
STATUS The authorization status of the
client. The possible attribute values
are DCE for DCE authorization (PAC
based) NAME for name-based
authorization. Operator allowed: =.
TIME The time the record was created. The
attribute values must be a
null-terminated string that expressed
an absolute time. Operators allowed:
<=, <, >, and >=.
CELL The UUID of the client's cell. The
attribute value must be a UUID
string. Operator allowed: =.
GROUP The UUID of one of the client's group
or groups. The attribute value must
be a UUID string. Operator allowed:
=.
ADDR The address of the client. The
attribute is typically the string
representation of an RPC binding
handle. Operator allowed: =.
FORMAT The format version number of the
audit event record. The attribute
value must be an integer. Operators
allowed: =, <, and >.
format The event's tail format used for the event-specific
information. This format can be configured by the user.
With this format version number, the servers and audit
analysis tools can accommodate changes in the formats
of the event specification information, or use
different formats dynamically.
Output
ard A pointer to the audit record descriptor containing the
returned record.
status The status code returned by this routine. This status
code indicates whether the routine was completed
successfully or not. If successful, the routine returns
aud_s_ok. If not, the status code contains one of the
following errors:
aud_s_invalid_trail_descriptor The audit trail
descriptor is not valid.
aud_s_trail_file_corrupted The audit trail is
corrupted.
aud_s_index_file_corrupted The index trail file is
corrupted.
aud_s_cannot_allocate_memory_rc The malloc call
failed.
Status codes passed from idl_es_decode_buffer.
Status codes passed from idl_es_handle_free.
Status codes passed from
audit_pickle_dencode_ev_info.
Usage
The dce_aud_prev routine attempts to read the previous record from
the audit trail file that is specified by the audit trail descriptor
at. This routine also defines the predicate to be used to search for
the previous record and returns a matching record if one exists. The
dce_aud_prev routine can be used to search for previous records in
the trail file that match the defined predicate. By default, if no
predicate is defined, the routine returns the previous record read
from the audit trail.
If no record satisfies the predicate specified for the call, a value
of zero ( NULL) is returned in ard.
The value returned in ard can be supplied as an input parameter to
the routines:
dce_aud_get_header
dce_aud_length
dce_aud_get_ev_info
dce_aud_get_event
dce_aud_discard
dce_aud_print
Storage allocated by this routine must be explicitly freed by a call
to dce_aud_discard with ard as the input parameter.
If the routine successfully reads an audit trail record, the cursor
associated with the audit trail descriptor at will be moved to the
previous record in the audit trail file. The calling routine does not
need to set or move the file cursor explicitly.
If no appropriate record can be found in the audit trail, an ard
value of zero (NULL) is returned and the cursor is set back to the
beginning of the audit trail. If a call is unsuccessful, the position
of the cursor does not change.
Related Information
Routines:
dce_aud_discard
dce_aud_get_ev_info
dce_aud_get_event
dce_aud_get_header
dce_aud_length
dce_aud_next
dce_aud_open
dce_aud_print
ΓòÉΓòÉΓòÉ 3.4.23. dce_aud_print ΓòÉΓòÉΓòÉ
Purpose
Formats an audit record into human-readable form. This routine is
used by audit trail examination and analysis tools.
Format
#include <dce\audit.h>
void dce_aud_print(
dce_aud_rec_t ard,
unsigned32 options,
unsigned_char_t **buffer,
unsigned32 *status);
Parameters
Input
ard An audit record descriptor. This descriptor can be
obtained from an opened audit trail by calling
dce_aud_next or it can be a new record established by
calling one of the dce_aud_start_xxx routines.
options The options governing the transformation of the binary
audit record information into a character string. The
value of the options parameter is the bitwise OR of any
selected combination of the following option values:
aud_c_evt_groups_info Includes group
information.
aud_c_evt_address_info Includes address
information.
aud_c_evt_specific_info Includes event
specific
information.
aud_c_evt_delegates_info Includes
delegation
information.
aud_c_evt_raw_info Includes raw
information.
aud_c_evt_all_info Includes all the
optional
information (that
is, groups,
address, and
event specific
information).
Output
buffer Returns the pointer to a character string converted
from the audit record specified by ard.
status The status code returned by this routine. If
successful, the routine returns aud_s_ok. If not, the
status code contains one of the following errors:
aud_s_invalid_record_descriptor The audit record
descriptor is not valid.
aud_s_cannot_allocate_memory The malloc call
failed.
Status codes passed from
sec_login_get_current_context.
Status codes passed from
sec_login_inquire_net_info.
Usage
The dce_aud_print routine transforms the audit record specified by
ard into a character string and places it in a buffer. The buffer is
allocated using malloc, and must later be freed by the caller. (This
routine allocates the memory to hold the human-readable text of the
audit record and returns the address of this memory in the buffer
parameter.)
The options parameter is set to the bitwise OR of flag values defined
in the dce\audit.h header file. A value of 0 for options results in
default operation, that is, no group, address, and event-specific
information is included in the output string.
Notes
The memory for a returned character string is allocated by malloc and
must be freed by the caller of dce_aud_print using dce_free.
Related Information
Routines:
dce_aud_open
dce_aud_start
dce_aud_start_with_pac
dce_aud_start_with_name
dce_aud_start_with_server_binding
dce_aud_next
dce_aud_put_ev_info
dce_free
ΓòÉΓòÉΓòÉ 3.4.24. dce_aud_put_ev_info ΓòÉΓòÉΓòÉ
Purpose
Adds event-specific information to a specified audit record buffer.
This routine is used by client/server applications.
Format
#include <dce\audit.h>
void dce_aud_put_ev_info(
dce_aud_rec_t ard,
dce_aud_ev_info_t info,
error_status_t *status);
Parameters
Input
ard A pointer to an audit record descriptor initialized by
one of the dce_aud_start_xxx routines.
info A data structure containing an event-specific
information item that is to be appended to the tail of
the audit record identified by ard. The possible
formats of the event-specific information are listed in
Audit Data Types.
Output
status The status code returned by this routine. If
successful, the routine returns aud_s_ok. If not, the
status code contains one of the following errors:
aud_s_invalid_record_descriptor The input audit
record descriptor is not valid.
aud_s_evt_tail_info_exceeds_limit The tail portion
of the audit trail record has exceeded its
limit of 4K.
Usage
The dce_aud_put_ev_info routine adds event-specific information to an
audit record. The event-specific information is included in an audit
record by calling dce_aud_put_ev_info one or more times. The order of
the information items included by multiple calls is preserved in the
audit record, so that they can be read in the same order by the
dce_aud_get_ev_info routine. This order is also observed by the
dce_aud_print routine. The info parameter is a pointer to an instance
of the self-descriptive dce_aud_ev_info_t structure.
Related Information
Routines:
dce_aud_commit
dce_aud_open
dce_aud_start
dce_aud_start_with_pac
dce_aud_start_with_name
dce_aud_start_with_server_binding
ΓòÉΓòÉΓòÉ 3.4.25. dce_aud_rename ΓòÉΓòÉΓòÉ
Purpose
Renames the specified audit trail. This routine is used by the trail
analysis and examination tools.
Format
#include <dce\audit.h>
void dce_aud_rename(
dce_aud_trail_t at,
char *new_name,
unsigned32 *status);
Parameters
Input
at A pointer to the descriptor of an audit trail file
previously opened for writing by the dce_aud_open
routine.
new_name The new audit trail file name.
Output
status The status code returned by this routine. If
successful, the routine returns aud_s_ok. Otherwise,
the status code is one of the following:
aud_s_invalid_trail_descriptor The audit trail
descriptor is invalid.
aud_s_invalid_name The value of new_name is
invalid (NULL).
aud_s_rename_trail_file_rc The rename call failed
on the trail file.
aud_s_rename_index_file_rc The rename call failed
on the index file.
Usage
The dce_aud_rename routine renames the audit trail file and the index
file to the name specified by new_name. DCE administrators can use
this routine to save the audit trail file before it reaches the
wrapping point.
Note: For a platform, where a FAT file system is applied, the
specified name cannot exceed 8 characters and the extension is
not included.
The audit trail file and the index trail file must be closed and
cannot be used by any process before the files are renamed.
The dce_aud_open routine must be called to specify the desired audit
trail. Otherwise, the audit trail that is currently set in at will be
renamed.
Notes
Storage allocated by this routine must be explicitly freed by a call
to the dce_aud_discard routine with ard as the input parameter.
Related Information
Routines:
dce_aud_clean
dce_aud_save
dce_aud_open
dce_aud_rewind
ΓòÉΓòÉΓòÉ 3.4.26. dce_aud_rewind ΓòÉΓòÉΓòÉ
Purpose
Rewinds the specified audit trail. This routine is used by the trail
analysis and examination tools.
Format
#include <dce\audit.h>
void dce_aud_rewind(
dce_aud_trail_t at,
unsigned32 *status);
Parameters
Input
at A pointer to the descriptor of an audit trail file
previously opened for writing by the dce_aud_open
routine.
Output
status The status code returned by this routine. If
successful, the routine returns aud_s_ok. Otherwise,
the status code is one of the following:
aud_s_invalid_trail_descriptor The audit trail
descriptor is invalid.
aud_s_rewind_trail_file The ftruncate call failed
on the trail file.
aud_s_rewind_index_file The ftruncate call failed
on the index file.
Usage
The dce_aud_rewind routine rewinds the specified audit trail file.
This routine can be used to instantly clean up the audit trail file
if it is no longer needed. The dce_aud_open routine must be called to
specify the desired audit trail. Otherwise, dce_aud_rewind will
rewind the latest audit trail file that is currently set in at.
If the call is successful, the file cursors are set to the beginning
of the file.
Notes
Storage allocated by this routine must be explicitly freed by a call
to the dce_aud_discard routine with ard as the input parameter.
Related Information
Routines:
dce_aud_clean
dce_aud_open
ΓòÉΓòÉΓòÉ 3.4.27. dce_aud_save ΓòÉΓòÉΓòÉ
Purpose
Saves the specified audit trail. This routine is used by the trail
analysis and examination tools.
Format
#include <dce\audit.h>
void dce_aud_save(
dce_aud_trail_t at,
char *name,
unsigned32 *status);
Parameters
Input
at A pointer to the descriptor of an audit trail file
previously opened for reading by the dce_aud_open
routine.
name The new audit trail file name.
Output
status The status code returned by this routine. If
successful, the routine returns aud_s_ok. Otherwise,
the status code is one of the following:
aud_s_invalid_trail_descriptor The audit trail
descriptor is invalid.
aud_s_cannot_open_trail_file_rc The fopen call
failed on the trail file (R/W).
aud_s_cannot_open_index_file_rc The fopen call
failed on the index file (R/W).
Usage
The dce_aud_save routine saves the specified audit trail and index
files. This routine is useful for backup. DCE application developers
can use this routine to implement the save function in their
applications.
For a platform, where a FAT file system is applied, the specified
name cannot exceed 8 characters and the extension is not included. If
a NULL is specified for name, the audit trail and index files are
saved (or copied) to the \opt\dcelocal\var\audit\adm subdirectory
with a default extension. For example, on the OS/2 platform, the file
centrail is saved as centrail.old and centrail.mdi is saved as
centrail.odi. Similarly, on the AIX platform, central_trail is saved
as central_trail.old and central_trail.md_index is saved as
central_trail.md_index.old.
The dce_aud_open routine must be called to specify the desired audit
trail to be saved. Otherwise, the audit trail that is currently set
in at will be saved.
Related Information
Routines:
dce_aud_clean
dce_aud_open
dce_aud_rename
dce_aud_rewind
ΓòÉΓòÉΓòÉ 3.4.28. dce_aud_set_local_cell_uuid ΓòÉΓòÉΓòÉ
Purpose
Obtains the cell's uuid.
Format
#include <dce/audit.h>
void dce_aud_set_local_cell_uuid(
uuid_t cell_uuid,
error_status_t *status);
Parameters
Input
cell_uuid The cell's uuid.
Input
status A pointer to the completion status. On successful
completion, the routine returns aud_s_ok.
Usage
Obtains the cell UUID from the registry and provides this to the
audit daemon.
ΓòÉΓòÉΓòÉ 3.4.29. dce_aud_set_trail_size_limit ΓòÉΓòÉΓòÉ
Purpose
Sets a limit to the audit trail size. This routine is used by
client/server applications.
Format
#include <dce\audit.h>
void dce_aud_set_trail_size_limit (
dce_aud_trail_t at,
unsigned32 file_size_limit_value,
unsigned32 *status)
Parameters
Input
at A pointer to the descriptor of an audit trail file
previously opened for reading by the routine
dce_aud_open.
file_size_limit_value The desired maximum size of the audit trail
file, in bytes.
Output
status Returns the status code of this routine. If successful,
the routine returns aud_s_ok. If not, the status code
contains aud_s_invalid_trail_descriptor, which
indicates that the audit trail descriptor at is null.
Usage
The dce_aud_set_trail_size_limit routine can be used by an
application that links with libaudit to set the maximum size of the
audit trail. This routine must be called immediately after calling
dce_aud_open.
For added flexibility, the environment variable DCEAUDITTRAILSIZE can
also be used to set the maximum trail size limit.
If none of these methods is used for setting the trail size, a
hardcoded limit of 2 megabytes is assumed.
If set, the value of the environment variable DCEAUDITTRAILSIZE
overrides the value set by this routine. Any of the values set by
DCEAUDITTRAILSIZE or this routine overrides the hardcoded default.
When the size limit is reached, the current trail file is copied to
another file. The name of this new file is the original file name
with a timestamp appended. For example, if the name of the original
trail file is central_trail, its companion trail file is named
central_trail.md_index. These two files are copied to
central_trail.1994-09-26-16-38-15 and
central_trail.1994-09-26-16-38-15.md_index.
When a trail file is copied to a new file by the audit library
because it has reached the size limit, a serviceability message is
issued to the console notifying the user that an audit trail file
(and its companion index file) is available to be backed up. After
the backup is performed, it is advisable to remove the old trail
file, to prevent running out of disk space.
Auditing then continues, using the original name of the file, (in our
example, central_trail).
Related Information
Routines:
dce_aud_open
Environment Variables:
DCEAUDITTRAILSIZE
ΓòÉΓòÉΓòÉ 3.4.30. dce_aud_start ΓòÉΓòÉΓòÉ
Purpose
Determines whether a specified event should be audited given the
client binding information and the event outcome. If the event must
be audited, or if the outcome of the event is not yet known, the
memory of the audit record descriptor is allocated and the address to
this structure is returned to the caller. This routine is used by
client/server applications.
Format
#include <dce\audit.h>
void dce_aud_start(
unsigned32 event,
rpc_binding_handle_t binding,
unsigned32 options,
unsigned32 outcome,
dce_aud_rec_t *ard,
error_status_t *status);
Parameters
Input
event Specifies the event to be audited. This is a 32-bit
event number. The event field in the audit record
header is set to this number.
binding Specifies the client's RPC binding handle from which
the client identification information is retrieved to
set the client, cell, num_groups, groups, and addr
fields in the audit record header.
options Specifies the optional header information wanted
(aud_c_evt_all_info, aud_c_evt_group_info, or
aud_c_evt_address_info).
It can also be used to specify whether the audit
records are always logged (aud_c_evt_always_log) or
that an alarm message is always sent to the standard
output (aud_c_evt_always_alarm). If either of these two
options is selected, the filter is bypassed.
The value of the options parameter is the bitwise OR of
any selected combination of the following option
values:
aud_c_evt_all_info Includes all optional
information (groups and address) in the audit
record header.
aud_c_evt_groups_info Includes the groups
information in the audit record header.
aud_c_evt_address_info Includes the client address
information in the audit record header.
aud_c_evt_always_log Bypasses the filter mechanism
and indicates that the event must be logged.
aud_c_evt_always_ems Unconditionally sends the
audit record to EMS as an audit event.
aud_c_evt_always_alarm Bypasses the filter
mechanism and indicates that an alarm message
must be sent to the system console for the
event.
outcome The event outcome to be stored in the header. The
following event outcome values are defined:
aud_c_esl_cond_success The event was completed
successfully.
aud_c_esl_cond_denial The event failed because
access was denied.
aud_c_esl_cond_failure The event failed for
reasons other than access denial.
aud_c_esl_cond_pending The event is in an
intermediate state; the outcome is pending
and is one in a series of connected events,
where the application waits to record the
real outcome only after the last event.
aud_c_esl_cond_unknown The event outcome (denial,
failure, pending, or success) is still
unknown. This outcome exists only between a
dce_aud_start (all varieties of this routine)
call and the next dce_aud_commit call. You
can also use 0 to specify this outcome.
Output
ard Returns a pointer to an audit record buffer. If the
event does not need to be audited because it is not
selected by the filters, or if the environment variable
DCEAUDITOFF has been set, a NULL pointer is returned.
If the routine is called with outcome set to
aud_c_esl_cond_unknown, it is possible that the routine
cannot determine whether the event should be audited.
In this case, the audit record descriptor is still
allocated and its address is returned to the caller. An
outcome other than aud_c_esl_cond_unknown must be
provided when calling the dce_aud_commit routine.
status The status code returned by this routine. If
successful, the routine returns aud_s_ok. If not, the
status code contains one of the following errors:
Status codes passed from
rpc_binding_to_string_binding.
Status codes passed from rpc_string_free.
Status codes passed from dce_aud_start_with_name.
Status codes passed from sec_cred_get_initiator.
Status codes passed from sec_cred_get_v1_pac.
Status codes passed from dce_aud_start_with_pac.
Status codes passed from sec_cred_get_delegate.
Usage
The dce_aud_start routine determines if an audit record should be
generated for the specified event. The decision is based on the event
filters, two environment variables (DCEAUDITON and DCEAUDITOFF), the
client's identity provided in the binding parameter, and the event
outcome (if it is provided in the outcome parameter). If this event
needs to be audited, the routine allocates an audit record descriptor
and returns a pointer to it, (that is, ard). If the event does not
need to be audited, a NULL ard is returned. If an internal error has
occurred, a NULL pointer is returned in ard. If the
aud_c_evt_always_log or aud_c_evt_always_alarm option is selected, an
audit record descriptor is always created and returned.
Note: If both the DCEAUDITOFF and DCEAUDITON environment variables
are set before starting the Audit daemon, DCEAUDITOFF takes
precedence.
The dce_aud_start routine is designed to be used by RPC applications.
Non-RPC applications that use the DCE authorization model (that is,
DCE ACL and PAC) must use dce_aud_start_with_pac. Non-RPC
applications that do not use the DCE authorization model must use
dce_aud_start_with_name.
This routine obtains the client identity information from the RPC
binding handle and records it in the newly created audit record
descriptor.
Event-specific information can be added to the record by calling the
dce_aud_put_ev_info routine. This routine can be called multiple
times after calling dce_aud_start and before calling dce_aud_commit.
A completed audit record is appended to an audit trail file or sent
to the Audit daemon (depending on the value of the description
parameter used in the previous call to dce_aud_open) by calling
dce_aud_commit.
This routine searches for all relevant filters (for the specified
subject and outcome, if these are specified), summarizes the actions
for each possible event outcome, and records an outcome-action table
with ard. If the outcome is specified when calling this routine and
the outcome does not require any action according to filters, then
this routine returns a NULL ard.
If outcome is not specified in the dce_aud_start routine,
dce_aud_start returns a NULL ard if no action is required for all
possible outcomes.
The caller should not change the outcome between the dce_aud_start
and dce_aud_commit calls arbitrarily. But in this case, the outcome
can be made more specific, for example, from aud_c_esl_cond_unknown
to aud_c_esl_cond_success or from aud_c_esl_cond_pending to
aud_c_esl_cond_success.
An outcome change from aud_c_esl_cond_success to
aud_c_esl_cond_denial is not logically correct because the outcome
aud_c_esl_cond_success may have caused a NULL ard to be returned in
this routine. If the final outcome can be aud_c_esl_cond_success, it
should be specified in this routine, or use aud_c_esl_cond_unknown.
This routine can be called with an outcome parameter of zero or the
union (logical OR) of selected values from the set of constants
aud_c_esl_cond_success, aud_c_esl_cond_failure,
aud_c_esl_cond_denial, and aud_c_esl_cond_pending. The outcome
parameter used in the dce_aud_commit routine should take one value
from the same set of constants.
If dce_aud_start used a non-zero value for outcome, the constant used
for outcome in the dce_aud_commit call should have been selected in
the dce_aud_start call.
Related Information
Routines:
dce_aud_commit
dce_aud_open
dce_aud_put_ev_info
dce_aud_start_with_pac
dce_aud_start_with_name
dce_aud_start_with_server_binding
ΓòÉΓòÉΓòÉ 3.4.31. dce_aud_start_with_name ΓòÉΓòÉΓòÉ
Purpose
Determines whether a specified event should be audited, given the
client/server name and the event outcome. If the event must be
audited, or if the outcome of the event is not yet known, the memory
for the audit record descriptor is allocated and the address of this
structure is returned to the caller. This routine is used by non-RPC
based client/server applications that do not use the DCE
authorization model.
Format
#include <dce\audit.h>
void dce_aud_start_with_name(
unsigned32 event,
unsigned_char_t *client,
unsigned_char_t *address,
unsigned32 options,
unsigned32 outcome,
dce_aud_rec_t *ard,
unsigned32 *status);
Parameters
Input
event Specifies the event to be audited. This is a 32-bit
event number. The event field in the audit record
header is set to this number.
client Specifies the principal name of the remote
client/server.
address Specifies the address of the remote client/server. The
address could be in any format of the underlying
transport protocol.
options Specifies the optional header information wanted
(aud_c_evt_all_info, aud_c_evt_group_info,
aud_c_evt_address_info).
It can also be used to specify any of two options: to
always log an audit record (aud_c_evt_always_log) or to
always send an alarm message to the standard output
(aud_c_evt_always_alarm). If either of these two
options is selected, the filter is bypassed. The value
of the options parameter is the bitwise OR of any
selected combination of the following option values:
aud_c_evt_all_info Includes all optional
information (groups and address) in the audit
record header.
aud_c_evt_groups_info Includes the groups
information in the audit record header.
aud_c_evt_address_info Includes the client address
information in the audit record header.
aud_c_evt_always_log Bypasses the filter mechanism
and indicates that the event must be logged.
aud_c_evt_always_ems Unconditionally sends the
audit record to EMS as an audit event.
aud_c_evt_always_alarm Bypasses the filter
mechanism and indicates that an alarm message
must be sent to the system console for the
event.
aud_c_evt_specific_info Includes event specific
information.
aud_c_evt_delegates_info Includes delegation
information.
aud_c_evt_raw_info Includes raw information.
outcome The event outcome to be stored in the header. The
following event outcome values are defined:
aud_c_esl_cond_success The event was completed
successfully.
aud_c_esl_cond_denial The event failed because
access was denied.
aud_c_esl_cond_failure The event failed for
reasons other than access denial.
aud_c_esl_cond_pending The event is in an
intermediate state; the outcome is pending
and is one in a series of connected events,
where the application waits to record the
real outcome only after the last event.
aud_c_esl_cond_unknown The event outcome (denial,
failure, pending, or success) is still
unknown. This outcome exists only between a
dce_aud_start (all varieties of this routine)
call and the next dce_aud_commit call. You
can also use 0 to specify this outcome.
Output
ard Returns a pointer to an audit record buffer. If the
event does not need to be audited because it is not
selected by the filters, or if the environment variable
DCEAUDITOFF has been set, a NULL pointer is returned.
If the routine is called with outcome set to
aud_c_esl_cond_unknown, the routine may not be able to
determine whether the event should be audited. In this
case, the audit record descriptor is still allocated
and its address is returned to the caller. An outcome
must be provided prior to logging the record with the
dce_aud_commit routine.
status The status code returned by this routine. If
successful, the routine returns aud_s_ok. If not, the
status code contains one of the following errors:
Status codes passed from sec_rgy_site_open.
Status codes passed from sec_id_parse_name.
Status codes passed from dce_aud_start_with_pac
Usage
The dce_aud_start_with_name routine determines if an audit record
must be generated for the specified event. The decision is based on
the event filters, two environment variables (DCEAUDITON and
DCEAUDITOFF), the client's identity provided in the input parameters,
and the event outcome (if it is provided in the outcome parameter).
If this event needs to be audited, the routine allocates an audit
record descriptor and returns a pointer to it, (that is, ard). If the
event does not need to be audited, NULL is returned in the ard
parameter. If either the aud_c_evt_always_log orthe
aud_c_evt_always_alarm option is selected, an audit record descriptor
is always created and returned.
Note: If both the DCEAUDITOFF and DCEAUDITON environment variables
are set before starting the Audit daemon, DCEAUDITOFF takes
precedence.
The dce_aud_start_with_name routine is designed to be used by non-RPC
applications that do not use the DCE authorization model (that is,
DCE PAC and ACL). RPC applications must use dce_aud_start. Non-RPC
applications that use the DCE authorization model must use
dce_aud_start_with_pac.
This routine records the input identity parameters in the newly
created audit record descriptor.
Event-specific information can be added to the record by using the
dce_aud_put_ev_info routine, which can be called multiple times after
calling any of the dce_aud_start_xxx routines and before calling
dce_aud_commit. A completed audit record can either be appended to an
audit trail file or sent to the Audit daemon by calling
dce_aud_commit.
This routine searches for all relevant filters (for the specified
subject and outcome, if these are specified), summarizes the actions
for each possible event outcome, and records an outcome-action table
with ard. If the outcome is specified when calling this routine and
the outcome does not require any action according to filters, this
routine returns a NULL ard.
If outcome is not specified in the dce_aud_start_with_name call,
dce_aud_start_with_name returns a NULL ard if no action is required
for all possible outcomes.
The caller should not change the outcome between the
dce_aud_start_with_name and dce_aud_commit calls arbitrarily. In this
case, the outcome can be made more specific, for example, from
aud_c_esl_cond_unknown to aud_c_esl_cond_success or from
aud_c_esl_cond_pending to aud_c_esl_cond_success.
An outcome change from aud_c_esl_cond_success to
aud_c_esl_cond_denial is not logically correct because the outcome
aud_c_esl_cond_success may have caused a NULL ard to be returned in
this routine. If the final outcome can be aud_c_esl_cond_success, it
should be specified in this routine, or use aud_c_esl_cond_unknown.
This routine can be called with the outcome parameter taking a value
of zero or the union (logical OR) of selected values from the set of
constants aud_c_esl_cond_success, aud_c_esl_cond_failure,
aud_c_esl_cond_denial, and aud_c_esl_cond_pending. The outcome
parameter used in the dce_aud_commit routine should take one value
from the same set of constants.
If dce_aud_start_with_name used a non-zero value for outcome, the
constant used for outcome in the dce_aud_commit routine should have
been selected in the dce_aud_start_with_name routine.
Related Information
Routines:
dce_aud_commit
dce_aud_open
dce_aud_put_ev_info
dce_aud_start
dce_aud_start_with_pac
dce_aud_start_with_server_binding
ΓòÉΓòÉΓòÉ 3.4.32. dce_aud_start_with_pac ΓòÉΓòÉΓòÉ
Purpose
Determines whether a specified event must be audited, given the
client's privilege attribute certificate (PAC) and the event outcome.
If the event must be audited or if the outcome of the event is not
yet known, the memory for the audit record descriptor is allocated
and the address of this structure is returned to the caller. This
routine is used by non-RPC based client/server applications that use
the DCE authorization model.
Format
#include <dce\audit.h>
void dce_aud_start_with_pac(
unsigned32 event,
sec_id_pac_t *pac,
unsigned_char_t *address,
unsigned32 options,
unsigned32 outcome,
dce_aud_rec_t *ard,
unsigned32 *status);
Parameters
Input
event Specifies the event to be audited. This is a 32-bit
event number. The event field in the audit record
header is set to this number.
pac Specifies the client's PAC from which the client's
identification information is retrieved to set the
client, cell, num_groups, and groups fields in the
audit record header.
address Specifies the client's address. The address can be in
any format that is native to the underlying transport
protocol.
options Specifies the optional header information wanted
(aud_c_evt_all_info, aud_c_evt_group_info,
aud_c_evt_address_info). It can also be used to specify
any of two options: to always log an audit record
(aud_c_evt_always_log) or to always send an alarm
message to the standard output
(aud_c_evt_always_alarm). If either of these two
options is selected, the filter is bypassed.
The value of the options parameter is the bitwise OR of
any selected combination of the following option
values:
aud_c_evt_all_info Includes all optional
information (groups and address) in the audit
record header.
aud_c_evt_groups_info Includes the groups'
information in the audit record header.
aud_c_evt_address_info Includes the client address
information in the audit record header.
aud_c_evt_always_log Bypasses the filter and
indicates that the event must be logged.
aud_c_evt_always_alarm Bypasses the filter and
indicates that an alarm message must be sent
to the system console for the event.
aud_c_evt_specific_info Includes event specific
information.
aud_c_evt_delegates_info Includes delegation
information.
aud_c_evt_raw_info Includes raw information.
outcome The event outcome to be stored in the header. The
following event outcome values are defined:
aud_c_esl_cond_success The event was completed
successfully.
aud_c_esl_cond_denial The event failed because
access was denied.
aud_c_esl_cond_failure The event failed for
reasons other than access denial.
aud_c_esl_cond_pending The event is in an
intermediate state; the outcome is pending
and is one in a series of connected events,
where the application waits to record the
real outcome after the last event only.
aud_c_esl_cond_unknown The event outcome (denial,
failure, pending, or success) is still
unknown. This outcome exists only between a
dce_aud_start (all varieties of this routine)
call and the next dce_aud_commit call. You
can also use 0 to specify this outcome.
Output
ard Returns a pointer to an audit record buffer. If the
event does not need to be audited because it is not
selected by the filters, or if the environment variable
DCEAUDITOFF has been set, a NULL pointer is returned.
If the routine is called with outcome set to
aud_c_esl_cond_unknown, it is possible that the routine
cannot determine whether the event should be audited.
In this case, the audit record descriptor is still
allocated and its address is returned to the caller. An
outcome must be provided prior to logging the record
with the dce_aud_commit routine.
status The status code returned by this routine. If
successful, the routine returns aud_s_ok. If not, the
status code contains one of the following errors:
Status codes passed from sec_rgy_site_open.
Status codes passed from
sec_rgy_properties_get_info,
Status codes passed from uuid_create_nil.
Usage
The dce_aud_start_with_pac routine determines if an audit record must
be generated for the specified event. The decision is based on the
event filters, two environment variables (DCEAUDITON and
DCEAUDITOFF), the client's identity provided in the pac parameter,
and the event outcome (if it is provided in the outcome parameter).
If this event needs to be audited, the routine allocates an audit
record descriptor and returns a pointer to it, (that is, ard). If the
event does not need to be audited, NULL is returned in the ard
parameter. If either the aud_c_evt_always_log or
aud_c_evt_always_alarm option is selected, an audit record descriptor
is always created and returned.
Note: If both the DCEAUDITOFF and DCEAUDITON environment variables
are set before starting the Audit daemon, DCEAUDITOFF takes
precedence.
The dce_aud_start_with_pac routine is designed to be used by non-RPC
applications that use the DCE authorization model (that is, DCE PAC
and ACL). RPC applications must use dce_aud_start. Non-RPC
applications that do not use the DCE authorization model must use
dce_aud_start_with_name.
This routine obtains the client's identity information from the
client's privilege attribute certificate (PAC) and records it in the
newly created audit record descriptor.
Event-specific information can be added to the record by calling the
dce_aud_put_ev_info routine. This routine can be called multiple
times after calling any of the dce_aud_start_xxx routines and before
calling dce_aud_commit. A completed audit record can either be
appended to an audit trail file or sent to the Audit daemon by
calling the dce_aud_commit routine.
This routine searches for all relevant filters (for the specified
subject and outcome, if these are specified), summarizes the actions
for each possible event outcome, and records an outcome-action table
with ard. If the outcome is specified when calling this routine and
the outcome does not require any action according to filters, this
routine returns a NULL ard.
If the outcome is not specified in the dce_aud_start_with_pac call,
dce_aud_start_with_pac returns a NULL ard if no action is required
for all possible outcomes.
The caller should not change the outcome between the
dce_aud_start_with_pac and dce_aud_commit routines arbitrarily. In
this case, the outcome can be made more specific, for example, from
aud_c_esl_cond_unknown to aud_c_esl_cond_success or from
aud_c_esl_cond_pending to aud_c_esl_cond_success.
An outcome change from aud_c_esl_cond_success to
aud_c_esl_cond_denial is not logically correct because the outcome
aud_c_esl_cond_success may have caused a NULL ard to be returned in
this routine. If the final outcome can be aud_c_esl_cond_success,
then it should be specified in this routine, or use
aud_c_esl_cond_unknown.
This routine can be called with the outcome parameter taking a value
of zero or the union (logical OR) of selected values from the set of
constants aud_c_esl_cond_success, aud_c_esl_cond_failure,
aud_c_esl_cond_denial, and aud_c_esl_cond_pending. The outcome
parameter used in the dce_aud_commit routine should take one value
from the same set of constants.
If dce_aud_start_with_pac used a non-zero value for outcome, then the
constant used for outcome in the dce_aud_commit routine should have
been selected in the dce_aud_start_with_pac call.
Related Information
Routines:
dce_aud_commit
dce_aud_open
dce_aud_put_ev_info
dce_aud_start
dce_aud_start_with_name
dce_aud_start_with_server_binding
ΓòÉΓòÉΓòÉ 3.4.33. dce_aud_start_with_server_binding ΓòÉΓòÉΓòÉ
Purpose
Determines whether a specified event must be audited given the server
binding information and the event outcome. If the event must be
audited, or if the outcome of the event is not yet known, the memory
for the audit record descriptor is allocated and the address of this
structure is returned to the caller. This routine is used by
client/server applications.
Format
#include <dce\audit.h>
void dce_aud_start_with_server_binding(
unsigned32 event,
rpc_binding_handle_t binding,
unsigned32 options,
unsigned32 outcome,
dce_aud_rec_t *ard,
unsigned32 *status);
Parameters
Input
event Specifies the event to be audited. This is a 32-bit
event number. The event field in the audit record
header is set to this number.
binding Specifies the server's RPC binding handle from which
the server identification information is retrieved to
set the client, cell, and addr fields in the audit
record header. Note that when an application client
issues an audit record, the server identity is
represented in the client field of the record.
options This parameter can be used to specify the optional
header information desired (aud_c_evt_all_info,
aud_c_evt_group_info, aud_c_evt_address_info). It can
also be used to specify any of two options: to always
log an audit record (aud_c_evt_always_log) or to always
send an alarm message to the standard output
(aud_c_evt_always_alarm). If either of these two
options is selected, the filter is bypassed.
The value of the options parameter is the bitwise OR of
any selected combination of the following option
values:
aud_c_evt_address_info Includes the server address
information in the audit record header.
aud_c_evt_always_log Bypasses the filter and
indicates that the event must be logged.
aud_c_evt_always_alarm Bypasses the filter and
indicates that an alarm message must be sent
to the system console for the event.
aud_c_evt_specific_info Includes event specific
information.
aud_c_evt_delegates_info Includes delegation
information.
aud_c_evt_raw_info Includes raw information.
outcome The event outcome to be stored in the header. The
following event outcome values are defined:
aud_c_esl_cond_success The event was completed
successfully.
aud_c_esl_cond_denial The event failed because
access was denied.
aud_c_esl_cond_failure The event failed for
reasons other than access denial.
aud_c_esl_cond_pending The event is in an
intermediate state; the outcome is pending
and is one in a series of connected events,
where the application waits to record the
real outcome after the last event only.
aud_c_esl_cond_unknown The event outcome (denial,
failure, pending, or success) is still
unknown. This outcome exists only between a
dce_aud_start (all varieties of this routine)
call and the next dce_aud_commit call. You
can also use 0 to specify this outcome.
Output
ard Returns a pointer to an audit record buffer. If the
event does not need to be audited because it is not
selected by the filters, or if the environment variable
DCEAUDITOFF has been set, a NULL pointer is returned.
If the routine is called with outcome set to
aud_c_esl_cond_unknown, it is possible that the routine
cannot determine whether the event should be audited.
In this case, the audit record descriptor is still
allocated and its address is returned to the caller. An
outcome must be provided prior to logging the record
with the dce_aud_commit routine.
status The status code returned by this routine. If
successful, the routine returns aud_s_ok. If not, the
status code contains one of the following errors:
Status codes passed from
rpc_binding_inq_auth_info.
Status codes passed from
rpc_binding_to_string_binding.
Status codes passed from dce_aud_start_with_name
Usage
The dce_aud_start_with_server_binding routine determines if an audit
record must be generated for the specified event. The decision is
based on the event filters, two environment variables (DCEAUDITON and
DCEAUDITOFF), the server's identity provided in the binding
parameter, and the event outcome (if it is provided in the outcome
parameter). If this event needs to be audited, the routine allocates
an audit record descriptor and returns a pointer to it (that is,
ard). If the event does not need to be audited, NULL is returned in
the ard parameter. If the aud_c_evt_always_log or
aud_c_evt_always_alarm option is selected, an audit record descriptor
is always created and returned.
Note: If both the DCEAUDITOFF and DCEAUDITON environment variables
are set before starting the Audit daemon, DCEAUDITOFF takes
precedence.
The dce_aud_start_with_server_binding routine is designed to be used
by RPC applications. Non-RPC applications that use the DCE
authorization model must use the dce_aud_start_with_pac routine.
Non-RPC applications that do not use the DCE authorization model must
use the dce_aud_start_with_name routine.
This routine obtains the server identity information from the RPC
binding handle and records it in the newly created audit record
descriptor.
Event-specific information can be added to the record by calling the
dce_aud_put_ev_info routine. The dce_aud_put_ev_info routine can be
called multiple times after calling any of the dce_aud_start_xxx
routines and before calling dce_aud_commit. A completed audit record
can either be appended to an audit trail file or sent to the Audit
daemon by calling dce_aud_commit.
This routine searches for all relevant filters (for the specified
subject and outcome, if these are specified), summarizes the actions
for each possible event outcome, and records an outcome-action table
with ard. If the outcome is specified when calling this routine and
the outcome does not require any action according to filters, this
routine returns a NULL ard.
If the outcome is not specified in the
dce_aud_start_with_server_binding call,
dce_aud_start_with_server_binding returns a NULL ard if no action is
required for all possible outcomes.
The caller should not change the outcome between the
dce_aud_start_with_server_binding and dce_aud_commit calls
arbitrarily. In this case, the outcome can be made more specific, for
example, from aud_c_esl_cond_unknown to aud_c_esl_cond_success or
from aud_c_esl_cond_pending to aud_c_esl_cond_success.
An outcome change from aud_c_esl_cond_success to
aud_c_esl_cond_denial is not logically correct because the outcome
aud_c_esl_cond_success may have caused a NULL ard to be returned in
this routine. If the final outcome can be aud_c_esl_cond_success, it
should be specified in this routine, or use aud_c_esl_cond_unknown.
This routine can be called with the outcome parameter taking a value
of zero or the union (logical OR) of selected values from the set of
constants aud_c_esl_cond_success, aud_c_esl_cond_failure,
aud_c_esl_cond_denial, and aud_c_esl_cond_pending. The outcome
parameter used in the dce_aud_commit routine should take one value
from the same set of constants.
If dce_aud_start_with_server_binding used a non-zero value for
outcome, the constant used for outcome in the dce_aud_commit call
should have been selected in the dce_aud_start_with_server_binding
call.
Related Information
Routines:
dce_aud_commit
dce_aud_open
dce_aud_put_ev_info
dce_aud_start
dce_aud_start_with_pac
dce_aud_start_with_name
ΓòÉΓòÉΓòÉ 3.4.34. dce_aud_start_with_uuid ΓòÉΓòÉΓòÉ
Purpose
Determines whether a specified event should be audited, given the
client/server UUID and the event outcome. If the event must be
audited, or if the outcome of the event is not yet known, the memory
for the audit record descriptor is allocated and the address of this
structure is returned to the caller. This routine is used by
client/server applications that already know the UUIDs of their
clients and want to avoid the overhead of the audit library acquiring
them.
Format
#include <dce\audit.h>
void dce_aud_start_with_uuid(
unsigned32 event,
uuid_t server_uuid,
uuid_t client_uuid,
uuid_t realm_uuid,
unsigned_char_t * address,
unsigned32 options,
unsigned32 outcome,
dce_aud_rec_t *ard,
unsigned32 *status);
Parameters
Input
event Specifies the event to be audited. This is a 32-bit
event number. The event field in the audit record
header is set to this number.
server_uuid Specifies the calling application's principal UUID.
client_uuid Specifies the remote client or server's principal UUID.
realm_uuid Specifies the remote client or server's cell UUID.
address Specifies the remote client or server's address. The
address could be in any format of the underlying
transport protocol.
options Specifies the optional header information desired
(aud_c_evt_all_info, aud_c_evt_group_info,
aud_c_evt_address_info).
It can also be used to specify any of two options: to
always log an audit record (aud_c_evt_always_log) or to
always send an alarm message to the standard output
(aud_c_evt_always_alarm). If either of these two
options is selected, the filter is bypassed. The value
of the options parameter is the bitwise OR of any
selected combination of the following option values:
aud_c_evt_all_info Includes all optional
information (groups and address) in the audit
record header.
aud_c_evt_groups_info Includes the groups
information in the audit record header.
aud_c_evt_address_info Includes the client address
information in the audit record header.
aud_c_evt_always_log Bypasses the filter mechanism
and indicates that the event must be logged.
aud_c_evt_always_alarm Bypasses the filter
mechanism and indicates that an alarm message
must be sent to the system console for the
event.
aud_c_evt_specific_info Includes event specific
information.
aud_c_evt_delegates_info Includes delegation
information.
aud_c_evt_raw_info Includes raw information.
outcome The event outcome to be stored in the header. The
following event outcome values are defined:
aud_c_esl_cond_unknown The event outcome (denial,
failure, or success) is still unknown.
aud_c_esl_cond_success The event completed
successfully.
aud_c_esl_cond_denial The event failed because
access was denied.
aud_c_esl_cond_failure The event failed for
reasons other than access denial.
aud_c_esl_cond_pending The event outcome is
pending and is one in a series of connected
events, where the application wants to record
the real outcome after the last event only.
Output
ard Returns a pointer to an audit record buffer. If the
event does not need to be audited because it is not
selected by the filters, or if the environment variable
DCEAUDITOFF has been set, a NULL pointer is returned.
If the routine is called with outcome set to
aud_c_esl_cond_unknown, it is possible that the routine
cannot determine whether the event should be audited.
In this case, the audit record descriptor is still
allocated and its address is returned to the caller. An
outcome other than aud_c_esl_cond_unknown must be
provided prior to logging the record with the
dce_aud_commit routine.
status The status code returned by this routine. If
successful, the routine returns aud_s_ok. If not, the
status codes are passed from dce_aud_start_with_pac.
Usage
The dce_aud_start_with_uuid routine determines if an audit record
must be generated for the specified event. The decision is based on
the event filters, two environment variables (DCEAUDITON and
DCEAUDITOFF), the client's identity provided in the input parameters,
and the event outcome (if it is provided in the outcome parameter).
If this event needs to be audited, the routine allocates an audit
record descriptor and returns a pointer to it, (that is, ard). If the
event does not need to be audited, NULL is returned in the ard
parameter. If either the aud_c_evt_always_log or
aud_c_evt_always_alarm option is selected, an audit record descriptor
is always created and returned.
Note: If both the DCEAUDITOFF and DCEAUDITON environment variables
are set before starting the Audit daemon, DCEAUDITOFF takes
precedence.
The dce_aud_start_with_uuid routine is designed to be used by RPC
applications that know their client's identity in UUID form.
Otherwise, RPC applications should use dce_aud_start. Non-RPC
applications that use the DCE authorization model should use
dce_aud_start_with_pac. The dce_aud_start_with_name routine should be
used by Non-RPC applications that do not use the DCE authorization
model.
This routine records the input identity parameters in the
newly-created audit record descriptor.
Event-specific information can be added to the record by using the
dce_aud_put_ev_info routine, which can be called multiple times after
calling any of the dce_aud_start_xxx routines and before calling
dce_aud_commit. A completed audit record can either be appended to an
audit trail file or sent to the Audit daemon by calling
dce_aud_commit.
This routine searches for all relevant filters (for the specified
subject and outcome, if these are specified), summarizes the actions
for each possible event outcome, and records an outcome-action table
with ard. If the outcome is specified when calling this routine and
the outcome does not require any action according to filters, this
routine returns a NULL ard.
If the outcome is not specified in the dce_aud_start_with_uuid call,
dce_aud_start_with_uuid returns a NULL ard if no action is required
for all possible outcomes.
The caller should not change the outcome between the
dce_aud_start_with_uuid and dce_aud_commit calls arbitrarily. In this
case, the outcome can be made more specific, for example, from
aud_c_esl_cond_unknown to aud_c_esl_cond_success or from
aud_c_esl_cond_pending to aud_c_esl_cond_success.
An outcome change from aud_c_esl_cond_success to
aud_c_esl_cond_denial is not logically correct because the outcome
aud_c_esl_cond_success might have caused a NULL ard to be returned in
this routine. If the final outcome can be aud_c_esl_cond_success,
then it should be specified in this routine, or use
aud_c_esl_cond_unknown.
This routine can be called with the outcome parameter taking a value
of zero or the union (logical OR) of selected values from the set of
constants aud_c_esl_cond_success, aud_c_esl_cond_failure,
aud_c_esl_cond_denial, and aud_c_esl_cond_pending. The outcome
parameter used in the dce_aud_commit routine should take one value
from the same set of constants.
If dce_aud_start_with_uuid used a non-zero value for outcome, then
the constant used for outcome in the dce_aud_commit routine should
have been selected in the dce_aud_start_with_uuid routine.
Related Information
Routines:
dce_aud_commit
dce_aud_open
dce_aud_put_ev_info
dce_aud_start
dce_aud_start_with_pac
dce_aud_start_with_name
dce_aud_start_with_server_binding
ΓòÉΓòÉΓòÉ 3.4.35. get_event_name_from_event_number ΓòÉΓòÉΓòÉ
Purpose
Returns the event name from the event number. This routine is used by
the trail analysis and examination tools.
Format
#include <dce\audit.h>
boolean32 get_event_name_from_event_number(
unsigned32 number,
char *name);
Parameters
Input
number The 32-bit heximal event number.
Output
name The event name associated with the 32-bit event number.
Usage
The get_event_name_from_number routine returns the event (ASCII) name
of the associated 32-bit event number. This routine is used in
dce_aud_print to display the human readable form of the audit
records. This routine can also be used in any application where it is
necessary to obtain the event name from the event number.
Related Information
Routines:
get_event_number_from_event_name
ΓòÉΓòÉΓòÉ 3.4.36. get_event_number_from_event_name ΓòÉΓòÉΓòÉ
Purpose
Returns the event number from the event name. This routine is used by
the trail analysis and examination tools.
Format
#include <dce\audit.h>
boolean32 get_event_number_from_event_name(
char *name,
unsigned32 number);
Parameters
Input
name The ASCII form of the event name.
Output
number The 32-bit heximal event number associated with the
event name.
Usage
The get_event_number_from_name routine returns the 32-bit heximal
event number associated with the event name. This routine is used in
dce_aud_print to display the human readable form of the audit
records. This routine can also be used in any application where it is
necessary to obtain the event number from the event name.
Related Information
Routines:
get_event_name_from_event_number
ΓòÉΓòÉΓòÉ 3.5. The DCE Configuration Routines ΓòÉΓòÉΓòÉ
The DCE configuration routines return information based on the contents of the
local DCE configuration file, which is created during the DCE
cell-configuration or machine-configuration process. A configuration file is
located on each DCE machine; it contains the host's name, the primary name of
the cell where the host is located, and any aliases for that cell name.
The configuration routines can also be used to get some additional information
corollary to the host name, namely:
o The host's principal name
o Binding information to the host
The configuration file on machines that belong to internationalized DCE cells
also contains the path name to the code set registry object file on the host.
The Security Service component on each DCE machine must be able to find out,
by strictly local means, the machine's host name, the host machine's principal
name, and its cell name. The DCE configuration routines exist primarily to
enable Security components to do these things. But because this information
can be useful to DCE applications as well, these routines are made available
as part of the general application programming interface.
Notes Host name, as used throughout this section, refers to the DCE host name
(that is, the machine's \...\cellname\host_directory\dce_hostname entry
in the CDS namespace), and not the Domain Name Service (DNS) host name,
which can be quite different from the DCE name.
The dce_hostname is case sensitive.
See the following topics for more information:
Configuration Routines List
Configuration Notes
Configuration Files
Configuration Output
Related Information for DCE Configuration
ΓòÉΓòÉΓòÉ 3.5.1. Configuration Routines List ΓòÉΓòÉΓòÉ
The DCE configuration routines are:
dce_cf_binding_entry_from_host Returns the host binding entry name.
dce_cf_dced_entry_from_host Returns the dced entry name on a host.
dce_cf_find_name_by_key Returns a string tagged by key (this
is a lower-level utility routine that
is used by the others).
dce_cf_free_cell_aliases Frees a list of cell aliases for a
cell.
dce_cf_get_cell_aliases Returns a list of cell aliases for a
cell.
dce_cf_get_cell_name Returns the primary cell name for the
local cell.
dce_cf_get_csrgy_filename Returns the path name of the code set
registry file on a host.
dce_cf_get_host_name Returns the host name relative to a
local cell.
dce_cf_prin_name_from_host Returns the host's principal name.
dce_cf_profile_entry_from_host Returns the host's profile entry.
dce_cf_same_cell_name Indicates whether two cell names refer
to the same cell.
ΓòÉΓòÉΓòÉ 3.5.2. Configuration Notes ΓòÉΓòÉΓòÉ
The DCE 1.0 implementations of the DCE configuration routines accepts only
lines (in the configuration file) with a length of less than 1024 characters.
If a tag occurs more than once in the input, the routines recognize only the
first occurrence.
ΓòÉΓòÉΓòÉ 3.5.3. Configuration Files ΓòÉΓòÉΓòÉ
dcelocal\dce_cf.db The machine's local DCE configuration file (where dcelocal
is usually \opt\dcelocal).
The format of the configuration file is as follows.
Each of the entries is tagged with its own identifier, which must be the first
nonblank token on a line that does not begin with a # (number sign) comment
character. The second token on a line is assumed to be the name associated
with the tag that was detected in front of it.
For example, cellname and dce_hostname are tags identifying the cell name and
host name, respectively, for the machine where the configuration file is
located. A sample configuration file could have the following contents:
cellname \...\osf.org
dce_hostname hosts\brazil
which would identify the host brazil in the osf.org cell.
Text characterized by the following is ignored:
o Garbage lines; that is, lines that do not conform to the previously
described format.
o Leading and trailing spaces in lines.
o Additional tokens occurring on a line after the second token.
Only privileged users should be able to write the configuration file and
everyone should be able to read it.
ΓòÉΓòÉΓòÉ 3.5.4. Configuration Output ΓòÉΓòÉΓòÉ
The DCE configuration routines return names without global or cell-relative
prefixes, such as host_directory\dce_hostname or principalname where
host_directory is usually hosts.
However, the DCE Name Service Interface (NSI) routines require that the names
that are passed to them are expressed either in cell-relative form such as:
\.:\host_directory\dce_hostname
or as global names, with the global root prefix \...\ and the cell name, such
as:
\...\cellname\host_directory\dce_hostname
Therefore, an application must add either the cell-relative (\.:\) or correct
global (\...\cellname) prefix to any name that it receives from a DCE
configuration routine before it passes the name to an NSI routine. (All NSI
routines have names beginning with rpc_ns_.) For example, if expressed in
cell-relative form, the name host_directory\dce_hostname would become:
\.:\hosts\dce_hostname
The cell-relative form of the name principalname would be:
\.:\sec\principals\principalname
where dce_hostname and principalname are the host's name and principal name,
respectively.
ΓòÉΓòÉΓòÉ 3.5.5. Related Information for DCE Configuration ΓòÉΓòÉΓòÉ
Books:
DCE for OS/2 Warp: Administration Guide
DCE for OS/2 Warp: Administration Command Reference
ΓòÉΓòÉΓòÉ 3.5.6. dce_cf_binding_entry_from_host ΓòÉΓòÉΓòÉ
Purpose
Returns the host binding entry name.
Library
\lib\dceos2.lib
Format
#include <dce_cf.h>
public void dce_cf_binding_entry_from_host(
char *dce_hostname,
char **entry_name,
error_status_t *status);
Parameters
Input
dce_hostname Specifies the name of the host. Note that host names
are case sensitive. If NULL, the configuration file is
searched for the host name, and that name, if found, is
used.
Output
entry_name The binding entry name associated with the specified
host.
status Returns the status code from this operation. The status
code is a value that indicates whether the routine
completed successfully and if not, why not.
Possible status codes and their meanings are:
dce_cf_st_ok Operation completed successfully.
dce_cf_e_file_open File open error.
dce_cf_e_no_mem No memory available.
dce_cf_e_no_match No dce_hostname entry in the DCE
configuration file.
Usage
The dce_cf_binding_entry_from_host routine returns the binding entry
name string associated with the dce_hostname passed to it. If
dce_hostname is NULL, the binding entry name associated with the name
returned by dce_cf_get_host_name is returned.
Related Information
Routines:
dce_cf_find_name_by_key
dce_cf_get_cell_name
dce_cf_get_host_name
dce_cf_prin_name_from_host
Files:
dcelocal\dce_cf.db - The machine's local DCE configuration file
(where dcelocal is usually \opt\dcelocal).
Books:
DCE for OS/2 Warp: Administration Guide
ΓòÉΓòÉΓòÉ 3.5.7. dce_cf_dced_entry_from_host ΓòÉΓòÉΓòÉ
Purpose
Returns the dced entry name on a host.
Format
#include <dce\dce_cf.h>
void dce_cf_dced_entry_from_host(
char *dce_hostname,
char **entry_name,
error_status_t *status);
Parameters
Input
dce_hostname Specifies the name of the host. Note that host names
are case-sensitive. If this value is NULL, the value
returned by dce_cf_get_host_name is used.
Output
entry_name The dced entry name associated with the specified host.
Storage for this name is dynamically allocated.
status Returns the status code from this operation. The status
code is a value that indicates whether the routine
completed successfully and if not, why not.
Possible status codes and their meanings are:
dce_cf_st_ok Operation completed successfully.
dce_cf_e_file_open File open error.
dce_cf_e_no_mem No memory available.
dce_cf_e_no_match No dce_hostname entry in the DCE
configuration file.
Usage
The dce_cf_dced_entry_from_host routine returns the name entered into
the DCE namespace for a DCE host daemon (dced) on the host specified
by the dce_hostname parameter. If the dce_hostname parameter is NULL,
the dced name associated with the name returned by
dce_cf_get_host_name is returned. The string name is of the form
\.:\hosts\dce_hostname\config, and specifies the entry point into the
dced namespace on the host. This is the location in the DCE namespace
where dced stores the objects associated with the host services it
provides (the hostdata, srvrconf, srvrexec, secval, and keytab
services, as well as ACL editing). It is also an actual name in the
DCE namespace that you can import if you want to create your own RPC
binding to dced.
You can use the dced entry name returned by this routine as input to
the dced_binding_create routine, input to sec_acl_xxx routines, or to
rpc_ns_binding_import_xxx routines to establish a binding to a dced
host service.
If using dced_binding_create, you append a service name to the entry
returned by this routine. If using sec_acl_xxx routines, you append
the service and the object name. If using rpc_ns_binding_import_xxx,
you use only the entry returned by the routine.
You can also use the returned string to name objects that dced
maintains (for example, when editing these objects' ACLs with dcecp).
For example, the string name \.:\hosts\vineyard\config\srvrconf\dtsd
names the server configuration data for the DTS server on the host
vineyard.
Notes
Storage for entry_name is dynamically allocated and must be freed by
the caller using dce_free.
Related Information
Routines:
dce_cf_binding_entry_from_host
dce_cf_find_name_by_key
dce_cf_get_cell_name
dce_cf_get_host_name
dce_cf_prin_name_from_host
dce_free
dced_binding_create
Files:
dcelocal\dce_cf.db - The machine's local DCE configuration file
(where dcelocal is usually \opt\dcelocal).
Books:
DCE for OS/2 Warp: Application Development Guide - Core Components
DCE for OS/2 Warp: Administration Command Reference
ΓòÉΓòÉΓòÉ 3.5.8. dce_cf_find_name_by_key ΓòÉΓòÉΓòÉ
Purpose
Returns a string tagged by a character string key.
Library
\lib\dceos2.lib
Format
#include <dce_cf.h>
void dce_cf_find_name_by_key(
FILE *fp,
char *key,
char **name,
error_status_t *status);
Parameters
Input
fp A file pointer to a correctly formatted text file
opened for reading.
key A character string key that is used to find name.
Input/Output
name A pointer to a string (char **) containing the name. A
buffer is allocated by a call to malloc into which the
string is copied.
Output
status Returns the status code from this operation. The status
code is a value that indicates whether the routine
completed successfully and if not, why not.
Possible status codes and their meanings are:
dce_cf_st_ok Operation completed
successfully.
dce_cf_e_no_mem No memory available.
dce_cf_e_no_match No match for key in file.
Usage
The dce_cf_find_name_by_key routine searches a text file for the
first occurrence of a string tag identical to the string passed in
key. The tag string, in order to be found, must be the first
non-white-space string on an uncommented line. If the tag string is
found, the dce_cf_find_name_by_key routine allocates a buffer (by a
call to malloc) for the next string found on the same line as the tag
string. The routine then copies this second string into the buffer
and returns its address in the name input parameter.
The name of the DCE configuration file is in the constant
dce_cf_c_db_name; in turn, this constant is defined in the include
file dce_cf.h.
Notes
The memory for a returned name string is allocated by malloc and must
be freed using dce_free by the original caller of the configuration
routine that called dce_cf_find_name_by_key.
This routine is limited to processing lines of text whose length is
less than 1024 characters long.
Related Information
Routines:
dce_cf_binding_entry_from_host
dce_cf_get_cell_name
dce_cf_get_csrgy_filename
dce_cf_get_host_name
dce_cf_prin_name_from_host
dce_free
Files:
dcelocal\dce_cf.db - The machine's local DCE configuration file
(where dcelocal is usually \opt\dcelocal).
Books:
DCE for OS/2 Warp: Application Development Guide - Core Components.
ΓòÉΓòÉΓòÉ 3.5.9. dce_cf_free_cell_aliases ΓòÉΓòÉΓòÉ
Purpose
Frees a list of cell name aliases for the local cell.
Format
#include <dce\dce_cf.h>
void dce_cf_free_cell_aliases(
char **cell_alias_list,
error_status_t *status);
Parameters
Input
cell_alias_list The address of a cell alias list, which is a
null-terminated array of pointers to the cell alias
names for the local cell.
Output
status Returns the status code from this operation. The status
code is a value that indicates whether the routine
completed successfully and if not, why not.
Possible status codes are:
dce_cf_st_ok Operation completed
successfully.
dce_cf_e_file_open File open error.
dce_cf_e_no_mem No memory available.
dce_cf_e_no_match No match for the
cell_alias_list.
Usage
The dce_cf_free_cell_aliases routine frees the list of aliases for
the local cell that the dce_cf_get_cell_aliases routine allocated.
The routine frees the memory allocated to hold the array of pointers
to cell alias string buffers and also frees the string buffers.
Related Information
Routines:
dce_cf_get_cell_aliases
dce_cf_get_cell_name
dce_cf_get_host_name
dce_cf_prin_name_from_host
dce_cf_same_cell_name
Books:
DCE for OS/2 Warp: Application Development Guide - Core Components
DCE for OS/2 Warp: Administration Command Reference
ΓòÉΓòÉΓòÉ 3.5.10. dce_cf_get_cell_aliases ΓòÉΓòÉΓòÉ
Purpose
Returns a list of aliases for the local cell.
Format
#include <dce\dce_cf.h>
void dce_cf_get_cell_aliases(
char ***cell_alias_list,
error_status_t *status);
Parameters
Output
cell_alias_list The address of a string pointer array. This routine
sets this address to point to the address of an
allocated n ull-terminated array of pointers to the
cell alias names for the local cell. If no aliases
exist, the routine returns NULL in this parameter.
status Returns the status code from this operation. The status
code is a value that indicates whether the routine
completed successfully and if not, why not.
Possible status codes are:
dce_cf_st_ok Operation completed
successfully.
dce_cf_e_file_open File open error.
dce_cf_e_no_mem No memory available.
dce_cf_e_no_match No match for the
cell_alias_list.
Usage
The dce_cf_get_cell_aliases routine retrieves the local cell's name
aliases. If cell aliases are found, the routine returns the address
of an allocated list of cell alias names in the cell_alias_list
parameter. If no aliases exist for the cell, the routine returns
NULL.
Use the dce_cf_free_cell_aliases routine to free the memory allocated
by the dce_cf_get_cell_aliases routine.
Related Information
Routines:
dce_cf_get_cell_aliases
dce_cf_get_cell_name
dce_cf_get_host_name
dce_cf_same_cell_name
Books:
DCE for OS/2 Warp: Application Development Guide - Core Components
DCE for OS/2 Warp: Administration Command Reference
ΓòÉΓòÉΓòÉ 3.5.11. dce_cf_get_cell_name ΓòÉΓòÉΓòÉ
Purpose
Returns the primary name for the local cell.
Library
\lib\dceos2.lib
Format
#include <dce\dce_cf.h>
void dce_cf_get_cell_name(
char **cellname,
error_status_t *status );
Parameters
Input/Output
cellname The address of a string pointer. This pointer is set
by the routine to point to an allocated buffer that
contains the cell name.
Output
status Returns the status code from this operation. The status
code is a value that indicates whether the routine
completed successfully and if not, why not.
Possible status codes and their meanings are:
dce_cf_st_ok Operation successfully
completed.
dce_cf_e_file_open File open error.
dce_cf_e_no_mem No memory available.
dce_cf_e_no_match No match for cellname in
DCE configuration file.
Usage
The dce_cf_get_cell_name routine searches the DCE configuration file
for the local cell's name. If the name is found, dce_cf_get_cell_name
returns an allocated (by a call to malloc) copy of it in the cellname
input parameter.
Notes
The memory for a returned cellname is allocated by malloc. You must
use dce_free to free the allocated copy when you no longer need it.
This version of this routine is limited to processing lines of text
less than 1024 characters long.
Related Information
Routines:
dce_cf_binding_entry_from_host
dce_cf_find_name_by_key
dce_cf_get_host_name
dce_cf_get_csrgy_filename
dce_cf_prin_name_from_host
dce_free
Files:
dcelocal\dce_cf.db - The machine's local DCE configuration file
(where dcelocal is usually \opt\dcelocal).
Books:
DCE for OS/2 Warp: Administration Guide
ΓòÉΓòÉΓòÉ 3.5.12. dce_cf_get_csrgy_filename ΓòÉΓòÉΓòÉ
Purpose
Returns the path name of the code set registry file on a host.
Library
\lib\dceos2.lib
Format
#include <dce\dce_cf.h>
void dce_cf_get_csrgy_filename(
char **csrgy_filename,
error_status_t *status );
Parameters
Input/Output
csrgy_filename The address of a string pointer. This pointer is set
by the routine to point to a buffer that contains the
path name to the code set registry file.
Output
status Returns the status code from this operation. The status
code is a value that indicates whether the routine
completed successfully and if not, why not.
Possible status codes and their meanings are:
dce_cf_st_ok Operation successfully
completed.
dce_cf_e_file_open File open error.
dce_cf_e_no_mem No memory available.
Usage
The dce_cf_get_csrgy_filename routine returns the path name of a code
set registry file that has been created on a given host with the csrc
utility. DCE RPC routines for code set interoperability use this
routine when they need to locate a host's code set registry file in
order to map between unique code set identifiers and their operating
system-specific local code set names, or to obatin supported code
sets for a client or server. User-written code set interoperability
routines can also use the routine.
The dce_cf_get_csrgy_filename routine searches the DCE configuration
file for the name of the local host's code set registry file,
allocates a buffer for it (by a call to malloc), copies the name into
the buffer, and returns its address in the csrgy_filename input
parameter.
Notes
The memory for a returned name string is allocated by malloc and must
be freed by the caller of dce_cf_get_csrgy_filename by using
dce_free.
This routine is limited to processing lines of text whose length is
less than 1024 characters.
Related Information
Routines:
dce_cf_get_cell_name
dce_cf_find_name_by_key
dce_cf_get_host_name
dce_cf_prin_name_from_host
dce_cs_loc_to_rgy
dce_cs_rgy_to_loc
dce_free
Files:
dcelocal\dce_cf.db - The machine's local DCE configuration file
(where dcelocal is usually \opt\dcelocal).
Books:
DCE for OS/2 Warp: Administration Guide
ΓòÉΓòÉΓòÉ 3.5.13. dce_cf_get_host_name ΓòÉΓòÉΓòÉ
Purpose
Returns the host name relative to the local cell root.
Library
\lib\dceos2.lib
Format
#include <dce\dce_cf.h>
public void dce_cf_get_host_name(
char **dce_hostname,
error_status_t *status);
Parameters
Input/Output
dce_hostname A pointer to a string (char **) where a string
containing the name found is placed. The name string is
allocated by malloc.
Output
status Returns the status code from this operation. The status
code is a value that indicates whether the routine
completed successfully and if not, why not.
Possible status codes and their meanings are:
dce_cf_st_ok Operation successfully completed.
dce_cf_e_file_open File open error.
dce_cf_e_no_mem No memory available.
dce_cf_e_no_match No match for dce_hostname in DCE
configuration file.
Usage
The dce_cf_get_host_name routine searches the DCE configuration file
for the local host's name relative to the local cell's root. If the
name is found, dce_cf_get_host_name allocates (by a call to malloc) a
buffer for it, copies the name into the buffer, and returns its
address in the dce_hostname input parameter.
Notes
The memory for a returned name string is allocated by malloc, and
must be freed by the caller of dce_cf_get_host_name, using dce_free.
The DCE 1.0 version of this function is limited to processing lines
of text whose length is less than 1024 characters.
Related Information
Routines:
dce_cf_binding_entry_from_host
dce_cf_find_name_by_key
dce_cf_get_cell_name
dce_cf_get_csrgy_filename
dce_cf_prin_name_from_host
dce_free
Files:
dcelocal\dce_cf.db - The machine's local DCE configuration file
(where dcelocal is usually \opt\dcelocal).
Books:
DCE for OS/2 Warp: Administration Guide
ΓòÉΓòÉΓòÉ 3.5.14. dce_cf_prin_name_from_host ΓòÉΓòÉΓòÉ
Purpose
Returns the host's principal name.
Library
\lib\dceos2.lib
Format
#include <dce\dce_cf.h>
void dce_cf_prin_name_from_host(
char *dce_hostname,
char **prin_name,
error_status_t *status);
Parameters
Input
dce_hostname The name of the host. Note that host names are
case-sensitive. If NULL, the configuration file is
searched for the host name, and that name, if found, is
used.
Output
prin_name The principal name associated with the specified host.
status Returns the status code from this operation. The status
code is a value that indicates whether the routine
completed successfully and if not, why not.
Possible status codes and their meanings are:
dce_cf_st_ok Operation completed
successfully.
dce_cf_e_file_open File open error.
dce_cf_e_no_mem No memory available.
dce_cf_e_no_match No match for dce_hostname
in DCE configuration
file.
Usage
The dce_cf_prin_name_from_host routine returns the principal name
associated with the dce_hostname passed to it. If dce_hostname is
NULL, dce_cf_prin_name_from_host returns the principal name
associated with the name returned by dce_cf_get_host_name.
Related Information
Routines:
dce_cf_binding_entry_from_host
dce_cf_find_name_by_key
dce_cf_get_cell_name
dce_cf_get_host_name
dce_cf_get_csrgy_filename
Files:
dcelocal\dce_cf.db - The machine's local DCE configuration file
(where dcelocal is usually \opt\dcelocal).
Books:
DCE for OS/2 Warp: Administration Guide
ΓòÉΓòÉΓòÉ 3.5.15. dce_cf_profile_entry_from_host ΓòÉΓòÉΓòÉ
Purpose
Returns the host profile entry.
Library
\lib\dceos2.lib
Format
#include <dce\dce_cf.h>
void dce_cf_profile_entry_from_host(
char *dce_hostname,
char **prof_name,
error_status_t *status);
Parameters
Input
dce_hostname The name of the host. Note that host names are
case-sensitive. If NULL, the configuration file is
searched for the host name, and that name, if found, is
used.
Output
prof_name The profile entry associated with the specified host.
status Returns the status code from this operation. The status
code is a value that indicates whether the routine
completed successfully and if not, why not.
Possible status codes and their meanings are:
dce_cf_st_ok Operation completed
successfully.
dce_cf_e_file_open File open error.
dce_cf_e_no_mem No memory available.
dce_cf_e_no_match No match for dce_hostname
in DCE configuration
file.
Usage
The dce_cf_profile_entry_from_host routine returns the profile entry
string associated with the dce_hostname passed to it. If dce_hostname
is NULL, dce_cf_profile_entry_from_host returns the profile entry
associated with the name returned by dce_cf_get_host_name.
Related Information
Routines:
dce_cf_binding_entry_from_host
dce_cf_find_name_by_key
dce_cf_get_cell_name
dce_cf_get_host_name
dce_cf_prin_name_from_host
Files:
dcelocal\dce_cf.db - The machine's local DCE configuration file
(where dcelocal is usually \opt\dcelocal).
Books:
DCE for OS/2 Warp: Administration Guide
ΓòÉΓòÉΓòÉ 3.5.16. dce_cf_same_cell_name ΓòÉΓòÉΓòÉ
Purpose
Indicates whether two cell names refer to the same cell.
Format
#include <dce\dce_cf.h>
void dce_cf_same_cell_name(
char *cell_name1,
char *cell_name2,
boolean result,
error_status_t *status);
Parameters
Input
cell_name1 A character string that specifies the name of a cell.
cell_name2 A character string that specifies the name of a cell to
compare with cell_name1. If this value is NULL, the
routine determines whether the cell name specified in
cell_name1 is the name of the local cell.
Output
result A boolean value that indicates whether the specified
cell names match, when two cell names are given, and
indicates whether the specified cell name is the name
of the local cell, when only one cell name is given. A
value of TRUE indicates that the cell names refer to
the same cell.
status Returns the status code from this operation. On
successful completion, the routine returns
dce_cf_st_ok. Otherwise, the routine returns
dce_cf_e_no_match.
Usage
The dce_cf_same_cell_name routine, when given the names of two cells
as input parameters, compares the cell names to determine whether
they refer to the same cell. The result parameter is set to TRUE if
they do, and to FALSE if they do not.
If only one cell name is specified as an input parameter, the
dce_cf_same_cell_name routine determines whether the specified cell
name is the same as the local cell's primary name (which it retrieves
by calling dce_cf_get_cell_name). You can use the routine in this way
to determine whether a given cell name is the primary name of your
local cell.
Related Information
Routines:
dce_cf_free_cell_aliases
dce_cf_get_cell_aliases
dce_cf_get_cell_name
Books:
DCE for OS/2 Warp: Application Development Guide - Core Components
DCE for OS/2 Warp: Administration Command Reference
ΓòÉΓòÉΓòÉ 3.6. The DCE Backing Store Interface ΓòÉΓòÉΓòÉ
The DCE backing store interface allows you to maintain typed data between
program invocations. For example, you can store application-specific
configuration data in a backing store, and then retrieve it from the backing
store when the application restarts. The backing store routines can be used in
servers, in clients, or in standalone programs that do not involve remote
procedure calls (RPC). A program can have more than one backing store open at
the same time.
Sometimes the backing store is called a database. For instance, the associated
IDL file is dce\database.idl, and the name of the backing store routines begin
with dce_db_. The backing store is, however, not a full-fledged database in the
conventional sense, and it has no support for SQL or for any other query
system.
See the following subtopics for more information:
Backing Store Data
Encoding and Decoding in the Backing Store
Memory Allocation
The Backing Store Routines
Backing Store Data Types and Structures
Backing Store Notes
Backing Store Related Information
ΓòÉΓòÉΓòÉ 3.6.1. Backing Store Data ΓòÉΓòÉΓòÉ
The backing store interface provides for the tagged storage and retrieval of
typed data. The tag (or retrieval key) can be either a UUID or a standard C
string. For a specific backing store, the data type must be specified at
compile time, and is established through the IDL Encoding Services. Each
backing store can contain a single data type only.
Each data item (also called a data object or data record) consists of the data
stored by a single call to a storage routine (dce_db_store,
dce_db_store_by_name, or dce_db_store_by_uuid). Optionally, data items can have
headers. If a backing store has been created to use headers, every data item
must have a header. For a description of the data item header, see Backing
Store Data Types and Structures.
ΓòÉΓòÉΓòÉ 3.6.2. Encoding and Decoding in the Backing Store ΓòÉΓòÉΓòÉ
When an RPC sends data between a client and a server, it serializes the user's
data structures by using the IDL Encoding Services (ES), described in the DCE
for OS/2 Warp: Application Development Guide - Core Components.
The backing store uses this same serialization scheme for encoding and
decoding, informally called pickling, when storing data structures to disk. The
IDL compiler, idl, writes the routine that encodes and decodes the data. This
routine is passed to dce_db_open, remembered in the handle, and used by these
store and fetch routines:
dce_db_fetch
dce_db_fetch_by_name
dce_db_fetch_by_uuid
dce_db_header_fetch
dce_db_store
dce_db_store_by_name
dce_db_store_by_uuid
ΓòÉΓòÉΓòÉ 3.6.3. Memory Allocation ΓòÉΓòÉΓòÉ
When fetching data, the encoding services (ES) allocate memory for the data
structures that are returned. These services accept a structure and use
rpc_sm_allocate to provide additional memory needed to hold the data.
The backing store library does not know what memory has been allocated, and
therefore cannot free it. For fetch calls that are made from a server stub,
this is not a problem, because the memory is freed automatically when the
server call terminates. For fetch calls that are made from a non-server, the
programmer is responsible for freeing the memory.
Programs that call the fetch or store routines, such as dce_db_fetch, outside
of a server operation (for instance, if a server does some backing store
initialization, or in a standalone program) must call rpc_sm_enable_allocate
first.
ΓòÉΓòÉΓòÉ 3.6.4. The Backing Store Routines ΓòÉΓòÉΓòÉ
Many of the backing store routines occur in three versions: plain, by name, and
by UUID. The plain version works with backing stores that were created to be
indexed either by name or by UUID, but the restricted versions accept the
matching type only. It is advantageous to use the restricted versions when
they are appropriate, because they provide type-checking by the compiler, as
well as visual clarity of purpose.
The backing store routines, listed in alphabetical order, are:
dce_db_close Frees the handle returned by dce_db_open. It
closes any open files and releases all other
resources associated with the backing store.
dce_db_delete Deletes an item from a backing store that is
indexed by name or by UUID. The key type must
match the flag that was used in dce_db_open.
dce_db_delete_by_name Deletes an item only from a backing store that
is indexed by name.
dce_db_delete_by_uuid Deletes an item only from a backing store that
is indexed by UUID.
dce_db_fetch Retrieves data from a backing store that is
indexed by name or by UUID. The key type must
match the flag that was used in dce_db_open.
dce_db_fetch_by_name Retrieves data only from a backing store that
is indexed by name.
dce_db_fetch_by_uuid Retrieves data only from a backing store that
is indexed by UUID.
dce_db_free Releases the data supplied from a backing
store.
dce_db_header_fetch Retrieves a header from a backing store.
dce_db_inq_count Returns the number of items in a backing
store.
dce_db_iter_done Terminates an iteration operation initiated by
dce_db_iter_start. It should be called when
iteration is done.
dce_db_iter_next Returns the key for the next item from a
backing store that is indexed by name or by
UUID. The db_s_no_more return value indicates
that there are no more items.
dce_db_iter_next_by_name Returns the key for the next item only from a
backing store that is indexed by name. The
db_s_no_more return value indicates that there
are no more items.
dce_db_iter_next_by_uuid Returns the key for the next item only from a
backing store that is indexed by UUID. The
db_s_no_more return value indicates that there
are no more items.
dce_db_iter_start Prepares for the start of iteration.
dce_db_lock Locks a backing store. A lock is associated
with an open backing store's handle. The
storage routines dce_db_store,
dce_db_store_by_name, and dce_db_store_by_uuid
all acquire the lock before updating.
dce_db_open Creates a new backing store or opens an
existing one. The backing store is identified
by a filename. Flags allow you to:
o Create a new backing store, or open an
existing one.
o Create a new backing store indexed by
name, or indexed by UUID.
o Open an existing backing store
read/write, or read-only.
o Use the standard data item header, or
not.
The routine returns a handle that subsequent
routines can use to reference the opened
backing store.
dce_db_std_header_init Initializes a standard backing store header
retrieved by dce_db_header_fetch. It only
places the values into the header, and does
not write into the backing store.
dce_db_store Stores a data item into a backing store that
is indexed by name or by UUID. The key type
must match the flag that was used in
dce_db_open.
dce_db_store_by_name Stores a data item only into a backing store
that is indexed by name.
dce_db_store_by_uuid Stores a data item only into a backing store
that is indexed by UUID.
dce_db_unlock Unlocks a backing store.
ΓòÉΓòÉΓòÉ 3.6.5. Backing Store Data Types and Structures ΓòÉΓòÉΓòÉ
dce_db_handle_t An opaque handle to a backing store. Use dce_db_open
to acquire the handle.
dce_db_header_t The data structure that defines a standard backing
store header for data items. Use dce_db_header_fetch
to retrieve it from a backing store and
dce_db_std_header_init to initialize it.
dce_db_convert_func_t An opaque pointer to the data conversion routine to
be used when storing or retrieving data. This routine
is specified as an argument to dce_db_open at open
time. It converts between native format and on-disk
(serialized) format. It is generated from the IDL
file by the IDL compiler.
ΓòÉΓòÉΓòÉ 3.6.6. Backing Store Notes ΓòÉΓòÉΓòÉ
You cannot use conformant arrays in objects stored to a backing store. This is
because the idl-generated code that encodes (pickles) the structure has no way
to predict or detect the size of the array. When the object is fetched, there
may be insufficient space provided for the structure, and the array's data
destroys whatever is in memory after the structure.
ΓòÉΓòÉΓòÉ 3.6.7. Backing Store Related Information ΓòÉΓòÉΓòÉ
Files:
database.idl
database.h
db.h
dbif.h
Books:
DCE for OS/2 Warp: Application Development Guide - Core Components
ΓòÉΓòÉΓòÉ 3.6.8. dce_db_close ΓòÉΓòÉΓòÉ
Purpose
Closes an open backing store.
Format
#include <dce\dce.h>
#include <dce\dbif.h>
void dce_db_close(
dce_db_handle_t *handle,
error_status_t *status);
Parameters
Input
handle A handle identifying the backing store to be closed.
Output
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns an error.
Usage
The dce_db_close routine closes a backing store that was opened by
dce_db_open. It also frees the storage used by the handle and sets
the handle value to NULL.
Related Information
Routines:
dce_db_open
ΓòÉΓòÉΓòÉ 3.6.9. dce_db_delete ΓòÉΓòÉΓòÉ
Purpose
Deletes an item from a backing store.
Format
#include <dce\dce.h>
#include <dce\dbif.h>
void dce_db_delete(
dce_db_handle_t handle,
void *key,
error_status_t *status);
Parameters
Input
handle A handle returned from dce_db_open that identifies the
backing store being used.
key A pointer to a string or UUID that is the key to the
item in the backing store. The data type of key must
match the key method that was selected in the flags
parameter to dce_db_open when the backing store was
created.
Output
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns one of the following errors:
db_s_del_failed The deletion did not occur. The
global variable errno may indicate further
information about the error.
db_s_bad_index_type The type of the key parameter
is wrong, or the backing store is not
organized by name or by UUID.
db_s_iter_not_allowed The routine was called while
an iteration, begun by dce_db_iter_start, was
in progress. Deletion is not allowed during
iteration.
Usage
The dce_db_delete routine deletes an item from the backing store that
is identified by the handle parameter, which was obtained from
dce_db_open. It is a general deletion routine, which interprets the
key parameter according to the type of index with which the backing
store was created.
Related Information
Routines:
dce_db_delete_by_name
dce_db_delete_by_uuid
dce_db_open
ΓòÉΓòÉΓòÉ 3.6.10. dce_db_delete_by_name ΓòÉΓòÉΓòÉ
Purpose
Deletes an item from a string-indexed backing store.
Format
#include <dce\dce.h>
#include <dce\dbif.h>
void dce_db_delete_by_name(
dce_db_handle_t handle,
char *key,
error_status_t *status);
Parameters
Input
handle A handle returned from dce_db_open that identifies the
backing store being used.
key A NULL-terminated string that is the key to the item in
the backing store.
Output
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns one of the following errors:
db_s_del_failed The deletion did not occur. The
global variable errno might indicate further
information about the error.
db_s_bad_index_type The backing store is not
indexed by name.
db_s_iter_not_allowed The routine was called while
an iteration, begun by dce_db_iter_start, was
in progress. Deletion is not allowed during
iteration.
Usage
The dce_db_delete_by_name routine deletes an item from the backing
store that is identified by the handle parameter, which was obtained
from dce_db_open. It is a specialized deletion routine for backing
stores that are indexed by name, as selected by the
db_c_index_by_name bit in the flags parameter of the dce_db_open
routine when the backing store was created.
Related Information
Routines:
dce_db_delete
dce_db_delete_by_uuid
dce_db_open
ΓòÉΓòÉΓòÉ 3.6.11. dce_db_delete_by_uuid ΓòÉΓòÉΓòÉ
Purpose
Deletes an item from a UUID-indexed backing store.
Format
#include <dce\dce.h>
#include <dce\dbif.h>
void dce_db_delete_by_uuid(
dce_db_handle_t handle,
uuid_t *key,
error_status_t *status);
Parameters
Input
handle A handle returned from dce_db_open that identifies the
backing store being used.
key A pointer to a UUID that is the key to the item in the
backing store.
Output
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns one of the following errors:
db_s_del_failed The deletion did not occur. The
global variable errno might indicate further
information about the error.
db_s_bad_index_type The backing store is not
indexed by UUID.
db_s_iter_not_allowed The routine was called while
an iteration, begun by dce_db_iter_start, was
in progress. Deletion is not allowed during
iteration.
Usage
The dce_db_delete_by_uuid routine deletes an item from the backing
store that is identified by the handle parameter, which was obtained
from dce_db_open. It is a specialized deletion routine for backing
stores that are indexed by UUID, as selected by the
db_c_index_by_uuid bit in the flags parameter of the dce_db_open
routine when the backing store was created.
Related Information
Routines:
dce_db_delete
dce_db_delete_by_name
dce_db_open
ΓòÉΓòÉΓòÉ 3.6.12. dce_db_fetch ΓòÉΓòÉΓòÉ
Purpose
Retrieves data from a backing store.
Format
#include <dce\dce.h>
#include <dce\dbif.h>
void dce_db_fetch(
dce_db_handle_t handle,
void *key,
void *data,
error_status_t *status);
Parameters
Input
handle A handle returned from dce_db_open that identifies the
backing store being used.
key A string or UUID that is the key to the item in the
backing store. The data type of key must match the key
method that was selected in the flags parameter of the
dce_db_open routine when the backing store was created.
Output
data A pointer to the returned data.
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns one of the following errors:
db_s_key_not_found The specified key was not found
in the backing store. (This circumstance is
not necessarily an error.)
db_s_bad_index_type The type of the key parameter
is wrong, or else the backing store is not
organized by name or by UUID.
Usage
The dce_db_fetch routine retrieves data from the backing store that
is identified by the handle parameter, which was obtained from
dce_db_open. It is a general retrieval routine, interpreting the key
parameter according to the type of index with which the backing store
was created.
The data parameter is shown as a pointer to an arbitrary data type.
In actual use it is the address of the backing-store-specific data
type.
Notes
After calling dce_db_fetch, it might be necessary to free some memory
if the call was made outside of an RPC on the server side. This is
done by calling rpc_sm_client_free. (Inside an RPC, the memory is
allocated through rpc_sm_allocate and is automatically freed.)
Programs that call dce_db_fetch outside of a server operation (for
instance, if a server does some backing store initialization or in a
standalone program) must call rpc_sm_enable_allocate first. Indeed,
every thread that calls dce_db_fetch must do rpc_sm_allocate, but in
the server side of an RPC, this is already done.
Related Information
Routines:
dce_db_fetch_by_name
dce_db_fetch_by_uuid
dce_db_free
dce_db_open
ΓòÉΓòÉΓòÉ 3.6.13. dce_db_fetch_by_name ΓòÉΓòÉΓòÉ
Purpose
Retrieves data from a string-indexed backing store.
Format
#include <dce\dce.h>
#include <dce\dbif.h>
void dce_db_fetch_by_name(
dce_db_handle_t handle,
char *key,
void *data,
error_status_t *status);
Parameters
Input
handle A handle, returned from dce_db_open, that identifies
the backing store being used.
key A null-terminated string that is the key to the item in
the backing store.
Output
data A pointer to the returned data.
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns one of the following errors:
db_s_key_not_found The specified key was not found
in the backing store. (This circumstance is
not necessarily an error.)
db_s_bad_index_type The backing store is not
indexed by name.
Usage
The dce_db_fetch_by_name routine retrieves data from the
string-indexed backing store that is identified by the handle
parameter, which was obtained from dce_db_open. It is a specialized
retrieval routine for backing stores that are indexed by string, as
selected by the db_c_index_by_name bit in the flags parameter of the
dce_db_open routine when the backing store was created.
The data parameter is shown as a pointer to an arbitrary data type.
In actual use, it is the address of the backing-store-specific data
type.
Notes
After calling dce_db_fetch_by_name, it might be necessary to free
some memory if the call was made outside of an RPC on the server
side. This is done by calling rpc_sm_client_free. (Inside an RPC, the
memory is allocated through rpc_sm_allocate and is automatically
freed.)
Programs that call dce_db_fetch_by_name outside of a server operation
(for instance, if a server does some backing store initialization or
in a standalone program) must call rpc_sm_enable_allocate first.
Indeed, every thread that calls dce_db_fetch_by_name must do
rpc_sm_allocate, but in the server side of an RPC, this is already
done.
Examples
This example shows the use of the user-defined data type as the
my_data parameter.
extern dce_db_handle_t db_h;
uuid_t key_uuid;
my_data_type_t my_data;
error_status_t status;
/* set key_uuid = xxx; */
dce_db_fetch_by_name(db_h, &key_uuid, &my_data, &status);
Related Information
Routines:
dce_db_fetch
dce_db_fetch_by_uuid
dce_db_free
dce_db_open
ΓòÉΓòÉΓòÉ 3.6.14. dce_db_fetch_by_uuid ΓòÉΓòÉΓòÉ
Purpose
Retrieves data from a UUID-indexed backing store.
Format
#include <dce\dce.h>
#include <dce\dbif.h>
void dce_db_fetch_by_uuid(
dce_db_handle_t handle,
uuid_t *key,
void *data,
error_status_t *status);
Parameters
Input
handle A handle, returned from dce_db_open, that identifies
the backing store being used.
key A UUID that is the key to the item in the backing
store.
Output
data A pointer to the returned data.
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns one of the following errors:
db_s_key_not_found The specified key was not found
in the backing store. (This circumstance is
not necessarily an error.)
db_s_bad_index_type The backing store is not
indexed by UUID.
Usage
The dce_db_fetch_by_uuid routine retrieves data from the UUID-indexed
backing store that is identified by the handle parameter, which was
obtained from dce_db_open. It is a specialized retrieval routine for
backing stores that are indexed by UUID, as selected by the
db_c_index_by_uuid bit in the flags parameter of the dce_db_open
routine when the backing store was created.
The data parameter is shown as a pointer to an arbitrary data type.
In actual use, it is the address of the backing-store-specific data
type.
Notes
After calling dce_db_fetch_by_uuid, it may be necessary to free some
memory if the call was made outside of an RPC on the server side.
This is done by calling rpc_sm_client_free. (Inside an RPC, the
memory is allocated through rpc_sm_allocate and is automatically
freed.)
Programs that call dce_db_fetch_by_uuid outside of a server operation
(for instance, if a server does some backing store initialization or
in a standalone program) must call rpc_sm_enable_allocate first.
Indeed, every thread that calls dce_db_fetch_by_uuid must do
rpc_sm_allocate, but in the server side of an RPC, this is already
done.
Examples
This example shows the use of the user-defined data type as the data
parameter.
extern dce_db_handle_t db_h;
uuid_t key_uuid;
my_data_type_t my_data;
error_status_t status;
/* set key_uuid = xxx; */
dce_db_fetch_by_uuid(db_h, &key_uuid, &my_data, &status);
Related Information
Routines:
dce_db_fetch
dce_db_fetch_by_name
dce_db_free
dce_db_open
rpc_sm_enable_allocate
ΓòÉΓòÉΓòÉ 3.6.15. dce_db_free ΓòÉΓòÉΓòÉ
Purpose
Releases the data supplied from a backing store.
Format
#include <dce\dce.h>
#include <dce\dbif.h>
void dce_db_free(
dce_db_handle_t handle,
void *data,
error_status_t *status);
Parameters
Input
handle A handle, returned from dce_db_open, that identifies
the backing store being used.
data The data area to be released.
Output
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns an error.
Usage
The dce_db_free routine is designed to free the data area previously
returned by a call to dce_db_fetch, dce_db_fetch_by_name, or
dce_db_fetch_by_uuid.
Notes
In the current implementation, the dce_db_free routine does not
perform any action. For servers that run properly this is of little
consequence, because their allocated memory is automatically cleaned
up when a remote procedure call finishes. For completeness, and for
compatibility with future releases, the use of dce_db_free is
recommended.
Related Information
Routines:
dce_db_fetch
dce_db_fetch_by_name
dce_db_fetch_by_uuid
ΓòÉΓòÉΓòÉ 3.6.16. dce_db_header_fetch ΓòÉΓòÉΓòÉ
Purpose
Retrieves the header from a backing store.
Format
#include <dce\dce.h>
#include <dce\dbif.h>
void dce_db_header_fetch(
dce_db_handle_t handle,
void *key,
dce_db_header_t *hdr,
error_status_t *status);
Parameters
Input
handle A handle, returned from dce_db_open, that identifies
the backing store being used.
key A string or UUID that is the backing store key.
Output
hdr A pointer to a caller-supplied header structure to be
filled in by the library.
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns db_s_key_not_found.
Usage
The dce_db_header_fetch routine returns a pointer to a copy of the
header of the object in the backing store that is identified by the
handle parameter, which was obtained from dce_db_open. The key
parameter is interpreted according to the type of index with which
the backing store was created.
The hdr parameter is shown as a pointer to an arbitrary data type. In
actual use it is the address of the backing-store-specific data type.
Notes
The dce_db_header_fetch routine returns a pointer that must be freed
by the caller using dce_free.
Related Information
Routines:
dce_db_fetch
dce_db_std_header_init
dce_free
ΓòÉΓòÉΓòÉ 3.6.17. dce_db_inq_count ΓòÉΓòÉΓòÉ
Purpose
Returns the number of items in a backing store.
Format
#include <dce\dce.h>
#include <dce\dbif.h>
void dce_db_inq_count(
dce_db_handle_t handle,
unsigned32 *count,
error_status_t *status);
Parameters
Input
handle A handle, returned from dce_db_open, that identifies
the backing store being used.
Output
count A pointer to the number of items in the backing store.
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns db_s_iter_not_allowed, which
means the routine was called while an iteration, begun
by dce_db_iter_start, was in progress. Determining the
count is not allowed during iteration.
Usage
The dce_db_inq_count routine returns the number of items in the
backing store that is identified by the handle parameter, which was
obtained from dce_db_open. It performs identically on backing stores
that are indexed by UUID and those that are indexed by string. The
count of items can be helpful when iterating through a backing store.
Related Information
Routines:
dce_db_iter_next
ΓòÉΓòÉΓòÉ 3.6.18. dce_db_iter_done ΓòÉΓòÉΓòÉ
Purpose
Frees the state associated with iteration.
Format
#include <dce\dce.h>
#include <dce\dbif.h>
void dce_db_iter_done(
dce_db_handle_t handle,
error_status_t *status);
Parameters
Input
handle A handle returned from dce_db_open that identifies the
backing store being used.
Output
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Usage
The dce_db_iter_done routine frees the state that permits iteration.
It should be called after an iteration through a backing store is
finished.
The iteration state is established by dce_db_iter_start. The routines
for performing iteration over the items are dce_db_iter_next,
dce_db_iter_next_by_name, and dce_db_iter_next_by_uuid.
Related Information
Routines:
dce_db_iter_next
dce_db_iter_next_by_name
dce_db_iter_next_by_uuid
dce_db_iter_start
ΓòÉΓòÉΓòÉ 3.6.19. dce_db_iter_next ΓòÉΓòÉΓòÉ
Purpose
Returns the next key from a backing store during iteration.
Format
#include <dce\dce.h>
#include <dce\dbif.h>
void dce_db_iter_next(
dce_db_handle_t handle,
void **key,
error_status_t *status);
Parameters
Input
handle A handle, returned from dce_db_open, that identifies
the backing store being used.
Output
key A pointer to the string or UUID that is the key to the
item in the backing store.
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns db_s_no_more, which indicates
that all the keys in the backing store have been
accessed; there are no more iterations remaining to be
done.
Usage
The dce_db_iter_next routine retrieves the next key from the backing
store that is identified by the handle parameter. An iterator
established by the dce_db_iter_start routine maintains the identity
of the current key. Use one of the dce_db_fetch routines to retrieve
the actual data.
The iteration routines scan sequentially through a backing store, in
no particular order. The dce_db_iter_start routine initializes the
process, a dce_db_iter_next routine retrieves successive keys, for
which the data can be retrieved with dce_db_fetch, and the
dce_db_iter_done routine finishes the process. The iteration can also
use the dce_db_iter_next_by_name and dce_db_iter_next_by_uuid
routines; the fetching can use the dce_db_fetch_by_name and
dce_db_fetch_by_uuid routines.
The iteration routine returns a pointer to a private space associated
with the handle. Each call to the iteration routine reuses this
space, instead of using allocated space.
Related Information
Routines:
dce_db_fetch
dce_db_fetch_by_name
dce_db_fetch_by_uuid
dce_db_iter_done
dce_db_iter_next_by_name
dce_db_iter_next_by_uuid
dce_db_iter_start
dce_db_open
ΓòÉΓòÉΓòÉ 3.6.20. dce_db_iter_next_by_name ΓòÉΓòÉΓòÉ
Purpose
Returns the next key from a backing store indexed by string during
iteration.
Format
#include <dce\dce.h>
#include <dce\dbif.h>
void dce_db_iter_next_by_name(
dce_db_handle_t handle,
char **key,
error_status_t *status);
Parameters
Input
handle A handle returned from dce_db_open that identifies the
backing store being used.
Output
key The string that is the key to the item in the backing
store.
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns db_s_no_more, which indicates
that all the keys in the backing store have been
accessed; there are no more iterations remaining to be
done.
Usage
The dce_db_iter_next_by_name routine retrieves the next key from the
backing store that is identified by the handle parameter. An
iterator established by the dce_db_iter_start routine maintains the
identity of the current key. Use the dce_db_fetch_by_name routine to
retrieve the actual data.
This iteration routine is the same as dce_db_iter_next, except that
it only works with backing stores indexed by name, and returns an
error if the backing store index is the wrong type.
The iteration routine returns a pointer to a private space associated
with the handle. Each call to the iteration routine reuses this
space, instead of using allocated space.
Related Information
Routines:
dce_db_fetch_by_uuid
dce_db_iter_done
dce_db_iter_next
dce_db_iter_next_by_uuid
dce_db_iter_start
ΓòÉΓòÉΓòÉ 3.6.21. dce_db_iter_next_by_uuid ΓòÉΓòÉΓòÉ
Purpose
During iteration, returns the next key from a backing store indexed
by UUID.
Format
#include <dce\dce.h>
#include <dce\dbif.h>
void dce_db_iter_next_by_uuid(
dce_db_handle_t handle,
uuid_t **key,
error_status_t *status);
Parameters
Input
handle A handle, returned from dce_db_open, that identifies
the backing store being used.
Output
key The UUID that is the key to the item in the backing
store.
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns an error.
Usage
The dce_db_iter_next_by_uuid routine retrieves the next key from the
backing store that is identified by the handle parameter. An iterator
established by the dce_db_iter_start routine maintains the identity
of the current key. Use the dce_db_fetch_by_uuid routine to retrieve
the actual data.
This iteration routine is the same as dce_db_iter_next, except that
it only works with backing stores indexed by UUID, and returns an
error if the backing store index is the wrong type.
The iteration routine returns a pointer to a private space associated
with the handle. Each call to the iteration routine reuses this
space, instead of using allocated space.
Related Information
Routines:
dce_db_fetch_by_uuid
dce_db_iter_done
dce_db_iter_next
dce_db_iter_next_by_name
dce_db_iter_start
ΓòÉΓòÉΓòÉ 3.6.22. dce_db_iter_start ΓòÉΓòÉΓòÉ
Purpose
Prepares a backing store for iteration.
Format
#include <dce\dce.h>
#include <dce\dbif.h>
void dce_db_iter_start(
dce_db_handle_t handle,
error_status_t *status);
Parameters
Input
handle A handle, returned from dce_db_open, that identifies
the backing store being used.
Output
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns db_s_iter_not_allowed, which
indicates that the routine was called while an
iteration was already in progress. The concept of
nested iterations is not supported.
Usage
The dce_db_iter_start routine prepares the backing store that is
identified by the handle parameter for iterative retrieval of all its
keys in succession.
A given handle can support only a single instance of iteration at one
time.
To avoid the possibility that another thread writes to the backing
store during an iteration, always use the dce_db_lock routine before
calling dce_db_iter_start.
Related Information
Routines:
dce_db_iter_done
dce_db_iter_next
dce_db_iter_next_by_name
dce_db_iter_next_by_uuid
dce_db_lock
dce_db_open
dce_db_unlock
ΓòÉΓòÉΓòÉ 3.6.23. dce_db_lock ΓòÉΓòÉΓòÉ
Purpose
Applies an advisory lock on a backing store.
Format
#include <dce\dce.h>
#include <dce\dbif.h>
void dce_db_lock(
dce_db_handle_t handle,
error_status_t *status);
Parameters
Input
handle A handle, returned from dce_db_open, that identifies
the backing store being used.
Output
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns db_s_already_locked, which
indicates that an attempt was made to lock a backing
store, but it was already locked.
Usage
The dce_db_lock routine acquires the lock associated with the handle.
There is an advisory lock associated with each handle. The routines
for storing and deleting backing stores apply the lock before
updating a backing store. This routine provides a means to apply the
lock for other purposes, such as iteration.
Advisory locks allow cooperating threads to perform consistent
operations on backing stores, but do not guarantee consistency; that
is, threads can still access backing stores without using advisory
locks, possibly resulting in inconsistencies.
Related Information
Routines:
dce_db_delete
dce_db_delete_by_name
dce_db_delete_by_uuid
dce_db_store
dce_db_store_by_name
dce_db_store_by_uuid
dce_db_unlock
ΓòÉΓòÉΓòÉ 3.6.24. dce_db_open ΓòÉΓòÉΓòÉ
Purpose
Opens an existing backing store or creates a new one.
Format
#include <dce\dce.h>
#include <dce\dbif.h>
void dce_db_open(
const char *name,
const char *backend_type,
unsigned32 flags,
dce_db_convert_func_t convert,
dce_db_handle_t *handle,
error_status_t *status);
Parameters
Input
name The file name of the backing store to be opened or
created.
backend_type Either of the strings bsd4.4-hash or bsd4.4-btree, or a
null pointer, which defaults to hash. This parameter
specifies the backing store backend type for licensees
adding multiple backends.
flags The manner of opening, as specified by any of the
following bits:
db_c_index_by_name The backing store is to be
indexed by name. Either this or
db_c_index_by_uuid, but not both, must be
selected.
db_c_index_by_uuid The backing store is to be
indexed by UUID. Either this or
db_c_index_by_name, but not both, must be
selected.
db_c_std_header The first field of each item
(which is defined as a union in
dce_db_header_t) is the standard backing
store header, with the case dce_db_header_std
selected. If you select db_c_std_header, you
cannot select db_c_acl_uuid_header. If you do
not select a header flag, no header is used.
db_c_acl_uuid_header The first field of each item
(the union) is an ACL UUID, with the case
dce_db_header_acl_uuid selected. If you
select db_c_acl_uuid_header, you cannot
select db_c_std_header. If you do not select
a header flag, no header is used.
db_c_readonly An existing backing store is to be
opened in read-only mode. Read/write mode is
the default.
db_c_create Creates an empty backing store if one
of the given name does not already exist. It
is an error to try to create an existing
backing store.
convert The routine, generated by the IDL compiler, that is
called to perform serialization.
Output
handle A pointer to a handle that identifies the backing store
being used.
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns one of the following errors:
db_s_bad_index_type The index type in flags is
specified neither by name nor by UUID, or
else it is specified as both.
db_s_bad_header_type The header type in flags is
specified as both standard header and ACL
header.
db_s_index_type_mismatch An existing backing store
was opened with the wrong index type.
db_s_open_already_exists The backing store file
specified for creation already exists.
db_s_no_name_specified No file name is specified.
db_s_open_failed_eacces The server does not have
permission to open the backing store file.
db_s_open_failed_enoent The specified directory or
backing store file was not found.
db_s_open_failed The underlying database-open
procedure failed. The global variable errno
may provide more specific information.
Usage
The dce_db_open routine opens the specified backing store. The flags
parameter must specify whether the backing store is to be indexed by
name or by UUID. If all server objects have entries in the CDS
namespace, it is probably best to use a UUID index. If the server
provides a junction or another name-based lookup operation, then it
is probably best to use a name index.
The IDL code in \usr\include\dce\database.idl defines the backing
store header (selected by the flags parameter) that is placed on each
item, the possible header types, and the form of the routine for
serializing headers.
Notes
Backing stores are also called databases. For instance, the
associated IDL header is dce\database.idl, and the name of the
backing store routines begin with dce_db_. Nevertheless, backing
stores are not databases in the conventional sense and have no
support for SQL or for any other query system.
If a backing store database is opened several times, whether by the
same application or by different applications, updates made to the
database by one handle cannot be seen by other handles.
Examples
Standardized use of the backing store library is encouraged. The
following code is the skeleton IDL interface for a server's backing
store:
interface XXX_db
{
import "dce\database.idl";
typedef XXX_data_s_t {
dce_db_header_t header;
/* server-specific data */
} XXX_data_t;
void XXX_data_convert(
[in] handle_t h,
[in, out] XXX_data_t *data,
[out] error_status_t *st
);
}
This interface should be compiled with the following ACF:
interface XXX_db
{
[encode, decode] XXX_data_convert();
}
A typical call to dce_db_open, using the preceding IDL example, would
be:
dce_db_open("XXX_db", NULL,
db_c_std_header | db_c_index_by_uuid,
(dce_db_convert_func_t)XXX_data_convert,
&handle, &st);
Related Information
Routines:
dce_db_close
ΓòÉΓòÉΓòÉ 3.6.25. dce_db_std_header_init ΓòÉΓòÉΓòÉ
Purpose
Initializes a standard backing store header.
Format
#include <dce\dce.h>
#include <dce\dbif.h>
void dce_db_std_header_init(
dce_db_handle_t handle,
dce_db_header_t *hdr,
uuid_t *uuid,
uuid_t *acl_uuid,
uuid_t *def_object_acl,
uuid_t *def_container_acl,
unsigned32 ref_count,
error_status_t *status);
Parameters
Input
handle A handle, returned from dce_db_open, that identifies
the backing store being used.
hdr Pointer to the object header part of the users'
structure.
uuid The UUID to be placed into the header. This parameter
can be NULL.
acl_uuid The UUID of the ACL protecting this object, to be
placed into the header. This parameter can be NULL.
def_object_acl The UUID of the default object ACL, to be placed into
the header. This parameter can be NULL.
def_container_acl The UUID of the default container ACL, to be placed
into the header. This parameter can be NULL.
ref_count The reference count to be placed into the header.
Output
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns db_s_bad_header_type, which
indicates that the header type is not
dce_db_header_std.
Usage
The dce_db_std_header_init routine initializes the fields of the
standard header for a data object whose backing store is identified
by the handle parameter. The fields are only set in memory and should
be stored to the backing store by one of the store routines. The
handle was obtained from dce_db_open, which must have been called
with the db_c_std_header flag.
Related Information
Routines:
dce_db_header_fetch
dce_db_open
ΓòÉΓòÉΓòÉ 3.6.26. dce_db_store ΓòÉΓòÉΓòÉ
Purpose
Stores data into a backing store.
Format
#include <dce\dce.h>
#include <dce\dbif.h>
void dce_db_store(
dce_db_handle_t handle,
void *key,
void *data,
error_status_t *status);
Parameters
Input
handle A handle, returned from dce_db_open, that identifies
the backing store being used.
key A string or UUID that is the backing store key. The
datatype of key must match the key method that was
selected in the flags parameter of the dce_db_open
routine when the backing store was created.
data A pointer to the data structure to be stored.
Output
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns one of the following errors:
db_s_bad_index_type The type of the key parameter
is wrong, or else the backing store is not by
name or by UUID.
db_s_readonly The backing store was opened with
the db_c_readonly flag, and cannot be written
to.
db_s_store_failed The data could not be stored
into the backing store for some reason. The
global variable errno may contain more
information about the error.
db_s_iter_not_allowed The routine was called while
an iteration, begun by dce_db_iter_start, was
in progress. Storing is not allowed during
iteration.
Usage
The dce_db_store routine stores the data structure pointed to by data
into the backing store. The conversion routine that was specified in
the call to dce_db_open serializes the structure so that it can be
written to disk.
If the key value is the same as a key already stored, the new data
replaces the previously stored data associated with that key.
Notes
Because the dce_db_store routine uses the encoding services, and they
in turn use rpc_sm_allocate, all programs that call dce_db_store
outside a server operation (for instance, if a server does some
backing store initialization or in a standalone program) must call
rpc_sm_enable_allocate first. Indeed, every thread that calls
dce_db_store must do rpc_sm_enable_allocate, but in the server side
of an RPC, this is already done.
Related Information
Routines:
dce_db_iter_start
dce_db_fetch
dce_db_open
dce_db_store_by_name
dce_db_store_by_uuid
rpc_sm_enable_allocate
ΓòÉΓòÉΓòÉ 3.6.27. dce_db_store_by_name ΓòÉΓòÉΓòÉ
Purpose
Stores data into a string-indexed backing store.
Format
#include <dce\dce.h>
#include <dce\dbif.h>
void dce_db_store_by_name(
dce_db_handle_t handle,
char *key,
void *data,
error_status_t *status);
Parameters
Input
handle A handle, returned from dce_db_open, that identifies
the backing store being used.
key A null-terminated string that is the backing store key.
data A pointer to the data structure to be stored.
Output
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns one of the following errors:
db_s_bad_index_type The backing store is not
indexed by name.
db_s_readonly The backing store was opened with
the db_c_readonly flag, and cannot be written
to.
db_s_store_failed The data could not be stored
into the backing store for some reason. The
global variable errno may contain more
information about the error.
db_s_iter_not_allowed The routine was called while
an iteration, begun by dce_db_iter_start, was
in progress. Storing is not allowed during
iteration.
Usage
The dce_db_store_by_name routine stores the data structure pointed to
by data into the backing store. The conversion routine that was
specified in the call to dce_db_open serializes the structure so that
it can be written to disk.
This routine is specialized for storage into backing stores that are
indexed by string, as selected by the db_c_index_by_name bit in the
flags parameter of the dce_db_open routine when the backing store was
created.
If the key value is the same as a key already stored, the information
pointed to by data replaces the previously stored data associated
with that key.
Notes
Because the dce_db_store_by_name routine uses the encoding services,
and they in turn use rpc_sm_allocate, all programs that call
dce_db_store_by_name outside a server operation (for instance, if a
server does some backing store initialization, or in a standalone
program) must call rpc_sm_enable_allocate first. Indeed, every thread
that calls dce_db_store_by_name must do rpc_sm_enable_allocate, but
in the server side of an RPC, this is already done.
Related Information
Routines:
dce_db_open
dce_db_store
dce_db_store_by_uuid
rpc_sm_enable_allocate
ΓòÉΓòÉΓòÉ 3.6.28. dce_db_store_by_uuid ΓòÉΓòÉΓòÉ
Purpose
Stores data into a UUID-indexed backing store.
Format
#include <dce\dce.h>
#include <dce\dbif.h>
void dce_db_store_by_uuid(
dce_db_handle_t handle,
uuid_t *key,
void *data,
error_status_t *status);
Parameters
Input
handle A handle, returned from dce_db_open, that identifies
the backing store being used.
key A UUID that is the backing store key.
data A pointer to the data structure to be stored.
Output
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns one of the following errors:
db_s_bad_index_type The backing store is not
indexed by UUID.
db_s_readonly The backing store was opened with
the db_c_readonly flag and cannot be written
to.
db_s_store_failed The data could not be stored
into the backing store for some reason. The
global variable errno may contain more
information about the error.
db_s_iter_not_allowed The routine was called while
an iteration, begun by dce_db_iter_start, was
in progress. Storing is not allowed during
iteration.
Usage
The dce_db_store_by_uuid routine stores the data structure pointed to
by data into the backing store. The conversion routine that was
specified in the call to dce_db_open serializes the structure so that
it can be written to disk.
This routine is specialized for storage into backing stores that are
indexed by UUID, as selected by the db_c_index_by_uuid bit in the
flags parameter of the dce_db_open routine when the backing store was
created.
If the key value is the same as a key already stored, the information
pointed to by data replaces the previously stored data associated
with that key.
Notes
Because the dce_db_store_by_uuid routine uses the encoding services,
and they in turn use rpc_sm_allocate, all programs that call
dce_db_store_by_uuid outside a server operation (for instance, if a
server does some backing store initialization, or in a standalone
program) must call rpc_sm_enable_allocate first. Indeed, every thread
that calls dce_db_store_by_uuid must do rpc_sm_enable_allocate, but
in the server side of an RPC, this is already done.
Related Information
Routines:
dce_db_iter_start
dce_db_open
dce_db_store
dce_db_store_by_name
rpc_sm_enable_allocate
ΓòÉΓòÉΓòÉ 3.6.29. dce_db_unlock ΓòÉΓòÉΓòÉ
Purpose
Releases the backing store lock.
Format
#include <dce\dce.h>
#include <dce\dbif.h>
void dce_db_unlock(
dce_db_handle_t handle,
error_status_t *status);
Parameters
Input
handle A handle, returned from dce_db_open, that identifies
the backing store being used.
Output
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns db_s_not_locked, which indicates
that an attempt was made to unlock a backing store, but
it was not locked.
Usage
The dce_db_unlock routine releases the lock associated with the
handle.
Related Information
Routines:
dce_db_lock
ΓòÉΓòÉΓòÉ 3.7. The DCE Messaging Interface ΓòÉΓòÉΓòÉ
All DCE message texts are assigned a unique message ID. This is a 32-bit
number, with the special value of all-bits-zero reserved to indicate success.
All other numbers are divided into a technology/component that identifies the
message catalog, and an index into the catalog.
All messages for a given component are stored in a single message catalog
generated by the sams utility when the component is built. (The messages can
also be compiled into the application code, which allows the successful
retrieval of message text independent of whether the message catalogs were
correctly installed.)
In typical use, a message is first retrieved from a message catalog, which
allows localization to occur. If this fails, the default message is retrieved
from an in-memory table. If this fails, a fallback text identifying the message
number is generated. The two most useful routines, dce_error_inq_text and
dce_msg_get, and the DCE printf routines follow these rules. The remainder of
this API gives direct access for special needs.
The dce_msg_cat_xxx routines provide a DCE abstraction to standard message
catalog routines, and map DCE message IDs to message catalog names. They offer
a convenient way of opening and accessing a message catalog by supplying the ID
of a message contained in it, rather than the name of the catalog itself. After
it is opened, the catalog is accessed by means of an opaque handle (the
dce_msg_cat_handle_t typedef).
See the following subtopics for more information:
The DCE Messaging Routines
Messaging Data Types and Structures
Messaging Related Information
ΓòÉΓòÉΓòÉ 3.7.1. The DCE Messaging Routines ΓòÉΓòÉΓòÉ
The messaging routines are as follows, listed in alphabetical order:
dce_error_inq_text Retrieves from the installed DCE component
message catalogs the message text associated
with an error status code returned by a DCE
library routine.
dce_msg_cat_close Closes the message catalog that was opened with
dce_msg_cat_open.
dce_msg_cat_get_msg Receives the text for a specified message.
dce_msg_cat_open Opens the message catalog that contains the
specified message and returns a handle that can
be used in subsequent calls to
dce_msg_cat_get_msg.
dce_msg_define_msg_table Registers an in-memory table containing the
messages.
dce_msg_get Retrieves the text for a specified message. This
routine is a convenience form of the
dce_msg_get_msg routine.
dce_msg_get_cat_msg This routine is a convenience form of the
dce_msg_cat_get_msg routine. Unlike
dce_msg_cat_get_msg, the dce_msg_get_cat_msg
routine does not require the message catalog to
be explicitly opened.
dce_msg_get_default_msg Retrieves a message from the application's
in-memory tables.
dce_msg_get_msg Retrieves the text for a specified message.
dce_msg_translate_table The dce_msg_translate_table routine overwrites
the specified in-memory message table with the
values from the equivalent message catalogs.
dce_pgm_printf, dce_pgm_fprintf, and dce_pgm_sprintf Equivalent to the
dce_printf routines, except that these routines
prepend the program name and append a newline
character.
dce_printf, dce_fprintf, and dce_sprintf These routines retrieve and print the
message text associated with the specified
message ID. dce_printf prints the message and
its arguments on the standard output,
dce_fprintf prints the message on the specified
stream, and dce_sprintf prints the message into
an allocated string that is returned.
ΓòÉΓòÉΓòÉ 3.7.2. Messaging Data Types and Structures ΓòÉΓòÉΓòÉ
dce_error_string_t An array of characters large enough to hold any
error text returned by dce_error_inq_text.
dce_msg_cat_handle_t An opaque handle to a DCE message catalog. (Use
dce_msg_cat_open to get a handle.)
ΓòÉΓòÉΓòÉ 3.7.3. Messaging Related Information ΓòÉΓòÉΓòÉ
Files:
dce\dce_msg.h
dce\dcesvcmsg.h
Books:
DCE for OS/2 Warp: Application Development Guide - Core Components
ΓòÉΓòÉΓòÉ 3.7.4. dce_error_inq_text ΓòÉΓòÉΓòÉ
Purpose
Retrieves message text associated with a DCE error code.
Format
#include <dce\dce_error.h>
void dce_error_inq_text(
error_status_t status_to_convert,
dce_error_string_t error_text,
int *status);
Parameters
Input
status_to_convert DCE status code for which a text message is to be
retrieved.
Output
error_text The message text associated with the status_to_convert.
status Returns the status code from this operation. The status
code is set to 0 on success, and to -1 on failure.
Usage
The dce_error_inq_text routine retrieves from the installed DCE
component message catalogs the message text associated with an error
status code returned by a DCE library routine.
All DCE message texts are assigned a unique 32-bit message ID. The
special value of all-bits-zero is reserved to indicate success.
The dce_error_inq_text routine uses the message ID as a series of
indices into the correct DCE component's message catalog; the text
found by this indexing is the message that explains the status code
that was returned by the DCE or DCE application routine.
All messages for a given component are stored in a single message
catalog generated by the sams utility when the component is built.
(The messages can also be compiled into the component code, which
allows the successful retrieval of message text independent of
whether the message catalogs were correctly installed.)
The text string returned by dce_error_inq_text is dependent on the
current locale. See Writing Internationalized RPC Applications for
more details.
Examples
The following code fragment shows how dce_error_inq_text can be used
to retrieve the message text describing the status code returned by
the DCE RPC library routine application:
dce_error_string_t error_string;
error_status_t status;
int print_status;
rpc_server_register_if(application_v1_0_s_ifspec, &type_uuid,
(rpc_mgr_epv_t)&manager_epv, &status);
if (status != rpc_s_ok) {
dce_error_inq_text(status, error_string, &print_status);
fprintf(stderr," Server: %s: %s\n", caller, error_string);
}
ΓòÉΓòÉΓòÉ 3.7.5. dce_msg_cat_close ΓòÉΓòÉΓòÉ
Purpose
Closes the specified DCE message catalog.
Format
#include <dce\dce_msg.h>
#include <dce\dcesvcmsg.h>
void dce_msg_cat_close(
dce_msg_cat_handle_t handle,
error_status_t *status);
Parameters
Input
handle The handle (returned by dce_msg_cat_open) to the
catalog that is to be closed.
Output
status Returns the status code from this operation. On
successful completion, the routine returns
msg_s_ok_text. Otherwise, it returns one of the
following errors:
msg_s_bad_id The message ID is not valid. A
message ID with a technology or component
that is not valid was specified.
msg_s_no_cat_open Could not open the message
catalog for the specified message ID.
msg_s_no_cat_perm Local file permissions prevented
the program from opening the message catalog
for the specified message ID.
msg_s_no_catalog The message catalog for the
specified message ID does not exist.
msg_s_no_default Could not find the default
message for the specified status code in the
internal tables.
msg_s_no_memory Could not allocate memory for
message table, string copy, or other internal
requirement.
msg_s_not_found Could not find the text for the
specified status code in either the in-core
message tables or the message catalogs.
Usage
The dce_msg_cat_close routine closes the message catalog that was
opened with dce_msg_cat_open. On error, it fills in status with an
error code.
Related Information
Routines:
dce_msg_cat_get_msg
dce_msg_cat_open
dce_msg_get
dce_msg_get_cat_msg
dce_msg_get_msg
ΓòÉΓòÉΓòÉ 3.7.6. dce_msg_cat_get_msg ΓòÉΓòÉΓòÉ
Purpose
Retrieves message text from a DCE message catalog.
Format
#include <dce\dce_msg.h>
#include <dce\dcesvcmsg.h>
unsigned char *dce_msg_cat_get_msg(
dce_msg_cat_handle_t handle,
unsigned32 message,
error_status_t *status);
Parameters
Input
message The ID of the message to be retrieved. This is a 32-bit
DCE message ID as described in dce_msg_intro.
handle A handle (returned by dce_msg_cat_open) to an opened
message catalog.
Output
status Returns the status code from this operation. On
successful completion, the routine returns
msg_s_ok_text. Otherwise, it returns one of the
following errors:
msg_s_bad_id The message ID is not valid. A
message ID with a technology or component
that is not valid was specified.
msg_s_no_cat_open Could not open the message
catalog for the specified message ID.
msg_s_no_cat_perm Local file permissions prevented
the program from opening the message catalog
for the specified message ID.
msg_s_no_catalog The message catalog for the
specified message ID does not exist.
msg_s_no_default Could not find the default
message for the specified status code in the
internal tables.
msg_s_no_memory Could not allocate memory for
message table, string copy, or other internal
requirement.
msg_s_not_found Could not find the text for the
specified status code in either the in-core
message tables or the message catalogs.
Usage
After the catalog has been opened with the dce_msg_cat_open routine,
dce_msg_cat_get_msg can be used to retrieve the text for a specified
message. If the message cannot be found in the catalog, the routine
returns a NULL and fills in status with the appropriate error code.
Related Information
Routines:
dce_msg_cat_close
dce_msg_cat_get_msg
dce_msg_cat_open
dce_msg_get
dce_msg_get_cat_msg
dce_msg_get_msg
ΓòÉΓòÉΓòÉ 3.7.7. dce_msg_cat_open ΓòÉΓòÉΓòÉ
Purpose
Opens a DCE message catalog.
Format
#include <dce\dce_msg.h>
#include <dce\dcesvcmsg.h>
dce_msg_cat_handle_t dce_msg_cat_open(
unsigned32 message_id,
error_status_t *status);
Parameters
Input
message_id The ID of the message to be retrieved.
Output
status Returns the status code from this operation. On
successful completion, the routine returns
msg_s_ok_text. Otherwise, it returns one of the
following errors:
msg_s_bad_id The message ID is not valid. A
message ID with a technology or component
that is not valid was specified.
msg_s_no_cat_open Could not open the message
catalog for the specified message ID.
msg_s_no_cat_perm Local file permissions prevented
the program from opening the message catalog
for the specified message ID.
msg_s_no_catalog The message catalog for the
specified message ID does not exist.
msg_s_no_default Could not find the default
message for the specified status code in the
internal tables.
msg_s_no_memory Could not allocate memory for
message table, string copy, or other internal
requirement.
msg_s_not_found Could not find the text for the
specified status code in either the in-core
message tables or the message catalogs.
Usage
The dce_msg_cat_open routine opens the message catalog that contains
the specified message_id. It returns a handle that can be used in
subsequent calls to dce_msg_cat_get_msg. On error, it returns NULL
and fills in status with an appropriate error code.
Related Information
Routines:
dce_msg_cat_close
dce_msg_cat_get_msg
dce_msg_get_cat_msg
dce_msg_get
dce_msg_get_msg
ΓòÉΓòÉΓòÉ 3.7.8. dce_msg_define_msg_table ΓòÉΓòÉΓòÉ
Purpose
Adds a message table to the in-memory table.
Format
#include <dce\dce_msg.h>
#include <dce\dcesvcmsg.h>
void dce_msg_define_msg_table(
dce_msg_table_t *table,
unsigned32 count,
error_status_t *status);
Parameters
Input
table A message table structure defined in a header file
generated by sams during compilation (see the examples
following).
count The number of elements contained in the table.
Output
status Returns the status code from this operation. On
successful completion, the routine returns
msg_s_ok_text. Otherwise, it returns one of the
following errors:
msg_s_bad_id The message ID is not valid. A
message ID with a technology or component
that is not valid was specified.
msg_s_no_cat_open Could not open the message
catalog for the specified message ID.
msg_s_no_cat_perm Local file permissions prevented
the program from opening the message catalog
for the specified message ID.
msg_s_no_catalog The message catalog for the
specified message ID does not exist.
msg_s_no_default Could not find the default
message for the specified status code in the
internal tables.
msg_s_no_memory Could not allocate memory for
message table, string copy, or other internal
requirement.
msg_s_not_found Could not find the text for the
specified status code in either the in-core
message tables or the message catalogs.
Usage
All messages for a given component are stored in a single message
catalog generated by the sams utility when the component
(application) is built.
However, the messages can also be compiled directly into the
component code, which allows the successful retrieval of message text
independent of whether the message catalogs were correctly installed.
Generation of in-memory message tables is specified by the incatalog
flag in the sams file where the message text is defined. If the
messages have been generated at compile time with this option
specified, the dce_msg_define_msg_table routine can be called by the
application to register an in-memory table containing the messages.
The table parameter should identify a message table structure defined
in a header file generated by sams during compilation (see the
examples following). The count parameter specifies the number of
elements contained in the table. If an error is detected during the
call, the routine returns an appropriate error code in the status
parameter.
Examples
The following code fragment shows how an application (whose
serviceability component name is app) sets up an in-memory message
table:
#include <dce\dce.h>
#include <dce\dce_msg.h>
#include <dce\dcesvcmsg.h>
#include "dceappmsg.h" \* defines app_msg_table *\
error_status_t status;
The following call adds the message table to the in-memory table.
Note that you must include <dce\dce_msg.h>. You also have to link in
dceappmsg.o and dceappsvc.o (object files produced by compiling
sams-generated .c files), which contain the code for the messages and
the table, respectively.
dce_msg_define_msg_table(app_msg_table,
sizeof(app_msg_table) / sizeof(app_msg_table[0]),
&status);
Related Information
Routines:
dce_msg_get
dce_msg_get_msg
dce_msg_get_default_msg
ΓòÉΓòÉΓòÉ 3.7.9. dce_msg_get ΓòÉΓòÉΓòÉ
Purpose
Retrieves the text of a specified DCE message.
Format
#include <dce\dce_msg.h>
unsigned char *dce_msg_get(
unsigned32 message);
Parameters
Input
message ID of the message to be retrieved. This ID is a 32-bit
DCE message ID, with the special value of all-bits-zero
reserved to indicate success.
Usage
The dce_msg_get routine is a convenience form of the dce_msg_get_msg
routine. Like dce_msg_get_msg, the dce_msg_get routine retrieves the
text for a specified message. However, dce_msg_get does not return a
status code; it either returns the specified message successfully or
fails (ends the program) with an assertion error if the message could
not be found or memory could not be allocated.
The routine implicitly determines the correct message catalog in
which to access the specified message, and opens it; you only have to
call this routine.
The routine first searches the appropriate message catalog for the
message, and then (if it cannot find the catalog) searches the
in-memory message table, if it exists.
The message, if found, is returned in allocated space to which the
routine returns a pointer. You must free the pointed-to space by
using dce_free.
Related Information
Routines:
dce_free
dce_msg_define_msg_table
dce_msg_get_msg
dce_msg_get_default_msg
ΓòÉΓòÉΓòÉ 3.7.10. dce_msg_get_cat_msg ΓòÉΓòÉΓòÉ
Purpose
Opens a message catalog and retrieves a message.
Format
#include <dce\dce_msg.h>
#include <dce\dcesvcmsg.h>
unsigned char *dce_msg_get_cat_msg(
unsigned32 message,
error_status_t *status);
Parameters
Input
message ID of message to be retrieved. This ID is a 32-bit DCE
message ID, with the special value of all-bits-zero
reserved to indicate success.
Output
status Returns the status code from this operation. On
successful completion, the routine returns
msg_s_ok_text. Otherwise, it returns one of the
following errors:
msg_s_bad_id The message ID is not valid. A
message ID with a technology or component
that is not valid was specified.
msg_s_no_cat_open Could not open the message
catalog for the specified message ID.
msg_s_no_cat_perm Local file permissions prevented
the program from opening the message catalog
for the specified message ID.
msg_s_no_catalog The message catalog for the
specified message ID does not exist.
msg_s_no_default Could not find the default
message for the specified status code in the
internal tables.
msg_s_no_memory Could not allocate memory for
message table, string copy, or other internal
requirement.
msg_s_not_found Could not find the text for the
specified status code in either the in-core
message tables or the message catalogs.
Usage
The dce_msg_get_cat_msg routine is a convenience form of the
dce_msg_cat_get_msg routine. The difference between it and the latter
routine is that dce_msg_get_cat_msg does not require the message
catalog to be explicitly opened; it determines the correct catalog
from the message parameter, opens it, retrieves the message, and
returns a pointer to space allocated with malloc that contains the
message. If the message catalog is inaccessible, the routine returns
an error.
The routine fails if the message catalog is not correctly installed.
Related Information
Routines:
dce_msg_cat_close
dce_msg_cat_get_msg
dce_msg_cat_open
dce_msg_get
dce_msg_get_msg
ΓòÉΓòÉΓòÉ 3.7.11. dce_msg_get_default_msg ΓòÉΓòÉΓòÉ
Purpose
Retrieves a DCE message from in-memory tables.
Format
#include <dce\dce_msg.h>
#include <dce\dcesvcmsg.h>
unsigned char *dce_msg_get_default_msg(
unsigned32 message,
error_status_t *status);
Parameters
Input
message ID of message to be retrieved. This ID is a 32-bit DCE
message ID, with the special value of all-bits-zero
reserved to indicate success.
Output
status Returns the status code from this operation. On
successful completion, the routine returns
msg_s_ok_text. Otherwise, it returns one of the
following errors:
msg_s_bad_id The message ID is not valid. A
message ID with a technology or component
that is not valid was specified.
msg_s_no_cat_open Could not open the message
catalog for the specified message ID.
msg_s_no_cat_perm Local file permissions prevented
the program from opening the message catalog
for the specified message ID.
msg_s_no_catalog The message catalog for the
specified message ID does not exist.
msg_s_no_default Could not find the default
message for the specified status code in the
internal tables.
msg_s_no_memory Could not allocate memory for
message table, string copy, or other internal
requirement.
msg_s_not_found Could not find the text for the
specified status code in either the in-core
message tables or the message catalogs.
Usage
The dce_msg_get_default_msg routine retrieves a message from the
application's in-memory tables. It returns a pointer to static space
that should not be freed. If the specified message cannot be found in
the in-memory tables, the routine returns NULL and fills in status
with the appropriate error code.
This routine should be used only for message strings that will never
be translated (see dce_msg_translate_table).
All messages for a given component are stored in a single message
catalog generated by the sams utility when the component is built.
Messages can also be compiled directly into the component code, which
allows the successful retrieval of message text independent of
whether the message catalogs were correctly installed. Generation of
in-memory message tables is specified by the incatalog flag in the
sams file where the message text is defined. If the messages have
been generated at compile time with this option specified, the
dce_msg_define_msg_table routine can be called by the application to
set up an in-memory table containing the messages.
Examples
The following code fragment shows how dce_msg_get_default_msg can be
called to retrieve the in-memory copy of a message defined by a DCE
application (whose serviceability component name is app):
#include <dce\dce.h>
#include <dce\dce_msg.h>
#include <dce\dcesvcmsg.h>
#include "dceappmsg.h" /* test_msg is defined in this file */
unsigned char *my_msg;
error_status_t status;
.
.
.
my_msg = dce_msg_get_default_msg(test_msg, &status);
printf("Message is: %s\n", my_msg);
Related Information
Routines:
dce_msg_define_msg_table
dce_msg_get
dce_msg_get_msg
ΓòÉΓòÉΓòÉ 3.7.12. dce_msg_get_msg ΓòÉΓòÉΓòÉ
Purpose
Retrieves a DCE message from its ID.
Format
#include <dce\dce_msg.h>
#include <dce\dcesvcmsg.h>
unsigned char *dce_msg_get_msg(
unsigned32 message,
error_status_t *status);
Parameters
Input
message ID of message to be retrieved. This ID is a 32-bit DCE
message ID, with the special value of all-bits-zero
reserved to indicate success.
Output
status Returns the status code from this operation. On
successful completion, the routine returns
msg_s_ok_text. Otherwise, it returns one of the
following errors:
msg_s_bad_id The message ID is not valid. A
message ID with a technology or component
that is not valid was specified.
msg_s_no_cat_open Could not open the message
catalog for the specified message ID.
msg_s_no_cat_perm Local file permissions prevented
the program from opening the message catalog
for the specified message ID.
msg_s_no_catalog The message catalog for the
specified message ID does not exist.
msg_s_no_default Could not find the default
message for the specified status code in the
internal tables.
msg_s_no_memory Could not allocate memory for
message table, string copy, or other internal
requirement.
msg_s_not_found Could not find the text for the
specified status code in either the in-core
message tables or the message catalogs.
Usage
The dce_msg_get_msg routine retrieves the text for a specified
message. The routine implicitly determines the correct message
catalog in which to access the message, and opens it; you only have
to call the routine.
The routine first searches the appropriate message catalog for the
message, and then (if it cannot find the catalog) searches the
in-memory message table. If the message cannot be found in either of
these places, the routine returns a default string and fills in
status with an error code. This routine always returns a string, even
if there is an error (except for msg_s_no_memory).
The message, if found, is returned in allocated space to which the
routine returns a pointer. You must free the pointed-to space by
using dce_free. If memory cannot be allocated, the routine returns
NULL and fills in status with the msg_s_no_memory error code.
Related Information
Routines:
dce_free
dce_msg_define_msg_table
dce_msg_get
dce_msg_get_default_msg
ΓòÉΓòÉΓòÉ 3.7.13. dce_msg_translate_table ΓòÉΓòÉΓòÉ
Purpose
Translates all in-memory messages in a table.
Format
#include <dce\dce_msg.h>
#include <dce\dcesvcmsg.h>
void dce_msg_translate_table(
dce_msg_table_t *table,
unsigned32 count,
error_status_t *status);
Parameters
Input
table A message table structure defined in a header file
generated by sams during compilation (see the following
examples), the contents of which are to be translated.
count The number of elements contained in the table.
Output
status Returns the status code from this operation. On
successful completion, the routine returns
msg_s_ok_text. Otherwise, it returns one of the
following errors:
msg_s_bad_id The message ID is not valid. A
message ID with a technology or component
that is not valid was specified.
msg_s_no_cat_open Could not open the message
catalog for the specified message ID.
msg_s_no_cat_perm Local file permissions prevented
the program from opening the message catalog
for the specified message ID.
msg_s_no_catalog The message catalog for the
specified message ID does not exist.
msg_s_no_default Could not find the default
message for the specified status code in the
internal tables.
msg_s_no_memory Could not allocate memory for
message table, string copy, or other internal
requirement.
msg_s_not_found Could not find the text for the
specified status code in either the in-core
message tables or the message catalogs.
Usage
The dce_msg_translate_table routine overwrites the specified
in-memory message table (that is, updates the in-memory table with
the contents of a message table that has changed for some reason; for
example, because of a change in locale).
If any in-memory message is not found in the message catalog, all
in-memory messages are left unchanged.
Examples
The following code fragment shows how dce_msg_translate_table can be
called (in an application whose serviceability component name is app)
to translate the DCE application's in-memory message table, set up by
an earlier call to dce_msg_define_msg_table:
#include <dce\dce.h>
#include <dce\dce_msg.h>
#include <dce\dcesvcmsg.h>
#include "dceappmsg.h"
char *loc_return;
error_status_t status;
<...>
dce_msg_translate_table(app_msg_table,
sizeof(app_msg_table) / sizeof(app_msg_table[0]),
&status);
Related Information
Routines:
dce_msg_define_msg_table
ΓòÉΓòÉΓòÉ 3.7.14. dce_pgm_printf, dce_pgm_fprintf, and dce_pgm_sprintf ΓòÉΓòÉΓòÉ
Purpose
Generates formatted DCE message output.
Format
#include <dce\dce.h>
int dce_pgm_printf(
unsigned32 messageid,
...);
int dce_pgm_fprintf(
FILE *stream,
unsigned32 messageid,
...);
unsigned char *dce_pgm_sprintf(
unsigned32 messageid,
...);
Parameters
Input
messageid The message ID, defined in the message's code field in
the sams file.
stream An open file pointer.
... Any format arguments for the message string.
Usage
The dce_pgm_printf routine is equivalent to dce_printf, except that
it prefixes the program name to the message (in the standard style of
DCE error messages), and appends a newline character to the end of
the message. This allows clients that do not usually use the
serviceability interface to produce error (or other) messages that
automatically include the originating application's name. Note that
the application should call dce_svc_set_progname first to set the
desired application name. Otherwise, the default program name is
PID#nnnn, where nnnn is the process ID of the application making the
call.
The dce_pgm_sprintf routine is similarly equivalent to dce_sprintf,
and the dce_pgm_fprintf routine is similarly equivalent to
dce_fprintf.
Notes
The dce_pgm_sprintf allocates storage that the user needs to free.
Use the dce_free routine to do this. See dce_printf, dce_fprintf, and
dce_sprintf for an example using dce_sprintf and dce_free.
Related Information
Routines:
dce_free
dce_printf, dce_fprintf, and dce_sprintf
dce_msg_get_msg
dce_svc_set_progname
ΓòÉΓòÉΓòÉ 3.7.15. dce_printf, dce_fprintf, and dce_sprintf ΓòÉΓòÉΓòÉ
Purpose
Generates formatted DCE message output.
Format
#include <dce\dce.h>
int dce_printf(
unsigned32 messageid,
...);
int dce_fprintf(
FILE *stream,
unsigned32 messageid,
...);
unsigned char *dce_sprintf(
unsigned32 messageid,
...);
Parameters
Input
messageid The message ID, defined in the message's code field in
the sams file.
stream An open file pointer.
... Any format arguments for the message string.
Usage
The dce_printf routine retrieves the message text associated with the
specified messageid and prints the message and its arguments on the
standard output.
The dce_fprintf routine functions similarly to dce_printf, except
that it prints the message and its arguments on the specified stream.
The dce_sprintf routine retrieves the message text associated with
the specified messageid and prints the message and its arguments into
an allocated string that is returned.
These routines determine the correct message catalog and, if
necessary, open it. If the message catalog is inaccessible and the
message exists in an in-memory table, this message is printed. If
neither the catalog nor the in-memory message is available, a default
message is printed.
The dce_pgm_printf routine is equivalent to dce_printf, except that
it prefixes the program name to the message (in the standard style of
DCE error messages) and appends a newline character to the end of the
message.
Notes
The dce_sprintf routine allocates memory for messageid that must be
freed by the caller using dce_free.
The final formatted string generated by dce_sprintf must not exceed
1024 bytes.
Examples
Assume that the following message is defined in the application's
sams file:
start
code arg_msg
text "This message has exactly %d, not %d argument(s)"
action "None required"
explanation "Test message with format arguments"
end
The following code fragment shows how dce_sprintf can be called to
write the message (with some argument values) into a string:
unsigned char *my_msg;
my_msg = dce_sprintf(arg_msg, 2, 8);
puts(my_msg);
dce_free(my_msg);
Of course, dce_printf could also be called to print the message and
arguments:
dce_printf(arg_msg, 2, 8);
Related Information
Routines:
dce_free
dce_msg_get_msg
dce_pgm_printf, dce_pgm_fprintf, and dce_pgm_sprintf
ΓòÉΓòÉΓòÉ 3.8. The DCE Server Routines ΓòÉΓòÉΓòÉ
The routines described on this reference page are used by servers to register
themselves with DCE. This includes registering with the RPC runtime, the local
endpoint mapper, and the namespace. Routines are also available to set up DCE
security so that servers can receive and invoke authenticated RPCs.
See the following subtopics for more information:
List of Server Routines
Server Data Types and Structures
Server Related Information
ΓòÉΓòÉΓòÉ 3.8.1. List of Server Routines ΓòÉΓòÉΓòÉ
The server routines are listed in alphabetical order:
dce_server_disable_service Unregisters an individual interface of a DCE
server from the RPC runtime and marks the
server's endpoints as disabled in the dced
endpoint mapper service.
dce_server_enable_service Registers an individual interface (application
service) of a DCE server with the RPC runtime
and marks the server's endpoints as enabled in
the dced endpoint mapper service.
dce_server_inq_attr Obtains application-specific attribute data from
the dced server configuration data.
dce_server_inq_server Obtains the server configuration data dced used
to start the server.
dce_server_inq_uuids Obtains the UUIDs that dced used in its srvrconf
and srvrexec facilities to identify the server's
configuration and execution data.
dce_server_register Registers a DCE server by establishing a
server's binding information, registering its
services (represented by interface IDs) with the
RPC runtime, and entering its endpoints in the
dced endpoint mapper service.
dce_server_sec_begin Prepares a server to receive and generate
authenticated RPCs.
dce_server_sec_done Releases the resources previously set up by a
call to dce_server_sec_begin.
dce_server_unregister Unregisters a DCE server by unregistering the
server's services (interfaces) from the RPC
runtime, and removing the endpoints from the
dced endpoint mapper service.
dce_server_use_protseq Registers a protocol sequence to use for the
server.
ΓòÉΓòÉΓòÉ 3.8.2. Server Data Types and Structures ΓòÉΓòÉΓòÉ
dce_server_handle_t An opaque data structure containing information
the runtime uses to establish the server with
DCE.
dce_server_register_data_t A structure that contains an interface handle
(generated by IDL), a default EPV, and a count
and array of dce_server_type_ts for services
that use RPC object types.
dce_server_type_t A structure containing a manager type UUID and
an RPC entry-point vector (EPV) that specifies
the routines that implement the IDL interface
for the specific type.
server_t See The DCE Host Daemon Routines for a complete
description of the server_t data type.
ΓòÉΓòÉΓòÉ 3.8.3. Server Related Information ΓòÉΓòÉΓòÉ
Files:
dce\dced.h
dce\dced_base.idl
Books:
DCE for OS/2 Warp: Application Development Guide - Core Components
ΓòÉΓòÉΓòÉ 3.8.4. dce_server_disable_service ΓòÉΓòÉΓòÉ
Purpose
Disables an individual service of a server. (This routine is not
currently supported.)
Format
#include <dce\dced.h>
void dce_server_disable_service(
dce_server_handle_t server_handle,
rpc_if_handle_t interface,
error_status_t *status);
Parameters
Input
server_handle An opaque handle returned by dce_server_register.
interface Specifies an opaque variable containing information the
runtime uses to access interface specification data.
Output
status Returns the status code from this routine. This status
code indicates whether the routine completed
successfully. The only status code is error_status_ok.
Usage
The dce_server_disable_service routine disables an individual service
that a server provides by unregistering the service's interface from
the RPC runtime and marking the server's endpoints as disabled in the
local dced endpoint mapper service.
For dced to recognize all server services, a server should register
all its application services using the dce_server_register routine.
If it later becomes necessary for the server to disable an interface,
it can use the dce_server_disable_service routine rather than
unregistering the entire server.
Related Information
Routines:
dce_server_enable_service
dce_server_register
Books:
DCE for OS/2 Warp: Application Development Guide - Core Components
ΓòÉΓòÉΓòÉ 3.8.5. dce_server_enable_service ΓòÉΓòÉΓòÉ
Purpose
Enables an individual service for a server. (This routine is not
currently supported.)
Format
#include <dce\dced.h>
void dce_server_enable_service(
dce_server_handle_t server_handle,
rpc_if_handle_t interface,
error_status_t *status);
Parameters
Input
server_handle An opaque handle returned by dce_server_register.
interface Specifies an opaque variable containing information the
runtime uses to access interface specification data.
Output
status Returns the status code from this routine. This status
code indicates whether the routine completed
successfully. The only status code is error_status_ok.
Usage
The dce_server_enable_service routine enables an individual service
that a server provides by registering the service's interface with
the RPC runtime, and registering the endpoints in the endpoint map.
If the dce_server_c_no_endpoints flag was set with the
dce_server_register routine prior to calling this routine, the
endpoints are not registered in the endpoint map.
A server commonly registers all its services with DCE at once by
using the dce_server_register routine. If necessary, a server can use
the dce_server_disable_service routine to disable individual services
and then reenable them by using dce_server_enable_service. However,
a server may need its services registered in a certain order, or it
may require application-specific activities between the registration
of services. If a server requires this kind of control as services
are registered, you can set the server->services.list[i].flags field
of the server_t structure to service_c_disabled for individual
services prior to calling dce_server_register. The server can then
call dce_server_enable_service for each service when needed.
Related Information
Routines:
dce_server_disable_service
dce_server_register
Books:
DCE for OS/2 Warp: Application Development Guide - Core Components
ΓòÉΓòÉΓòÉ 3.8.6. dce_server_inq_attr ΓòÉΓòÉΓòÉ
Purpose
Obtains from dced the value of an attribute known to the server.
(This routine is not currently supported.)
Format
#include <dce\dced.h>
void dce_server_inq_attr(
uuid_t *attribute_uuid,
sec_attr_t *value,
error_status_t *status);
Parameters
Input
attribute_uuid The UUID dced uses to identify an attribute.
Output
value Returns the attribute.
status Returns the error_status_ok status code upon
successful completion. Otherwise, one of the
following is returned:
dced_s_server_attr_not_found
dced_s_not_started_by_dced
Usage
The dce_server_inq_attr routine obtains an attribute from the
environment created by dced when it started the server. Each server
maintains, among other things, a list of attributes that are used to
describe application-specific behavior.
Related Information
Routines:
dce_server_inq_server
dce_server_inq_uuids
Books:
DCE for OS/2 Warp: Application Development Guide - Core Components
ΓòÉΓòÉΓòÉ 3.8.7. dce_server_inq_server ΓòÉΓòÉΓòÉ
Purpose
Obtains the server configuration data dced used to start the server.
(This routine is not currently supported.)
Format
#include <dce\dced.h>
void dce_server_inq_server(
server_t **server,
error_status_t *status);
Parameters
Output
server Returns the structure that describes the server's
configuration.
status Returns the error_status_ok status code upon successful
completion. Otherwise, one of the following is
returned:
dced_s_not_started_by_dced
dced_s_data_unavailable
Usage
The dce_server_inq_server routine obtains the server configuration
data (srvrconf) maintained by dced and used by dced to start the
server. This routine is commonly called prior to registering the
server to obtain the server data used as input to
dce_server_register.
Related Information
Routines:
dce_server_register
Books:
DCE for OS/2 Warp: Application Development Guide - Core Components
ΓòÉΓòÉΓòÉ 3.8.8. dce_server_inq_uuids ΓòÉΓòÉΓòÉ
Purpose
Obtains the UUIDs that dced associates with the server's
configuration and execution data. (This routine is not currently
supported.)
Format
#include <dce\dced.h>
void dce_server_inq_uuids(
uuid_t *conf_uuid,
uuid_t *exec_uuid,
error_status_t *status);
Parameters
Output
conf_uuid Returns the UUID that dced uses to identify the
server's configuration data. If a NULL value is input,
no value is returned.
exec_uuid Returns the UUID that dced uses to identify the
executing server. If a NULL value is input, no value is
returned.
status Returns the error_status_ok status code upon successful
completion. Otherwise, dced_s_not_started_by_dced is
returned.
Usage
The dce_server_inq_uuids routine obtains the UUIDs that dced uses in
its srvrconf and srvrexec services to identify the server's
configuration and execution data. The server can then use dced API
routines to access the data and perform other server management
functions.
Related Information
Routines:
dce_server_inq_server
Books:
DCE for OS/2 Warp: Application Development Guide - Core Components
ΓòÉΓòÉΓòÉ 3.8.9. dce_server_register ΓòÉΓòÉΓòÉ
Purpose
Registers a server with DCE. (This routine is not currently
supported.)
Format
#include <dce\dced.h>
void dce_server_register(
unsigned32 flags,
server_t *server,
dce_server_register_data_t *data,
dce_server_handle_t *server_handle,
error_status_t *status);
Parameters
Input
flags Specifies options for server registration. Combinations
of the following values can be used:
dce_server_c_no_protseqs
dce_server_c_no_endpoints
dce_server_c_ns_export
server Specifies the server data, commonly obtained from dced
by calling dce_server_inq_server. The server_t
structure is described in DCE Security Services API.
data Specifies the array of data structures that contain the
additional information required for the server to
service requests for specific remote procedures. Each
structure of the array includes:
o An interface handle (ifhandle) of type
rpc_if_handle_t
o An entry point vector (epv) of type rpc_mgr_epv_t
o A number (num_types) of type unsigned32
representing the number in the following array
o An array of server types (types) of type
dce_server_type_t
The dce_server_type_t structure contains a UUID (type)
of type uuid_t representing the object type, and a
manager entry point vector (epv) of type rpc_mgr_epv_t
representing the set of procedures implemented for the
object type.
Output
server_handle Returns a server handle, which is a pointer to an
opaque data structure containing information about the
server.
status Returns the error_status_ok status code upon successful
completion. Otherwise, rpc_s_no_memory is returned.
Usage
By default, the dce_server_register routine registers a DCE server by
establishing a server's binding information for all valid protocol
sequences, registering all the server's services with the RPC
runtime, and entering the server's endpoints in the dced endpoint
mapper service.
Prior to calling the dce_server_register routine, the server obtains
the server configuration data from dced by calling
dce_server_inq_server. The server must also set up an array of
registration data, where the size of the array represents all the
server's services that are currently registered in the server
configuration data of dced (server->services.count). If the memory
for the array is dynamically allocated, it must not be freed until
after the corresponding dce_server_unregister routine is called.
You can modify the behavior of dce_server_register, depending on the
values of the flags parameter. If the flag has the value
dce_server_c_ns_export, the binding information is also exported to
the name space. The name space entry is determined for each service
by the server->services.list[i].entryname parameter. If this
parameter has no value, the default value for the entire server is
used (server->entryname). If the flag has the value
dce_server_c_no_endpoints, the binding information is not registered
with the endpoint map. Your application can use rpc_ep_register to
register specific binding information. If the flag has the value
dce_server_c_no_protseqs, specific protocol sequences are used rather
than all valid protocol sequences. Use of this flag requires that the
server first call dce_server_use_protseq at least once for a valid
protocol sequence.
Related Information
Routines:
dce_server_inq_server
dce_server_sec_begin
dce_server_unregister
rpc_server_listen
Books:
DCE for OS/2 Warp: Application Development Guide - Core Components
ΓòÉΓòÉΓòÉ 3.8.10. dce_server_sec_begin ΓòÉΓòÉΓòÉ
Purpose
Establishes a server to receive fully authenticated remote procedure
calls (RPCs) and to also act as a client to do authenticated RPCs.
(This routine is not currently supported.)
Format
#include <dce\dced.h>
void dce_server_sec_begin(
unsigned32 flags,
error_status_t *status);
Parameters
Input
flags Flags are set to manage keys and set up a login
context. Valid values include the following:
dce_server_c_manage_key
dce_server_c_login
Output
status Returns the error_status_ok status code upon successful
completion. Otherwise, one of the following errors is
returned:
dced_s_need_one_server_prin
dced_s_not_started_by_dced
dced_s_no_server_keyfile
dced_s_cannot_create_key_mgmt_thr
dced_s_cannot_detach_key_mgmt_thr
Usage
The dce_server_sec_begin routine prepares a server to receive
authenticated RPCs. It also sets up all that is required for the
application, when behaving as a client to other servers, to do
authenticated RPCs as a client. When authentication is required,
this call must precede all other RPC and DCE server initialization
calls, including dce_server_register. When your application has
stopped listening for RPCs, it should call the dce_server_sec_done
routine.
Related Information
Routines:
dce_server_register
dce_server_sec_done
rpc_server_listen
Books:
DCE for OS/2 Warp: Application Development Guide - Core Components
ΓòÉΓòÉΓòÉ 3.8.11. dce_server_sec_done ΓòÉΓòÉΓòÉ
Purpose
Releases resources established for a server to receive (and when
acting as a client, to send) fully authenticated remote procedure
calls (RPCs). (This routine is not currently supported.)
Format
#include <dce\dced.h>
void dce_server_sec_done(
error_status_t *status);
Parameters
Output
status Returns the status code from this routine. This status
code indicates whether the routine completed
successfully. The only status code is error_status_ok.
Usage
The dce_server_sec_done routine releases the resources previously set
up by a call to dce_server_sec_begin. The dce_server_sec_begin
routine sets all that is needed for a server to receive authenticated
RPCs and it also sets up all that is required for the application to
do authenticated RPCs as a client. If this routine is used, it must
follow all other server DCE and RPC initialization and cleanup calls.
Related Information
Routines:
dce_server_sec_begin
rpc_server_listen
Books:
DCE for OS/2 Warp: Application Development Guide - Core Components
ΓòÉΓòÉΓòÉ 3.8.12. dce_server_unregister ΓòÉΓòÉΓòÉ
Purpose
Unregisters a DCE server. (This routine is not currently supported.)
Format
#include <dce\dced.h>
void dce_server_unregister(
dce_server_handle_t *server_handle,
error_status_t *status);
Parameters
Input
server_handle An opaque handle returned by dce_server_register.
Output
status Returns the status code from this routine. This
status code indicates whether the routine
completed successfully. The only status code is
error_status_ok.
Usage
The dce_server_unregister routine unregisters a DCE server by
unregistering a server's services (interfaces) from the RPC runtime.
When a server has stopped listening for remote procedure calls, it
should call this routine.
The flags set with the corresponding dce_server_register routine are
part of the server handle's information used to determine the action
to take. These actions include removing the server's endpoints from
the dced endpoint mapper service and unexporting binding information
from the name space.
Use the dce_server_disable_service routine to disable specific
application services rather than to unregister the whole server.
Related Information
Routines:
dce_server_disable_service
dce_server_register
rpc_server_listen
Books:
DCE for OS/2 Warp: Application Development Guide - Core Components
ΓòÉΓòÉΓòÉ 3.8.13. dce_server_use_protseq ΓòÉΓòÉΓòÉ
Purpose
Tells DCE to use the specified protocol sequence for receiving remote
procedure calls. This routine is used by server applications. (This
routine is not currently supported.)
Format
#include <dce\dced.h>
void dce_server_use_protseq(
dce_server_handle_t server_handle,
unsigned char *protseq,
error_status_t *status);
Parameters
Input
server_handle An opaque handle. Use the value of NULL.
protseq Specifies a string identifier for the protocol
sequence to register with the RPC runtime. (For a
list of string identifiers, see the table of
valid protocol sequences in The DCE Remote
Procedure Call API.)
Output
status Returns the status code from this routine. This
status code indicates whether the routine
completed successfully. The only status code is
error_status_ok.
Usage
The dce_server_use_protseq routine registers an individual protocol
sequence with DCE. Typical servers use all valid protocol sequences,
which is the default behavior for the dce_server_register routine,
which means that most servers do not need to call the
dce_server_use_protseq routine. However, this routine can be called
prior to dce_server_register, to restrict the protocol sequences
used. A server must register at least one protocol sequence with the
RPC runtime to receive remote procedure call requests. A server can
call this routine multiple times to register additional protocol
sequences.
Related Information
Routines:
The DCE Remote Procedure Call API
dce_server_register
rpc_server_use_protseq
Books:
DCE for OS/2 Warp: Application Development Guide - Core Components
ΓòÉΓòÉΓòÉ 3.9. The DCE Serviceability Interface ΓòÉΓòÉΓòÉ
The following routines are intended to be used by servers that export the
serviceability interface defined in service.idl. The complete list of these
remote serviceability implementation routines is as follows (the remote
operation name is given in the left column and the corresponding implementation
routine is given in the right column).
dce_svc_set_route dce_svc_routing
dce_svc_set_dbg_route dce_svc_debug_routing
dce_svc_set_dbg_levels dce_svc_debug_set_levels
dce_svc_inq_components dce_svc_components
dce_svc_inq_table dce_svc_table
dce_svc_filter_control dce_svc_filter
dce_svc_inq_stats dce_svc_inq_stats
These routines perform all the necessary processing (except for checking
client authorization) that must be done by the application manager to
implement the remote serviceability operations.
Note: Most of these routines have little meaning except as implementations of
remote operations. However, the dce_svc_routing, dce_svc_filter,
dce_svc_debug_routing and dce_svc_debug_set_levels routines can
conceivably be used by servers as purely local operations (for example,
in order to allow routing and debug levels to be set by means of
command line flags when the server is called).
The dce_svc_log_ routines provide read access to BINFILE format logs that are
created and written by the DCE serviceability routines; see the svcroute
serviceability file for further information. The dce_svc_log_handle_t typedef
is an opaque pointer to a handle for an opened log file.
Applications that use the serviceability interface can install a routine that
is effectively hooked into the operation of the interface. If a filter is
installed, it is called whenever one of the serviceability output routines
(dce_svc_printf) is about to output a message. When this happens, the filter
receives a group of parameters that describe the message that is about to be
output and the circumstances that provoked the action. The filter can then
allow the message output to proceed or suppress the message.
Along with the filter routine itself, the application also installs a filter
control routine, which permits the behavior of the filter to be altered
dynamically while the application is running. The dce_svc_filter routine is
the interface call-in to such an installed filter control.
There is also a set of macros that you can use in debugging production code.
See The DCE Serviceability Macros for more information.
See the following subtopics for more information:
The DCE Serviceability Routines
Serviceability Data Types and Structures
Serviceability Related Information
ΓòÉΓòÉΓòÉ 3.9.1. The DCE Serviceability Routines ΓòÉΓòÉΓòÉ
The serviceability routines listed in alphabetical order:
dce_setlocale Explicitly sets the DCE locale.
dce_svc_components Returns an array containing the names of all
components in the program that have been
registered with the dce_svc_register routine.
dce_svc_debug_routing Specifies both the level of an application's
serviceability debug messaging and where the
messages are routed.
dce_svc_debug_set_levels Sets serviceability debugging message levels for
a component.
dce_svc_define_filter Lets applications define serviceability
filtering routines.
dce_svc_filter Controls the behavior of the serviceability
message filtering routine, if one exists.
dce_svc_log_close Closes an open binary format serviceability log
and releases all internal states associated with
the handle.
dce_svc_log_get Reads the next entry from a binary format
serviceability log.
dce_svc_log_open Opens the specified file for reading.
dce_svc_log_rewind Rewinds the current reading position of the
specified (by handle) log file to the first
record.
dce_svc_printf Provides the normal routine for writing or
displaying serviceability messages.
dce_svc_register Registers a serviceability handle and
subcomponent table.
dce_svc_routing Specifies how normal (nondebug) serviceability
messages are routed.
dce_svc_set_progname If not called, the application's generated
serviceability messages are identified by its
process ID.
dce_svc_table Returns the serviceability subcomponent table
registered with the specified component.
dce_svc_unregister Destroys a serviceability handle and releases
all allocated resources associated with the
handle.
ΓòÉΓòÉΓòÉ 3.9.2. Serviceability Data Types and Structures ΓòÉΓòÉΓòÉ
dce_svc_filter_proc_t The prototype of a serviceability filtering
routine.
dce_svc_filterctl_proc_t The prototype of a serviceability filter-control
routine.
dce_svc_handle_t An opaque handle to generate serviceability
messages. (Use dce_svc_register or
DCE_DEFINE_SVC_HANDLE to obtain one.)
dce_svc_log_handle_t An opaque handle to an open serviceability
binary format log file. (Use dce_svc_log_open to
obtain one.)
dce_svc_log_prolog_t A structure containing data about a
serviceability binary format log entry.
dce_svc_prolog_t A structure containing the initial message
parameters passed to the filtering routine.
ΓòÉΓòÉΓòÉ 3.9.3. Serviceability Related Information ΓòÉΓòÉΓòÉ
Files:
dce\service.idl
dce\dce_svc.h
Books:
DCE for OS/2 Warp: Application Development Guide - Core Components
ΓòÉΓòÉΓòÉ 3.9.4. dce_setlocale ΓòÉΓòÉΓòÉ
Purpose
Explicitly sets the DCE locale.
Format
#include <dce\dce_msg.h>
char *dce_setlocale(DCE_LC_ALL,
const char *locale);
Parameters
Input
DCE_LC_ALL Set all locale categories.
locale Locale name expressed as a quoted string. See the DCE
for OS/2 Warp: Application Development Guide - Core
Components for information on valid locales.
Usage
The dce_setlocale routine:
o Is a wrapper function. The dce_setlocale routine calls the
runtime version of the setlocale routine, which is used by the
DCE code.
o Supports a subset of the standard setlocale routine.
o Supports the setting of all locale categories to a single locale
(but does not support the setting of individual locale
categories).
o Returns a pointer to a string that lists the values of the
locale categories. These values match the locale parameter of
the call.
Return Values
On error dce_setlocale returns NULL, and the locale is not changed.
Notes
DCE programs that do not use the locale model do not need to call
dce_setlocale because DCE will initialize a locale that matches the
OS/2 country and code page environment. DCE programs that call
setlocale, however, should also call dce_setlocale to ensure that
DCE's locale matches the locale of the program.
Because dce_setlocale is only used on OS/2, you should make sure that
any calls to dce_setlocale are within the bounds of an #ifdef for
portability.
Example
The following code fragment shows how the dce_setlocale routine is
used.
#include <dce_msg.h>
char *string;
void main(void)
{
/* Set the DCE locale to jajp932. Note that unless the
** DCE Japanese message files are present, DCE messages
** will be displayed or logged in English.
*/
#ifdef OS2
string = dce_setlocale(DCE_LC_ALL, "jajp932");
if (string != NULL)
{
printf(" %s \n",string);
}
#endif
}
The output is:
JAJP932 JAJP932 JAJP932 JAJP932 JAJP932 JAJP932
Related Information
Books:
DCE for OS/2 Warp: Application Development Guide - Core Components
ΓòÉΓòÉΓòÉ 3.9.5. dce_svc_components ΓòÉΓòÉΓòÉ
Purpose
Returns registered component names.
Format
#include <dce\dce.h>
#include <dce\svcremote.h>
void dce_svc_components(
dce_svc_stringarray_t *table,
error_status_t *status);
Parameters
Output
table An array containing the names of all components that
have been registered with the dce_svc_register routine.
status Returns the status code from this operation. The
following status codes are defined for serviceability:
svc_s_assertion_failed A programmer-developed
compile-time assertion failed.
svc_s_at_end No more data is available.
svc_s_bad_routespec See svcroute for information
on routing specification format.
svc_s_cantopen Permission is denied or the file
does not exist; consult errno.
svc_s_no_filter Attempted to send data to the
filter-control handle for a component that
does not have a filter registered.
svc_s_no_memory Could not allocate memory for
message table, string copy, or other internal
requirement.
svc_s_no_stats The definition of the return value
has not been specified.
svc_s_ok Operation performed.
svc_s_unknown_component Could not find the service
handle for a component.
Usage
The dce_svc_components routine returns an array containing the names
of all components in the program that have been registered with the
dce_svc_register routine.
Examples
The following code fragment shows how the dce_svc_components routine
should be used in the DCE application's implementation of the
serviceability remote interface. The following routine is the
implementation of the app_svc_inq_components operation defined in the
application's serviceability &per.epv file. Clients call this routine
remotely, and the routine, when called, first checks the caller's
authorization and then (if the client is authorized to perform the
operation) calls the dce_svc_components routine to perform the actual
operation.
/*****
*
* app_svc_inq_components -- remote request for list of all components registered
* by dce_svc_register().
*
*****/
static void app_svc_inq_components(
handle_t h,
dce_svc_stringarray_t *table,
error_status_t *st)
{
int ret;
/* Check the client's permissions here; if they are insufficient, */
/* deny the request. Otherwise, proceed with the operation... */
dce_svc_components(table, st);
}
Related Information
Files:
var\svc\routing
dce\service.idl
ΓòÉΓòÉΓòÉ 3.9.6. dce_svc_debug_routing ΓòÉΓòÉΓòÉ
Purpose
Specifies how debugging messages are routed.
Format
#include <dce\dce.h>
#include <dce\svcremote.h>
void dce_svc_debug_routing(
unsigned char *where,
error_status_t *status);
Parameters
Input
where A four-field routing string; the format is described in
svcroute.
Output
status Returns the status code from this operation. The
following status codes are defined for serviceability:
svc_s_assertion_failed A programmer-developed
compile-time assertion failed.
svc_s_at_end No more data is available.
svc_s_bad_routespec See svcroute for information
on routing specification format.
svc_s_cantopen Permission is denied or the file
does not exist; consult errno.
svc_s_no_filter Attempted to send data to the
filter-control handle for a component that
does not have a filter registered.
svc_s_no_memory Could not allocate memory for
message table, string copy, or other internal
requirement.
svc_s_no_stats The definition of the return value
has not been specified.
svc_s_ok Operation performed.
svc_s_unknown_component Could not find the service
handle for a component.
Usage
The dce_svc_debug_routing routine specifies both the level of the
application's serviceability debug messaging, and where the messages
are routed. The where parameter is a four-field routing string, as
described in svcroute. All four fields are required.
The routine is used to specify the disposition of serviceability
debug messages. If called before the component is registered (with
dce_svc_register), the disposition is stored until it is needed. In
case of error, the status parameter is filled in with an error code.
To set only the debugging level for a component, use the
dce_svc_debug_set_levels routine.
Related Information
Routines:
dce_svc_debug_set_levels
Files:
var\svc\routing
ΓòÉΓòÉΓòÉ 3.9.7. dce_svc_debug_set_levels ΓòÉΓòÉΓòÉ
Purpose
Sets the debugging level for a component.
Format
#include <dce\dce.h>
#include <dce\svcremote.h>
void dce_svc_debug_set_levels(
unsigned char *where,
error_status_t *status);
Parameters
Input
where A multifield string consisting of the component name
separated by a colon from a comma-separated list of
subcomponent/level pairs, as described in svcroute.
Output
status Returns the status code from this operation. The
following status codes are defined for serviceability:
svc_s_assertion_failed A programmer-developed
compile-time assertion failed.
svc_s_at_end No more data is available.
svc_s_bad_routespec See svcroute for information
on routing specification format.
svc_s_cantopen Permission is denied or the file
does not exist; consult errno.
svc_s_no_filter Attempted to send data to the
filter-control handle for a component that
does not have a filter registered.
svc_s_no_memory Could not allocate memory for
message table, string copy, or other internal
requirement.
svc_s_no_stats The definition of the return value
has not been specified.
svc_s_ok Operation performed.
svc_s_unknown_component Could not find the service
handle for a component.
Usage
The dce_svc_debug_set_levels routine sets serviceability debugging
message levels for a component. The where parameter is a multifield
string consisting of the component name separated by a colon from a
comma-separated list of subcomponent/level pairs, as described in
svcroute. The subcomponents are specified by codes defined in the
component's sams file; the levels are specified by single digits (1
through 9).
If the routine is called before the component is registered (with
dce_svc_register), the disposition is stored until it is needed. In
case of error, the status parameter is filled in with an error code.
To set both the debug level and routing for a component, use the
dce_svc_debug_routing routine.
Related Information
Routines:
dce_svc_debug_routing
Files:
var\svc\routing
ΓòÉΓòÉΓòÉ 3.9.8. dce_svc_define_filter ΓòÉΓòÉΓòÉ
Purpose
Defines DCE serviceability filtering routines.
Format
#include <stdarg.h>
#include <dce\dce.h>
#include <pthread.h>
#include <dce\svcfilter.h>
void dce_svc_define_filter(
dce_svc_handle_t handle,
dce_svc_filter_proc_t filter_function,
dce_svc_filterctl_proc_t filter_ctl_function,
error_status_t *status);
Parameters
Input
handle The handle (returned by dce_svc_log_open) of the log
file to be read.
filter_function The filter routine to be installed in the
serviceability mechanism.
filter_ctl_function A routine that can be called remotely to alter
the operation of the filtering routine.
Output
status Returns the status code from this operation. The
following status codes are defined for serviceability:
svc_s_assertion_failed A programmer-developed
compile-time assertion failed.
svc_s_at_end No more data is available.
svc_s_bad_routespec See svcroute for information
on routing specification format.
svc_s_cantopen Permission is denied or the file
does not exist; consult errno.
svc_s_no_filter Attempted to send data to the
filter-control handle for a component that
does not have a filter registered.
svc_s_no_memory Could not allocate memory for
message table, string copy, or other internal
requirement.
svc_s_no_stats The definition of the return value
has not been specified.
svc_s_ok Operation performed.
svc_s_unknown_component Could not find the service
handle for a component.
Usage
The serviceability interface provides a hook into the message-output
mechanism that allows applications to decide at the time of messaging
whether the given message should be output. The application defines
its own routine to perform whatever checking is desired, and installs
the routine (the filter_function parameter) with a call to
dce_svc_define_filter.
The filter routine to be installed must have the signature defined by
the dce_svc_filter_proc_t typedef. After it is installed, the routine
is automatically called every time a serviceability routine is called
to output a message. The filter receives a prolog argument that
contains all the pertinent information about the message. If the
filter returns TRUE, the message is output using the original
serviceability call. If the filter returns FALSE, the message is not
output. The information in the prolog allows these decisions to be
made on the basis of severity level, subcomponent, message index, and
so on. For details, see the header file dce\svcfilter.h.
In addition, an application that installs a message-filtering routine
must also define a routine that can be called remotely to alter the
operation of the filter routine. This procedure must have the
signature defined by the dce_svc_filterctl_proc_t typedef. The
routine is called with an opaque byte array parameter (and its
length), which it is free to interpret in an appropriate manner. The
remote-control routine is installed by the same call to
dce_svc_define_filter (as the filter_ctl_function parameter) in which
the filter itself is installed. See dce_svc_filter.
Examples
The following code fragment consists of example versions of an
application's routines to: filter serviceability messages; alter the
behavior of the filter routine; install the two routines.
/*****
* Filter routine-- this is the routine that is hooked into the serviceability
* mechanism when you install it by calling dce_svc_define_filter.
*****/
boolean app_filter(prolog, args)
dce_svc_prolog_t prolog;
va_list args;
{
if (filter_setting) {
printf("The value of filter_setting is TRUE\n");
printf("The progname is %s\n", prolog->progname);
if (prolog->attributes & svc_c_sev_notice)
printf("This is a Notice-type message\n");
switch (prolog->table_index) {
case app_s_server:
printf("Server sub-component\n");
break;
case app_s_refmon:
printf("Refmon sub-component\n");
break;
case app_s_manager:
printf("Manager sub-component\n");
break;
}
}
return 1;
}
/*****
* Filter Control routine-- this is the entry point for the remote-control
* call to modify the filter routine's behavior.
*****/
void app_filter_control(arg_size, arg, status)
idl_long_int arg_size;
idl_byte *arg;
error_status_t *status;
{
if (strncmp(arg, "Toggle", arg_size) != 0)
return;
else {
filter_setting = (filter_setting == FALSE) ? TRUE : FALSE;
if (filter_setting)
printf(" FILTER IS TURNED ON\n");
else
printf(" FILTER IS TURNED OFF\n");
}
return;
}
/*****
* install_filters-- calls dce_svc_define_filter to install the 2 previous routines.
*****/
void install_filters()
{
unsigned32 status;
filter_setting = TRUE;
dce_svc_define_filter(app_svc_handle,
(dce_svc_filter_proc_t)app_filter,
(dce_svc_filterctl_proc_t)app_filter_control, &status);
}
Related Information
Routines:
dce_svc_register
Macros:
DCE_SVC_DEFINE_HANDLE
ΓòÉΓòÉΓòÉ 3.9.9. dce_svc_filter ΓòÉΓòÉΓòÉ
Purpose
Controls the behavior of a serviceability filter.
Format
#include <dce\dce.h>
#include <dce\svcremote.h>
void dce_svc_filter(
dce_svc_string_t component,
idl_long_int arg_size,
idl_byte *argument,
error_status_t *status);
Parameters
Input
component The name of the serviceability-registered component,
defined in the component field of the sams file.
arg_size The number of characters contained in argument.
argument A string value to be interpreted by the target
component's filter control routine.
Output
status Returns the status code from this operation. The
following status codes are defined for serviceability:
svc_s_assertion_failed A programmer-developed
compile-time assertion failed.
svc_s_at_end No more data is available.
svc_s_bad_routespec See svcroute for information
on routing specification format.
svc_s_cantopen Permission is denied or the file
does not exist; consult errno.
svc_s_no_filter Attempted to send data to the
filter-control handle for a component that
does not have a filter registered.
svc_s_no_memory Could not allocate memory for
message table, string copy, or other internal
requirement.
svc_s_no_stats The definition of the return value
has not been specified.
svc_s_ok Operation performed.
svc_s_unknown_component Could not find the service
handle for a component.
Usage
The dce_svc_filter routine controls the behavior of the
serviceability message filtering routine, if one exists.
Along with the filter routine itself, the application also installs a
filter control routine. The purpose of this routine is to permit the
behavior of the filter to be altered dynamically while the
application is running. The dce_svc_filter routine is the interface's
call-in to such an installed filter control.
If an application has installed a serviceability filtering routine,
and if filter remote control is desired, the application's filter
routine (installed by the call to dce_svc_define_filter) should be
coded so that its operation can be switched to the various desired
alternatives by the values of static variables to which it has
access. These variables should also be accessible to the filter
control routine. The filter control routine thus receives from
dce_svc_filter an argument string, which it uses to set the
variables. The meaning of the contents of this string are entirely
application-defined.
Related Information
Files:
dce\service.idl
var\svc\routing
ΓòÉΓòÉΓòÉ 3.9.10. dce_svc_log_close ΓòÉΓòÉΓòÉ
Purpose
Closes an open log file.
Format
#include <dce\dce.h>
#include <pthread.h>
#include <dce\svclog.h>
void dce_svc_log_close(
dce_svc_log_handle_t handle,
error_status_t *status);
Parameters
Input
handle The handle (returned by dce_svc_log_open) of the log
file to be closed.
Output
status Returns the status code from this operation. The
following status codes are defined for serviceability:
svc_s_assertion_failed A programmer-developed
compile-time assertion failed.
svc_s_at_end No more data is available.
svc_s_bad_routespec See svcroute for information
on routing specification format.
svc_s_cantopen Permission is denied or the file
does not exist; consult errno.
svc_s_no_filter Attempted to send data to the
filter-control handle for a component that
does not have a filter registered.
svc_s_no_memory Could not allocate memory for
message table, string copy, or other internal
requirement.
svc_s_no_stats The definition of the return value
has not been specified.
svc_s_ok Operation performed.
svc_s_unknown_component Could not find the service
handle for a component.
Usage
The dce_svc_log_close routine closes an open binary format
serviceability log and releases all internal state associated with
the handle.
Related Information
Routines:
dce_svc_log_get
dce_svc_log_open
dce_svc_log_rewind
Files:
var\svc\routing
ΓòÉΓòÉΓòÉ 3.9.11. dce_svc_log_get ΓòÉΓòÉΓòÉ
Purpose
Reads the next record from a binary log file.
Format
#include <dce\dce.h>
#include <pthread.h>
#include <dce\svclog.h>
void dce_svc_log_get(
dce_svc_log_handle_t handle,
dce_svc_log_prolog_t *prolog,
error_status_t *status);
Parameters
Input
handle The handle (returned by dce_svc_log_open) of the log
file to be read.
Output
prolog A pointer to a structure containing information read
from the log file record.
status Returns the status code from this operation. The
following status codes are defined for serviceability:
svc_s_assertion_failed A programmer-developed
compile-time assertion failed.
svc_s_at_end No more data is available.
svc_s_bad_routespec See svcroute for information
on routing specification format.
svc_s_cantopen Permission is denied or the file
does not exist; consult errno.
svc_s_no_filter Attempted to send data to the
filter-control handle for a component that
does not have a filter registered.
svc_s_no_memory Could not allocate memory for
message table, string copy, or other internal
requirement.
svc_s_no_stats The definition of the return value
has not been specified.
svc_s_ok Operation performed.
svc_s_unknown_component Could not find the service
handle for a component.
Usage
The dce_svc_log_get routine reads the next entry from a binary format
serviceability log, and fills in prolog with a pointer to a private
data area containing the data read. The contents of the prolog
structure are defined in dce\svclog.h.
Related Information
Routines:
dce_svc_log_close
dce_svc_log_open
dce_svc_log_rewind
Files:
var\svc\routing
ΓòÉΓòÉΓòÉ 3.9.12. dce_svc_log_open ΓòÉΓòÉΓòÉ
Purpose
Opens a binary log file.
Format
#include <dce\dce.h>
#include <pthread.h>
#include <dce\svclog.h>
void dce_svc_log_open(
const char *name,
dce_svc_log_handle_t *handle,
error_status_t *status);
Parameters
Input
name The path name of the log file to be opened.
Output
handle A filled-in handle to the opened log file specified by
name.
status Returns the status code from this operation. The
following status codes are defined for serviceability:
svc_s_assertion_failed A programmer-developed
compile-time assertion failed.
svc_s_at_end No more data is available.
svc_s_bad_routespec See svcroute for information
on routing specification format.
svc_s_cantopen Permission is denied or the file
does not exist; consult errno.
svc_s_no_filter Attempted to send data to the
filter-control handle for a component that
does not have a filter registered.
svc_s_no_memory Could not allocate memory for
message table, string copy, or other internal
requirement.
svc_s_no_stats The definition of the return value
has not been specified.
svc_s_ok Operation performed.
svc_s_unknown_component Could not find the service
handle for a component.
Usage
The dce_svc_log_open routine opens the binary log file specified by
name for reading. If the call is successful, handle is filled in with
a handle to be used with the other dce_svc_log_ calls. On error,
status contains an error code.
Related Information
Routines:
dce_svc_log_close
dce_svc_log_get
dce_svc_log_rewind
ΓòÉΓòÉΓòÉ 3.9.13. dce_svc_log_rewind ΓòÉΓòÉΓòÉ
Purpose
Rewinds a binary log file to the first record.
Format
#include <dce\dce.h>
#include <pthread.h>
#include <dce\svclog.h>
void dce_svc_log_rewind(
dce_svc_log_handle_t handle,
error_status_t *status);
Parameters
Input
handle The handle (returned by dce_svc_log_open) of the log
file to be rewound.
Output
status Returns the status code from this operation. The
following status codes are defined for serviceability:
svc_s_assertion_failed A programmer-developed
compile-time assertion failed.
svc_s_at_end No more data is available.
svc_s_bad_routespec See svcroute for information
on routing specification format.
svc_s_cantopen Permission is denied or the file
does not exist; consult errno.
svc_s_no_filter Attempted to send data to the
filter-control handle for a component that
does not have a filter registered.
svc_s_no_memory Could not allocate memory for
message table, string copy, or other internal
requirement.
svc_s_no_stats The definition of the return value
has not been specified.
svc_s_ok Operation performed.
svc_s_unknown_component Could not find the service
handle for a component.
Usage
The dce_svc_log_rewind routine rewinds the current reading position
of the specified (by handle) binary log file to the first record.
Related Information
Routines:
dce_svc_log_close
dce_svc_log_get
dce_svc_log_open
ΓòÉΓòÉΓòÉ 3.9.14. dce_svc_printf ΓòÉΓòÉΓòÉ
Purpose
Generates a serviceability message.
Format
#include <dce\dce.h>
void dce_svc_printf(
DCE_SVC(dce_svc_handle_t handle,
char *argtypes),
const unsigned32 table_index,
const unsigned32 attributes,
const unsigned32 messageID,
...);
Parameters
Input
handle The serviceability handle of the caller.
argtypes Format string for the message.
table_index The message's subcomponent name. This symbol is
declared in the subcomponent list coded in Part II of
the sams file; its value is used to index into the
subtable of messages where the desired message is
located.
attributes Any routing, severity, action, or debug attributes that
are to associated with the generated message, ORed
together.
There are four categories of message attributes:
Routing The available routing attribute
constants are:
o svc_c_route_stderr
o svc_c_route_nolog
However, most routing is done
either by passing
specially-formatted strings to
dce_svc_routing or by environment
variable values. Note that using
the svc_c_route_nolog constant
without using svc_c_route_stderr
results in no message being
generated.
Severity The available severity attribute
constants are:
o svc_c_sev_fatal
o svc_c_sev_error
o svc_c_sev_warning
o svc_c_sev_notice
o svc_c_sev_notice_verbose
Action The available message action
attribute constants are:
o svc_c_action_abort
o svc_c_action_exit_bad
o svc_c_action_exit_ok
o svc_c_action_brief
o svc_c_action_none
Note that svc_c_action_brief is
used to suppress the standard
prolog.
Debug Level Nine different debug levels can be
specified
(svc_c_debug1...svc_c_debug9 or
svc_c_debug_off).
messageID The message ID, defined in the message code field in
the sams file. This parameter consists of one or more
attributes to be applied to the message that is to be
printed.
Note: You must specify at least one severity here.
Multiple attributes are ORed together.
... Any format arguments for the message string.
Usage
The dce_svc_printf routine is the normal routine for writing or
displaying serviceability messages. It cannot be called with a
literal text parameter. Instead, the message text is retrieved from a
message catalog or an in-core message table. These are generated by
the sams utility, which in turn outputs sets of tables from which the
messages are extracted for output.
There are two main ways to call the routine. If a message has been
defined in the sams file with both sub-component and attributes
specified, the sams output includes a convenience macro for the
message that can be passed as the single parameter to dce_svc_printf,
for example:
dce_svc_printf(SIGN_ON_MSG);
The convenience macro's name is generated from the uppercase version
of the message's code value (as specified in the sams file), with the
string _MSG appended.
If a convenience macro is not generated, or if you want to override
some of the message attributes at the time of output, you must call
the routine in its long form. An example of this form of the call is:
dce_svc_printf(DCE_SVC(app_svc_handle,""), app_subcomponent,\
svc_c_sev_error | svc_c_route_stderr, messageID);
DCE_SVC is a macro that must be passed as the first parameter to
dce_svc_printf if a convenience macro is not being used. It takes
two arguments:
o The caller's serviceability handle
o A format string for the message that is to be output
The format string is for use with messages that have been coded with
argument specifiers. It is a character string consisting of the
argument types as they would be passed to a printf call. If the
message is to be routed to a binary file, the format is extended to
include a %b specifier; using %b in a different routing gives
unpredictable results. The %b specifier takes two arguments, an
integer size and a buffer pointer.
Related Information
Routines:
dce_svc_register
Macros:
DCE_SVC_DEFINE_HANDLE
ΓòÉΓòÉΓòÉ 3.9.15. dce_svc_register ΓòÉΓòÉΓòÉ
Purpose
Registers a serviceability message table.
Format
#include <dce\dce.h>
dce_svc_handle_t dce_svc_register(
dce_svc_subcomp_t *table,
const idl_char *component_name,
error_status_t *status);
Parameters
Input
table A message table structure (defined in a header file
generated by sams during compilation).
component_name The serviceability name of the component, defined in
the component field of the sams file.
Output
status Returns the status code from this operation. The
following status codes are defined for serviceability:
svc_s_assertion_failed A programmer-developed
compile-time assertion failed.
svc_s_at_end No more data is available.
svc_s_bad_routespec See svcroute for information
on routing specification format.
svc_s_cantopen Permission is denied or the file
does not exist; consult errno.
svc_s_no_filter Attempted to send data to the
filter-control handle for a component that
does not have a filter registered.
svc_s_no_memory Could not allocate memory for
message table, string copy, or other internal
requirement.
svc_s_no_stats The definition of the return value
has not been specified.
svc_s_ok Operation performed.
svc_s_unknown_component Could not find the service
handle for a component.
Usage
The dce_svc_register routine registers a serviceability message
table. An application must call either this routine or the
DCE_SVC_DEFINE_HANDLE macro to set up its tables and obtain the
serviceability handle it must have in order to use the serviceability
interface.
Two parameters are required for the call: table is a pointer to the
application's serviceability table, defined in a file called
dceappsvc.h generated by the sams utility. component_name is a string
of the value app, which is defined in the component field of the sams
file where the serviceability messages are defined.
On error, this routine returns NULL and fills in status with an error
code.
Related Information
Routines:
dce_svc_debug_routing
dce_svc_debug_set_levels
dce_svc_define_filter
dce_svc_routing
dce_svc_unregister
Files:
var\svc\routing
Macros:
DCE_SVC_DEFINE_HANDLE
ΓòÉΓòÉΓòÉ 3.9.16. dce_svc_routing ΓòÉΓòÉΓòÉ
Purpose
Specifies routing of serviceability messages.
Format
#include <dce\dce.h>
#include <dce\svcremote.h>
void dce_svc_routing(
unsigned char *where,
error_status_t *status);
Parameters
Input
where A three-field routing string, as described in svcroute.
Output
status Returns the status code from this operation. The
following status codes are defined for serviceability:
svc_s_assertion_failed A programmer-developed
compile-time assertion failed.
svc_s_at_end No more data is available.
svc_s_bad_routespec See svcroute for information
on routing specification format.
svc_s_cantopen Permission is denied or the file
does not exist; consult errno.
svc_s_no_filter Attempted to send data to the
filter-control handle for a component that
does not have a filter registered.
svc_s_no_memory Could not allocate memory for
message table, string copy, or other internal
requirement.
svc_s_no_stats The definition of the return value
has not been specified.
svc_s_ok Operation performed.
svc_s_unknown_component Could not find the service
handle for a component.
Usage
The dce_svc_routing routine specifies how normal (nondebug)
serviceability messages are routed. The where parameter is a
three-field routing string, as described in svcroute. For
convenience, the first field of the routing specifier, which
indicates the message severity type to which the routing is to be
applied, can be an asterisk (*) to indicate that all messages,
whatever their severity, should be routed as specified.
If the routine is called before the component is registered (with the
dce_svc_register routine), the routing is stored until it is needed.
In case of error, the status parameter is filled in with an error
code.
Related Information
Files:
dce\service.idl
var\svc\routing
ΓòÉΓòÉΓòÉ 3.9.17. dce_svc_set_progname ΓòÉΓòÉΓòÉ
Purpose
Sets an application's program name.
Format
#include <dce\dce.h>
void dce_svc_set_progname(
char *program_name,
error_status_t *status);
Parameters
Input
program_name A string containing the name that is to be included in
the text of all serviceability messages that the
application generates during the session.
Output
status Returns the status code from this operation. The
following status codes are defined for serviceability:
svc_s_assertion_failed A programmer-developed
compile-time assertion failed.
svc_s_at_end No more data is available.
svc_s_bad_routespec See svcroute for information
on routing specification format.
svc_s_cantopen Permission is denied or the file
does not exist; consult errno.
svc_s_no_filter Attempted to send data to the
filter-control handle for a component that
does not have a filter registered.
svc_s_no_memory Could not allocate memory for
message table, string copy, or other internal
requirement.
svc_s_no_stats The definition of the return value
has not been specified.
svc_s_ok Operation performed.
svc_s_unknown_component Could not find the service
handle for a component.
Usage
The dce_svc_set_progname routine sets the application's program name,
which is included in serviceability messages. This allows
serviceability messages from more than one application to be written
to the same file and still be distinguishable as to their separate
origins.
If dce_svc_set_progname is not called, the application-generated
serviceability messages are identified by its process ID.
Examples
If an application sets its program name to be demo_program, as shown:
dce_svc_set_progname("demo_program", &status);
serviceability messages generated by the program resemble the
following:
1994-04-05-20:13:34.500+00:00I----- demo_program NOTICE app main.c 123 0xa444e208
<message text>
If the application does not set its program name, its generated
serviceability messages have the following form:
1994-04-05-20:13:34.500+00:00I----- PID#9467 NOTICE app main.c 123 0xa444e208
<message text>
Related Information
Routines:
dce_printf, dce_fprintf, and dce_sprintf
dce_svc_printf
Macros:
DCE_SVC_DEBUG
ΓòÉΓòÉΓòÉ 3.9.18. dce_svc_table ΓòÉΓòÉΓòÉ
Purpose
Returns a registered component's subcomponent table.
Format
#include <dce\dce.h>
#include <dce\svcremote.h>
void dce_svc_table(
dce_svc_string_t component,
dce_svc_subcomparray_t *table,
error_status_t *status);
Parameters
Input
component The name of the serviceability-registered component,
defined in the component field of the application's
sams file.
Output
table An array of elements, each of which describes one
serviceability subcomponent (as defined in its sams
file).
status Returns the status code from this operation. The
following status codes are defined for serviceability:
svc_s_assertion_failed A programmer-developed
compile-time assertion failed.
svc_s_at_end No more data is available.
svc_s_bad_routespec See svcroute for information
on routing specification format.
svc_s_cantopen Permission is denied or the file
does not exist; consult errno.
svc_s_no_filter Attempted to send data to the
filter-control handle for a component that
does not have a filter registered.
svc_s_no_memory Could not allocate memory for
message table, string copy, or other internal
requirement.
svc_s_no_stats The definition of the return value
has not been specified.
svc_s_ok Operation performed.
svc_s_unknown_component Could not find the service
handle for a component.
Usage
The dce_svc_table routine returns the serviceability subcomponent
table registered with the specified component. The returned table
consists of an array of elements; each describes one subcomponent.
Each element consists of four fields, which contain the subcomponent
name, its description, its message catalog ID, and the current value
of its debug message level. The first three of these values are
specified in the sams file that is processed during the compiling of
the application, and from which the application's message catalogs
and other serviceability and message files are generated.
Examples
The following code fragment shows how the remote operation can be
called from the client side of an application, and how the results
might print out:
#include <dce\rpc.h>
#include <dce\service.h>
handle_t svc_bind_handle;
dce_svc_string_t component;
dce_svc_subcomparray_t subcomponents_table;
error_status_t remote_status;
int i;
dce_svc_inq_table(svc_bind_handle, component, &subcomponents_table, &remote_status);
fprintf(stdout, "Subcomponent table size received is: %d...\n",
subcomponents_table.tab_size);
fprintf(stdout, "Subcomponent table contents are:\n");
for (i = 0; i < subcomponents_table.tab_size; i++)
{
fprintf(stdout, "Name: %s\n",
subcomponents_table.table[i].sc_name);
fprintf(stdout, "Desc: %s\n",
subcomponents_table.table[i].sc_descr);
fprintf(stdout, "Msg Cat ID: 0x%8.8lx\n",
(long) subcomponents_table.table[i].sc_descr_msgid);
fprintf(stdout, "Active debug level: %d\n\n",
subcomponents_table.table[i].sc_level);
}
Related Information
Files:
dce\service.idl
ΓòÉΓòÉΓòÉ 3.9.19. dce_svc_unregister ΓòÉΓòÉΓòÉ
Purpose
Destroys a serviceability handle.
Format
#include <dce\dce.h>
void dce_svc_unregister(
dce_svc_handle_t handle,
error_status_t *status);
Parameters
Input
handle The application's serviceability handle, originally
returned by a call to dce_svc_register or filled in by
the DCE_SVC_DEFINE_HANDLE macro.
Output
status Returns the status code from this operation. The
following status codes are defined for serviceability:
svc_s_assertion_failed A programmer-developed
compile-time assertion failed.
svc_s_at_end No more data is available.
svc_s_bad_routespec See svcroute for information
on routing specification format.
svc_s_cantopen Permission is denied or the file
does not exist; consult errno.
svc_s_no_filter Attempted to send data to the
filter-control handle for a component that
does not have a filter registered.
svc_s_no_memory Could not allocate memory for
message table, string copy, or other internal
requirement.
svc_s_no_stats The definition of the return value
has not been specified.
svc_s_ok Operation performed.
svc_s_unknown_component Could not find the service
handle for a component.
Usage
The dce_svc_unregister routine destroys a serviceability handle.
Calling this routine closes any open serviceability message routes
and frees all allocated resources associated with the handle.
The handle parameter is the serviceability handle that was originally
returned by the call to dce_svc_register, or filled in by the
DCE_SVC_DEFINE_HANDLE macro. On error, the routine fills in status
with an error code.
Note that it is not usually necessary to call this routine, because
the normal process exit will perform the required cleanup.
Related Information
Routines:
dce_svc_register
Macros:
DCE_SVC_DEFINE_HANDLE
ΓòÉΓòÉΓòÉ 3.9.20. svcroute ΓòÉΓòÉΓòÉ
Purpose
The routing control file for DCE serviceability messages.
Usage
The file svc\routing specifies routing for serviceability messages.
The default location for svc\routing is the DCE local data directory
(typically \opt\dcelocal\var). The environment variable
DCE_SVC_ROUTING_FILE, if set, specifies a different location for the
file.
The file consists of a series of text lines. Blank lines and lines
that begin with a # (number sign) character are ignored when the
file's contents are interpreted. All other lines must consist of
either three or four fields, each separated by a : (colon). Leading
white space is ignored.
Lines consisting of three fields specify routing for non-debug
serviceability messages. Their format is:
sev:out_form:dest[;out_form:dest...] \
[GOESTO:{sev | comp}]
o The sev (severity) field specifies one of the following message
severities:
FATAL Irrecoverable error exit. An unrecoverable
error (such as database corruption) has
occurred and probably requires manual
intervention to be corrected. The program
usually terminates immediately after such an
error.
ERROR Error detected. An unexpected event that is
non-terminal (such as a timeout), or is
correctable by human intervention, has
occurred. The program continues operation,
although some functions or services may no
longer be available. This severity level can
also be used to indicate that a particular
request or action could not be completed.
WARNING Correctable error. An error occurred that
was automatically corrected (for example, a
configuration file was not found and default
values were used instead). This severity
level may also be used to indicate a
condition that could be an error if the
effects are undesirable (for example,
removing all files as a side-effect of
removing a non-empty directory). This
severity level can also be used to indicate a
condition that, if not corrected, eventually
results in an error (for example, a printer
that is running low on paper).
NOTICE Informational notice. A significant routine
major event has occurred; for example, a
server has started.
NOTICE_VERBOSE Verbose information notice. A significant
routine event has occurred; for example, a
directory entry was removed.
o The out_form (output form) field specifies how the messages of a
given severity level should be processed, and must be one of the
following:
BINFILE Write these messages as a binary log entry
to the specified file.
TEXTFILE Write these messages as human-readable text.
FILE Equivalent to TEXTFILE.
DISCARD Do not record messages of this severity
level.
STDOUT Write these messages as human-readable text
to standard output.
STDERR Write these messages as human-readable text
to standard error.
Files written as BINFILEs can be read and manipulated with a
set of log file functions (for more information, see
dce_svc_log_open and dce_svc_log_get) or by the svcdumplog
command.
The out_form specifier can be followed by a two-number
specifier of the form .gens.count where:
- gens is an integer that specifies the number of files (that
is, generations) that should be kept
- count is an integer specifying how many entries (that is,
messages) should be written to each file
The multiple files are named by appending a dot to the simple
specified name, dest, followed by the current generation
number. When the number of entries in a file reaches the
maximum specified by count, the file is closed, the
generation number is incremented, and the next file is
opened. When the maximum number of files has been created and
filled, the generation number is reset to 1, and a new file
with that number is created and written to (thus overwriting
the already-existing file with the same name), and so on, as
long as messages are being written. Thus the files wrap
around to the beginning, and the total number of log files
never exceeds gens, although messages continue to be written
as long as the program continues writing them. Note that when
a program starts, the generation starts at 1.
o The dest (destination) field is a path name that specifies where
the message should be sent. This field can be left blank if the
out_form specified is DISCARD, STDOUT, or STDERR. The field can
also contain a %ld string in the file name, which, when the file
is written, is replaced by the process ID of the program that
wrote the message. File names must not contain colons or
periods.
Multiple routings for the same severity level can be specified
by adding the additional desired routings as semicolon-separated
out_form:dest strings. For example,
FATAL:TEXTFILE:\dev\console
WARNING:DISCARD:--
NOTICE:STDERR:-;BINFILE.50.100:\tmp\log%ld
specifies that:
- Fatal error messages should be sent to the console.
- Warnings should be discarded.
- Notices should be written to both standard error and as
binary entries in files located in the \tmp directory. No
more than 50 files should be written, and there should be
no more than 100 messages written to each file. The files
have names of the form:
\tmp\logprocess_id.n
where process_id is the process ID of the program
originating the messages, and n is the generation number of
the file (expressed with only as many digits as needed).
o The GOESTO specifier allows messages for the severity whose
routing specification it occurs in to be routed to the same
destination (and in the same output form) as those for the
other, specified, severity level (or component name). For
example, the following specification:
WARNING:STDERR:;GOESTO:FATAL
FATAL:STDERR:;FILE:\tmp\foo
means that WARNING messages should show up in three places:
twice to stderr, and once to the file \tmp\foo.
Note that a GOESTO specification should be the last element in a
multidestination route specification.
Routing Serviceability Messages by Environment Variable
Serviceability message routing can also be specified by the values of
certain environment variables. If environment variables are used,
the routings they specify override any conflicting routes specified
by the routing file.
The routes are specified on the basis of severity level by putting
the desired routing instructions in their corresponding environment
variables:
o SVC_FATAL
o SVC_ERROR
o SVC_WARNING
o SVC_NOTICE
o SVC_NOTICE_VERBOSE
Each variable should contain a single string in the following format:
out_form:dest[;out_form:dest...]
where out_form and dest have the same meanings and form as previously
stated. Multiple routings can be specified with semicolon-separated
additional substrings specifying the additional routes, as shown.
Setting Serviceability Debug Message Levels
Nine serviceability debug message levels (specified respectively by
single digits from 1 to 9) are available. The precise meaning of
each level varies with the application or DCE component in question,
but the general notion is that ascending to a higher level (for
example, from 2 to 3) increases the level of informational detail in
the messages.
Setting debug messaging at a certain level means that all levels up
to and including the specified level are enabled. For example, if
the debug level is set at 4, the 1, 2, and 3 levels are enabled as
well.
The general format for the debug level specifier string is:
component:sub_comp.level,sub_comp.level,...
where:
o component is the 3-character serviceability component code for
the program whose debug message levels are being specified.
o sub_comp.level is a serviceability subcomponent name, followed
(after a dot) by a debug level (expressed as a single digit from
1 to 9). Note that multiple subcomponent/level pairs can be
specified in the string.
If there are multiple subcomponents and you want to set the debug
level to be the same for all of them, the form:
component:*.level
does this (where the * (asterisk) specifies all subcomponents).
Routing Serviceability Debug Messages
Routing for serviceability debug messages can be specified in either
of the two following ways:
o By the contents of the SVC_COMP_DBG environment variable (where
COMP is the code of the component, converted to uppercase, where
debug message routing is to be set).
o By the contents of the \svc\routing routing file.
The routing is specified by the contents of a specially-formatted
string that is either included in the value of the environment
variable or in the contents of the routing file.
The general format for the debug routing specifier string is:
component:sub_comp.level,...:out_form::dest[;out_form:dest...]\
[GOESTO:{sev | component}]
where component, sub_comp.level, out_form, dest, and sev have the
same meanings as defined earlier in this reference page.
For example, consider the following string value:
hel:*.4:STDERR:-;TEXTFILE:\tmp\hel_debug_log_%ld
This value, when assigned to the SVC_HEL_DBG environment variable,
sets the debug level and routing for all hel subcomponents. A debug
level of 4 is specified, and all debug messages of that level or
lower are written both to standard error, and in text form to the
file \tmp\hel_debug_log_process_ID, where process_ID is the process
ID of the program writing the messages.
ΓòÉΓòÉΓòÉ 3.10. The DCE Serviceability Macros ΓòÉΓòÉΓòÉ
The DCE_SVC_DEFINE_HANDLE macro is used to create a serviceability handle. This
handle can be useful in a library that has no explicit initialization routine
where a call to dce_svc_register could be added. The remaining macros can be
"compiled out" of production code or left in to aid diagnostics, depending on
whether DCE_DEBUG (normally found in dce\dce.h) is defined.
See the following subtopics for more information:
List of Serviceability Macros
Related Information for Macros
ΓòÉΓòÉΓòÉ 3.10.1. List of Serviceability Macros ΓòÉΓòÉΓòÉ
The serviceability macros are listed in alphabetical order:
dce_assert Adds runtime "can't happen" assertions (such as
programming errors) to programs.
DCE_SVC_DEBUG Used to generate debugging output.
DCE_SVC_DEBUG_ATLEAST Can be used to test the debug level of a
subcomponent for a specified handle. Tests
whether the debug level is at least at the
specified level.
DCE_SVC_DEBUG_IS Can be used to test the debug level of a
subcomponent for a specified handle. The macro
tests for an exact match with the specified
level.
DCE_SVC_DEFINE_HANDLE Registers a serviceability message table.
DCE_SVC_LOG Generates debugging output based on a message
defined in an application's sams file.
ΓòÉΓòÉΓòÉ 3.10.2. Related Information for Macros ΓòÉΓòÉΓòÉ
Books:
DCE for OS/2 Warp: Application Development Guide - Core Components
Files:
dce\service.idl
dce\dce_svc.h
ΓòÉΓòÉΓòÉ 3.10.3. dce_assert ΓòÉΓòÉΓòÉ
Purpose
Inserts program diagnostics.
Format
#define DCE_ASSERT
#include <dce\assert.h>
void dce_assert(
dce_svc_handle_t handle,
int expression);
Parameters
Input
handle A registered serviceability handle.
expression An expression that is to be tested for truth.
Usage
The dce_assert macro is used to add runtime "can't happen" assertions
to programs (that is, programming errors). On execution, when
expression evaluates to 0 (that is, to FALSE), dce_svc_printf is
called with parameters to generate a message identifying the
expression, source file, and line number. The message is generated
with a severity level of svc_c_sev_fatal, with the svc_c_action_abort
flag specified (which causes the program to end when the assertion
fails and the message is generated). See the dce_svc_register
reference page for more information.
The handle parameter should be a registered serviceability handle; it
can also be NULL, which means that an internal serviceability handle
is used.
Assertion-checking can be enabled or disabled at compile time. The
header file dce\assert.h can be included multiple times. If
DCE_ASSERT is defined before the header is included, assertion
checking is performed. If it is not so defined, the
assertion-checking code is not compiled in. The system default is
set in dce\dce.h.
Related Information
Routines:
dce_svc_register
ΓòÉΓòÉΓòÉ 3.10.4. DCE_SVC_DEBUG ΓòÉΓòÉΓòÉ
Purpose
Output a serviceability debug message.
Format
#include <dce\dce.h>
DCE_SVC_DEBUG((
dce_svc_handle_t handle,
const unsigned32 table_index,
unsigned32 debug_level,
char *format,
...));
Parameters
Input
handle The caller's serviceability handle.
table_index The message's subcomponent name (defined in the sams
file).
debug_level Serviceability debug level for the message.
format The message string.
... Format arguments, if any.
Usage
The DCE_SVC_DEBUG macro is used to generate debugging output. Because
it is a macro that takes a variable number of arguments, the entire
parameter list must be enclosed in two sets of parentheses. The
handle and table_index parameters are as described for
dce_svc_printf.
In contrast to the normal operation of the serviceability interface,
DCE_SVC_DEBUG requires the caller to specify the message as a string
literal in the call, rather than to define it in the application's
sams file with a message ID.
The debug_level argument indicates the level of detail associated
with this message and must be in the range svc_c_debug1 to
svc_c_debug9.
The value of debug_level associates the message with one of nine
levels, and whether the message is actually generated at run time
depends on the debugging level that has been set for the application.
The level can be set by the application itself (by a call to
dce_svc_debug_set_levels or dce_svc_debug_routing) or by the value of
an environment variable or a serviceability routing file; see
svcroute for further information.
The significance of the various levels is application-defined, but in
general, the higher levels (numbers) imply more detail in debugging
output.
The format and ... parameters are passed directly to fprintf or its
equivalent.
Related Information
Routines:
dce_svc_debug_routing
dce_svc_debug_set_levels
dce_svc_printf
dce_svc_routing
Files:
var\svc\routing
ΓòÉΓòÉΓòÉ 3.10.5. DCE_SVC_DEBUG_ATLEAST ΓòÉΓòÉΓòÉ
Purpose
Tests a component's serviceability debug level.
Format
#include <dce\dce.h>
DCE_SVC_DEBUG_ATLEAST(
dce_svc_handle_t handle,
const unsigned32 table_index,
unsigned32 debug_level);
Parameters
Input
handle The caller's serviceability handle.
table_index The subcomponent name (defined in the sams file) that
is being tested for debug level.
debug_level Debug level being tested.
Usage
If serviceability debug code was enabled (by defining DCE_DEBUG)
during compilation, the DCE_SVC_DEBUG_ATLEAST and DCE_SVC_DEBUG_IS
macros can be used to test the debug level of a subcomponent
(specified by table_index) for the specified handle.
DCE_SVC_DEBUG_ATLEAST tests whether the debug level is at least at
the specified level. DCE_SVC_DEBUG_IS tests for an exact match with
the specified level. In either case, the specified level should be a
number between 1 and 9.
Related Information
Macros:
DCE_SVC_DEBUG
DCE_SVC_DEBUG_IS
DCE_SVC_LOG
ΓòÉΓòÉΓòÉ 3.10.6. DCE_SVC_DEBUG_IS ΓòÉΓòÉΓòÉ
Purpose
Tests a component's serviceability debug level.
Format
#include <dce\dce.h>
DCE_SVC_DEBUG_IS(
dce_svc_handle_t handle,
const unsigned32 table_index,
unsigned32 debug_level);
Parameters
Input
handle The caller's serviceability handle.
table_index The name of the subcomponent (defined in the sams file)
that is being tested for debug level.
debug_level The serviceability debug level being tested.
Usage
If serviceability debug code was enabled (by defining DCE_DEBUG)
during compilation, the DCE_SVC_DEBUG_ATLEAST and DCE_SVC_DEBUG_IS
macros can be used to test the debug level of a subcomponent
(specified by table_index) for the specified handle.
DCE_SVC_DEBUG_ATLEAST tests whether the debug level is at least at
the specified level. DCE_SVC_DEBUG_IS tests for an exact match with
the specified level. In either case, the specified level should be a
number between 1 and 9.
Related Information
Macros:
DCE_SVC_DEBUG
DCE_SVC_DEBUG_ATLEAST
DCE_SVC_LOG
ΓòÉΓòÉΓòÉ 3.10.7. DCE_SVC_DEFINE_HANDLE ΓòÉΓòÉΓòÉ
Purpose
Creates a serviceability handle.
Format
#include <dce\dce.h>
DCE_SVC_DEFINE_HANDLE(dce_svc_handle_t handle,
dce_svc_subcomp_t *table,
const idl_char *component_name);
Parameters
Input
table A message table structure (defined in a header file
generated by sams during compilation).
component_name The serviceability name of the component, defined in
the component field of the sams file.
Output
handle A serviceability handle structure filled in by the
macro.
Usage
There are two ways to register a serviceability table before using
the serviceability interface in an application. The first is to
create a global variable using the DCE_SVC_DEFINE_HANDLE macro. The
handle parameter is the serviceability handle, table is a pointer to
the component's message table, and component_name is the name of the
serviceability component (application). The macro creates a skeleton
variable that is completed the first time the handle is used. This
can be useful when writing library code that has no explicit
initialization routine.
The second method is to call the dce_svc_register routine.
Notes
Syntax errors will occur under some compile-time environments if
spaces are inserted between the parentheses and the parameters. This
macro defines data structures, not executable code. Therefore, you
must include it in the global definitions section of a program.
Related Information
Routines:
dce_svc_register
ΓòÉΓòÉΓòÉ 3.10.8. DCE_SVC_LOG ΓòÉΓòÉΓòÉ
Purpose
Outputs a binary form of a serviceability debug message.
Format
#include <dce\dce.h>
DCE_SVC_LOG((
dce_svc_handle_t handle,
const unsigned32 table_index,
unsigned32 debug_level,
const unsigned32 messageid,
...));
Parameters
Input
handle The caller's serviceability handle.
table_index The message's subcomponent name (defined in the sams
file).
debug_level Serviceability debug level for the message.
messageid A message ID, defined in the message's code field in
the sams file.
... Any format arguments for the message string.
Usage
The DCE_SVC_LOG macro is used to generate debugging output based on a
message defined in an application's sams file (in this respect it is
unlike DCE_SVC_DEBUG, where the message is specified as a literal
string parameter). Because it is a macro that takes a variable number
of arguments, the entire parameter list must be enclosed in two sets
of parentheses. The handle and table_index parameters are as
described for dce_svc_printf.
DCE_SVC_LOG generates a record in the serviceability binary format;
it is not a conventional serviceability message as such. When the
binary log is read (see svcdumplog), the text of the message is
reconstructed from the application's installed message catalog.
The debug_level argument indicates the level of detail associated
with the message and must be in the range svc_c_debug1 to
svc_c_debug9.
The value of debug_level associates the message with one of nine
levels, and whether the message is actually generated at run time
depends on the debugging level that has been set for the application.
The level can be set by the application itself (by a call to
dce_svc_debug_set_levels or dce_svc_debug_routing) or by the value of
an environment variable or a serviceability routing file; see
svcroute for further information.
The significance of the various levels is application-defined, but in
general the higher levels (numbers) imply more detail in debugging
output.
Related Information
Macros:
DCE_SVC_DEBUG
DCE_SVC_DEBUG_ATLEAST
DCE_SVC_DEBUG_IS
Files:
var\svc\routing
ΓòÉΓòÉΓòÉ 3.11. The DCE Host Daemon Routines ΓòÉΓòÉΓòÉ
This introduces the DCE Host Daemon application programming interface: the dced
API. This API gives management applications remote access to various data,
servers, and services on DCE hosts. Servers manage their own configuration in
the local dced by using the routines starting with dce_server, introduced in
The DCE Server Routines.
See the following subtopics for more information:
The dced API Naming Conventions
dced Binding Routines
Generic Entry Routines
Generic Routines to Read Data Objects
Host Data Management Routines
Server Configuration Control Routines
Server Execution Control Routines
Security Validation Routines
Key Table Management Routines
Host Daemon Data Types and Structures
Related Information for Host Daemon
ΓòÉΓòÉΓòÉ 3.11.1. The dced API Naming Conventions ΓòÉΓòÉΓòÉ
All of the dced API routine names begin with the dced_ prefix. This API
contains some specialized routines that operate on services represented by the
following keywords in the routine names:
hostdata The host data management service stores host-specific data such
as the DCE host name, the host's cell name, and other data, and
it provides access to these data items.
server The server control service configures, starts, and stops
servers, among other things. Applications must distinguish two
general states of server control: server configuration
(srvrconf) and server execution (srvrexec).
secval The security validation service maintains a host's principal
identity and ensures applications that the DCE Security daemon
is genuine.
keytab The key table management service remotely manages key tables.
The dced also provides the endpoint mapper service, which has its own API,
described with the RPC API. These routines begin with rpc_ep_ and
rpc_mgmt_ep_.
Because some of the dced daemon services require the same operations (but on
different data types), the dced API also contains generic routines that can
operate on more than one of the preceding services. For example, you use the
routine dced_object_read to read a data item (object) from the hostdata,
srvrconf, srvrexec, or keytab services.
ΓòÉΓòÉΓòÉ 3.11.2. dced Binding Routines ΓòÉΓòÉΓòÉ
A binding must be established to a dced service on a particular host before you
can use any other dced routines. The resources of the dced binding should also
be released when an application is finished with the service.
dced_binding_create Establishes a dced binding to a host service.
dced_binding_from_rpc_binding Establishes a dced binding to a dced service
on the host specified in a previously
established RPC binding handle to any server.
dced_binding_set_auth_info Sets authentication, authorization, and
protection level information for a dced
binding handle.
dced_binding_free Releases the resources of a dced binding
handle.
ΓòÉΓòÉΓòÉ 3.11.3. Generic Entry Routines ΓòÉΓòÉΓòÉ
All data maintained by dced is managed as entries. Most of the services of
dced have lists of entries traversed with a cursor that describe where the
actual data is maintained.
dced_entry_add Adds a keytab or hostdata entry.
dced_entry_get_next Obtains the next data entry from a list of
entries.
dced_entry_remove Removes a hostdata or keytab data entry from dced.
dced_initialize_cursor Obtains a list of data entries from dced and sets
a cursor at the beginning of the list.
dced_release_cursor Releases the resources associated with a cursor
that traverses a service's list of entries.
dced_list_get Returns the list of data entries maintained by a
DCE Host service.
dced_list_release Releases the resources of a list of entries.
dced_inq_id Obtains the UUID associated with an entry name.
dced_inq_name Obtains the name associated with an entry UUID.
ΓòÉΓòÉΓòÉ 3.11.4. Generic Routines to Read Data Objects ΓòÉΓòÉΓòÉ
These routines obtain the actual data for items to which entries refer
(objects).
dced_object_read Reads one data item of a dced service, based on
the entry UUID.
dced_object_read_all Reads all the data of a dced service's entry list.
dced_objects_release Releases the resources allocated for data
obtained.
ΓòÉΓòÉΓòÉ 3.11.5. Host Data Management Routines ΓòÉΓòÉΓòÉ
dced_hostdata_create Creates a hostdata item and the associated entry.
dced_hostdata_read Reads a hostdata item.
dced_hostdata_write Replaces an existing hostdata item.
dced_hostdata_delete Deletes a hostdata item from a specific host and
removes the associated entry.
ΓòÉΓòÉΓòÉ 3.11.6. Server Configuration Control Routines ΓòÉΓòÉΓòÉ
dced_server_create Creates a DCE server's configuration data.
dced_server_modify_attributes Modifies a DCE server's configuration data.
dced_server_delete Deletes a DCE server's configuration data.
dced_server_start Starts a DCE-configured server.
ΓòÉΓòÉΓòÉ 3.11.7. Server Execution Control Routines ΓòÉΓòÉΓòÉ
dced_server_disable_if Disables a service provided by a server.
dced_server_enable_if Re-enables a service provided by a server.
dced_server_stop Stops a DCE-configured server.
ΓòÉΓòÉΓòÉ 3.11.8. Security Validation Routines ΓòÉΓòÉΓòÉ
dced_secval_start Starts a host's security validation service.
dced_secval_validate Validates that the DCE Security daemon (secd) used
by a specific host is legitimate.
dced_secval_status Returns a status parameter of TRUE if the security
validation service is activated and FALSE if it is
not activated.
dced_secval_stop Stops a host's security validation service.
ΓòÉΓòÉΓòÉ 3.11.9. Key Table Management Routines ΓòÉΓòÉΓòÉ
dced_keytab_create Creates a key table with a list of keys in a new
file.
dced_keytab_delete Deletes a key table file and removes the
associated entry.
dced_keytab_initialize_cursor Obtains a list of keys from a key table and sets
a cursor at the beginning of the list.
dced_keytab_get_next_key Returns a key from a cached list and advances the
cursor.
dced_keytab_release_cursor Releases the resources associated with a cursor
that traverses a key table.
dced_keytab_add_key Adds a key to a key table.
dced_keytab_change_key Changes a key in both a key table and in the
security registry.
dced_keytab_remove_key Removes a key from a key table.
ΓòÉΓòÉΓòÉ 3.11.10. Host Daemon Data Types and Structures ΓòÉΓòÉΓòÉ
The following data types used with the dced API are defined in
dce\dced_base.idl and are shown here in alphabetical order.
dced_attr_list_t This data structure specifies the configuration
attributes to use when you start a server with dced.
The structure consists of the following:
count An unsigned32 number representing the
number of attributes in the list.
list An array of configuration attributes
where each element is of type
sec_attr_t. This data type is
described in DCE Security Services
API. For dced, the list[i].attr_id
field can have values of either
dced_g_uuid_fileattr, specifying plain
text, or dced_g_uuid_binfileattr,
specifying binary data.
dced_binding_handle_t A dced binding handle is an opaque pointer that
refers to information that includes a dced service
(hostdata, srvrconf, srvrexec, secval, or keytab) and
RPC binding information for a specific DCE Host
daemon.
dced_cursor_t The entry list cursor is an opaque pointer used to
keep track of a location in an entry list between
calls that traverse the list.
dced_entry_t An entry is the structure that contains information
about a data item (or object) maintained by a dced
service. The actual data is maintained elsewhere.
Each entry consists of the following structure
members:
id A unique identifier of type
uuid_t that dced maintains for
every data item it maintains.
name The name for the data item. The
data type is dced_string_t.
description A brief description of the data
item (of type dced_string_t) for
the convenience of human users.
storage_tag A string of type dced_string_t
describing the location of the
actual data. This is
implementation-specific and can
be a file (with a path name) on
the host system or a storage
identifier for the dced process.
dced_entry_list_t An entry list is a uniform way to list the data items
a dced service maintains. The entry list structure
contains a list of all the entries for a given
service. For example, the complete list of all
entries of hostdata, server configuration data,
server execution data, and keytab data are each
maintained in separate entry lists. The structure
consists of the following:
count An unsigned32 number representing the
number of entries in the list.
list An array of entries where each element
is of type dced_entry_t.
dced_key_t A key consists of the following structure members:
principal A dced_string_t type string
representing the principal
for the key.
version An unsigned32 number
representing the version
number of the key.
authn_service An unsigned32 number
representing the
authentication service used.
passwd A pointer to a password.
This is of type
sec_passwd_rec_t. See also
DCE Security Services API.
dced_key_list_t A key list contains all the keys for a given key
table and consists of the following structure
elements:
count An unsigned32 number representing the
number of keys in the list.
list An array of keys where each element is
of type dced_key_t.
dced_keytab_cursor_t The keytab cursor is an opaque pointer used to keep
track of a location in a key list between calls that
traverse the list.
dced_opnum_list_t A list of operation numbers is used in the service_t
structure. This structure consists of the following
fields:
count An unsigned32 number representing the
number of operations in the list.
list An array of UUIDs where each element
is of type uuid_t.
dced_service_type_t The dced service type distinguishes the services
provided by dced. It is an enumerated type used
mainly in a parameter of the
dced_binding_from_rpc_binding routine. It can have
one of the following values:
dced_e_service_type_hostdata The host data
management
service
dced_e_service_type_srvrconf The server
configuration
management
service
dced_e_service_type_srvrexec The server
execution
management
service
dced_e_service_type_secval The security
validation
service
dced_e_service_type_keytab The key table
management
service
dced_e_service_type_null A NULL service
type used
internally
dced_string_t This data type is a character string from the
Portable Character Set (PCS).
dced_string_list_t A list of strings with the following format:
count An unsigned32 number representing the
number of strings in the list.
list An array of strings where each element
is of type dced_string_t.
dced_tower_list_t A list of protocol towers used in the service_t
structure. This structure consists of the following
fields:
count An unsigned32 number representing the
number of protocol towers in the list.
list An array of pointers where each
element is a pointer to a protocol
tower of the type
sec_attr_twr_set_p_t. This data type
is described in DCE Security Services
API.
server_fixedattr_t This structure is a field in the server_t structure.
It contains the following fields:
startupflags This field is of type
unsigned32 and can be any
combination of the following
bits:
server_c_startup_at_boot
This means that
dced should
start the server
when dced is
started.
server_c_startup_auto This
means that the
server can be
started
automatically if
dced determines
there is a need.
server_c_startup_explicit
This means dced
can start the
server if it
receives an
explicit command
to do so from
dced_server_start
or the dcecp
operation server
start.
server_c_startup_on_failure
This means that
the server
should be
restarted by
dced if it exits
with an
unsuccessful
exit status.
Several bits are also reserved
for vendor-specific startup and
include:
server_c_startup_vendor1
server_c_startup_vendor2
server_c_startup_vendor3
server_c_startup_vendor4
flags This represents the execution
state of the server and is the
unsigned32 type. This field is
maintained by dced only and
should not be modified. Valid
values to check for are
self-explanatory and include
the following:
server_c_exec_notrunning
server_c_exec_running
Several bits are also reserved for
vendor-specific execution states and include:
server_c_exec_vendor1
server_c_exec_vendor2
server_c_exec_vendor3
server_c_exec_vendor4
program This is the full path name of
the server and is of type
dced_string_t.
arguments This is a list of arguments for
the server and is of type
dced_string_list_t.
prerequisites This is an advisory field that
means this server is a client
of other prerequisite servers
whose IDs are in a list of type
uuid_list_t. The UUIDs should
be the id fields from the
server_t structures of the
relevant servers.
keytables This is a list of keytab entry
UUIDs representing the key
tables for this server and is
of type uuid_list_t.
posix_uid This is a POSIX execution
attribute for the user ID. It
is of type unsigned32.
posix_gid This is a POSIX execution
attribute for the group ID. It
is of type unsigned32.
posix_dir This is a POSIX execution
attribute for the directory
where the server started when
it is invoked. It is of type
dced_string_t.
server_t The DCE Host daemon describes a server as follows:
id Each server has a unique ID of
type uuid_t.
name Each server's name is of type
dced_string_t.
entryname The server's entry name is a hint
as to where the server occurs in
the name space. This is of type
dced_string_t.
services Each server offers a list of
services specified in a list of
type service_list_t. This
structure has the following
members:
count An unsigned32
number
representing the
number of services
in the list.
list A pointer to an
array of services
where each element
is of type
service_t.
fixed This is a set of attributes
common to all DCE
implementations. The data type
is server_fixedattr_t.
attributes This field is of type
dced_attr_list_t and contains a
list of attributes representing
the behavior specific to a
particular server or host.
prin_names This field is a list of principal
names for the server and is of
type dced_string_list_t.
exec_data Data about an executing server is
maintained in a tagged union
(named tagged_union) with a
discriminator of type unsigned32
named execstate representing the
server's execution state. The
union has the following two
execution states:
server_c_exec_notrunning For
the case where the
server is not
running, the union
member has no
value. For
example:
if(server->exec_data.execstate ==
server_c_exec_notrunning)
server->exec_data.tagged_union = NULL;
server_c_exec_running For
the case where the
server is running,
and the value of
the union member
is a
srvrexec_data_t
data type named
running_data. A
srvrexec_data_t
structure contains
the following
members:
instance Each
instance
of
a
server
on
a
host
is
identified
with
a
UUID
(type
uuid_t).
posix_pid
Each
server
has
a
POSIX
process
ID
of
type
unsigned32.
service_t This structure describes each service offered by a
server. The server_t structure, described earlier,
contains an array of these structures. The service_t
structure contains the following fields:
ifspec An interface specification of
type rpc_if_id_t, generated by an
idl compilation of the interface
definition representing the
service. This data type is
described in The DCE Remote
Procedure Call API.
ifname An interface name of type
dced_string_t.
annotation An annotation about the purpose
of the interface (type
dced_string_t). This field is for
user display purposes only.
flags The flag field is of type
unsigned32 and currently has only
one bit field defined,
service_c_disabled. If this flag
is set, it indicates that the
service is not currently
available for the server. Also,
the dced Endpoint Mapper will not
map an endpoint to a disabled
service. Several values are also
reserved for vendor-specific use
and include
service_c_vendor1
service_c_vendor2
service_c_vendor3
service_c_vendor4
entryname The entry name (type
dced_string_t) is a clue to the
location of this service in the
name space. If the value is NULL,
the value in the entryname field
of the server_t structure is
used.
objects This is a list of objects
supported by the service. The
list is of type uuid_list_t.
operations This is a list of operation
numbers of type
dced_opnum_list_t. This field is
not currently used.
towers This is a list of protocol towers
of type dced_tower_list_t,
specifying the endpoints where
this server can be reached.
srvrexec_stop_method_t The server execution stop method is an enumerated
type with one of the following values:
srvrexec_stop_rpc Stops the running server
gracefully by letting the
server complete all
outstanding remote
procedure calls. This
causes dced to invoke the
rpc_mgmt_server_stop_listening
routine in that server.
srvrexec_stop_soft This uses a
system-specific
mechanism, such as the
SIGTERM signal. It stops
the running server with a
mechanism that the server
can ignore or intercept
in order to do
application-specific
cleanup.
srvrexec_stop_hard This uses a
system-specific
mechanism, such as the
SIGKILL signal. It stops
the running server
immediately with a
mechanism that the server
cannot intercept.
srvrexec_stop_error This uses a
system-specific
mechanism, such as the
SIGABRT signal. The local
operating system captures
the server state before
stopping it, and the
server can also intercept
it.
uuid_list_t A list of UUIDs in the following format:
count An unsigned32 number representing the
number of UUIDs in the list.
list A pointer to an array of UUIDs where
each element is of type uuid_t.
ΓòÉΓòÉΓòÉ 3.11.11. Related Information for Host Daemon ΓòÉΓòÉΓòÉ
Books:
DCE for OS/2 Warp: Application Development Guide - Core Components
Files:
dce\dced_base.h
dce\dced.h
dce\dced_data.h
dce\rpctypes.idl
dce\passwd.idl
dce\sec_attr_base.idl
ΓòÉΓòÉΓòÉ 3.11.12. dced_binding_create ΓòÉΓòÉΓòÉ
Purpose
Establishes a dced binding to one of the host services of a remote
(or the local) dced.
Format
#include <dce\dced.h>
void dced_binding_create(
dced_string_t service,
unsigned32 binding_flags,
dced_binding_handle_t *dced_bh,
error_status_t *status);
Parameters
Input
service A character string that specifies a host daemon service
name and an optional remote host. A service name is
specified with one of the following: hostdata,
srvrconf, srvrexec, secval, or keytab. The format of a
complete service and host specification is one of the
following:
service_name A service at the local host.
Pre-existing defined values
include:
dced_c_service_hostdata
dced_c_service_srvrconf
dced_c_service_srvrexec
dced_c_service_secval
dced_c_service_keytab
service_name@hosts\host_name A service at a host
anywhere in the local name
space.
\.:\hosts\host_name\config\service_name A complete
specification for
service_name@host, where the
host is anywhere in the local
name space.
\...\cell\hosts\host_name\config\service_name A
service at a host anywhere in
the global name space.
binding_flags Currently, the only valid flag value is
dced_c_binding_syntax_default.
Output
dced_bh Returns a dced binding handle, which is a pointer to an
opaque data structure containing information about an
RPC binding, the host, the host service, and a local
cache.
status Returns the status code from this routine. This status
code indicates whether the routine completed
successfully or, if not, why not. The possible status
codes are:
error_status_ok
dce_cf_e_no_mem
dced_s_invalid_arg
dced_s_no_memory
dced_s_unknown_service
rpc_s_entry_not_found
rpc_s_incomplete_name
rpc_s_invalid_object
rpc_s_name_service_unavailable
rpc_s_no_memory
rpc_s_no_more_bindings
rpc_s_no_ns_permission
Usage
The dced on each DCE host maintains the host services and provides a
remote interface to them. The host services include:
o Endpoint Mapper
o Host Data Management (hostdata)
o Server Management, including Server Configuration (srvrconf) and
Server Execution (srvrexec)
o Security Validation (secval)
o Key Table Management (keytab)
The dced_binding_create routine establishes a dced binding to a dced
service and it (or dced_binding_from_rpc_binding) must be the first
dced API routine called before an application can access one of the
host services with other dced API routines. When an application is
finished with the service, it should call the dced_binding_free
routine to free resources. To establish a dced binding to your local
host's dced, you can use the service name by itself, and do not need
to specify a host.
To access the endpoint map directly, use rpc_mgmt_ep_elt_inq_begin
and associated routines.
Examples
This example establishes a dced binding to the server configuration
service on the host patrick.
dced_binding_handle_t dced_bh;
error_status_t status;
dced_binding_create("srvrconf@hosts\patrick",
dced_c_binding_syntax_default,
&dced_bh,
&status);
.
.
.
/* Other routines including dced API routines. */
.
.
.
dced_binding_free(dced_bh, &status);
Related Information
Routines:
dced_binding_free
dced_binding_from_rpc_binding
Books:
DCE for OS/2 Warp: Application Development Guide - Core Components
ΓòÉΓòÉΓòÉ 3.11.13. dced_binding_free ΓòÉΓòÉΓòÉ
Purpose
Releases the resources associated with a dced binding handle.
Format
#include <dce\dced.h>
void dced_binding_free(
dced_binding_handle_t dced_bh,
error_status_t *status);
Parameters
Input
dced_bh Specifies a dced binding handle to free for a dced
service on a specific host.
Output
status Returns the status code from this routine. This status
code indicates whether the routine completed
successfully or, if not, why not. The possible status
codes are:
error_status_ok
rpc_s_invalid_binding
rpc_s_wrong_kind_of_binding
Usage
The dced_binding_free routine frees resources used by a dced binding
handle and referenced information. Use this routine when your
application has finished using a host service to break the
communication between your application and the dced. The dced binding
handle and referenced information is created with the
dced_binding_create or dced_binding_from_rpc_binding routine.
Related Information
Routines:
dced_binding_create
dced_binding_from_rpc_binding
Books:
DCE for OS/2 Warp: Application Development Guide - Core Components
ΓòÉΓòÉΓòÉ 3.11.14. dced_binding_from_rpc_binding ΓòÉΓòÉΓòÉ
Purpose
Establishes a dced binding to one of the host services on the host
specified in an existing RPC binding handle.
Format
#include <dce\dced.h>
void dced_binding_from_rpc_binding(
dced_service_type_t service,
handle_t rpc_bh,
dced_binding_handle_t *dced_bh,
error_status_t *status);
Parameters
Input
service A variable that specifies one of the host services. A
valid variable name includes one of the following:
dced_e_service_type_hostdata
dced_e_service_type_srvrconf
dced_e_service_type_srvrexec
dced_e_service_type_secval
dced_e_service_type_keytab
rpc_bh An RPC binding handle to some server.
Output
dced_bh Returns a dced binding handle, which is a pointer to an
opaque data structure containing information about an
RPC binding, the host, the host service, and a local
cache.
status Returns the status code from this routine. This status
code indicates whether the routine completed
successfully or, if not, why not. The possible status
codes are:
error_status_ok
dced_s_no_memory
dced_s_unknown_service
ept_s_cant_perform_op
ept_s_database_invalid
ept_s_invalid_context
ept_s_invalid_entry
rpc_s_comm_failure
rpc_s_fault_context_mismatch
rpc_s_invalid_arg
rpc_s_invalid_binding
rpc_s_no_more_elements
rpc_s_wrong_kind_of_binding
Usage
The dced on each DCE host maintains the host services and provides a
remote interface to the services. The dced_binding_from_rpc_binding
routine establishes a dced binding to a dced service, and it (or
dced_binding_create) must be the first dced API routine called before
an application can access one of the host services with other dced
routines. When an application finishes using the service, it should
call the dced_binding_free routine to free resources.
Prior to using the RPC binding in this routine, make a copy of the
binding by using the rpc_binding_copy routine. This is necessary if
the application needs to continue using the RPC binding, because
otherwise the dced binding takes over the RPC binding.
The RPC binding can be obtained from a call to specific RPC runtime
routines such as rpc_binding_from_string_binding,
rpc_ns_binding_import_next, or rpc_ns_binding_lookup_next.
Examples
The following example obtains an RPC binding from a string binding,
and it later makes a copy of the RPC binding for use in the
dced_binding_from_rpc_binding routine.
handle_t rpc_bh, binding_handle;
dced_binding_handle_t dced_bh;
dced_service_type_t service_type;
error_status_t status;
unsigned_char_t string_binding[STRINGLEN];
.
.
.
rpc_binding_from_string_binding(string_binding, &binding_handle, &status);
.
.
.
rpc_binding_copy(binding_handle, &rpc_bh, &status);
dced_binding_from_rpc_binding(service_type, rpc_bh, &dced_bh, &status);
.
.
.
/* Other routines including dced API routines. */
.
.
.
dced_binding_free(dced_bh, &status);
Related Information
Routines:
dced_binding_free
dced_binding_create
rpc_ns_binding_import_next
rpc_ns_binding_lookup_next
rpc_binding_from_string_binding
rpc_binding_copy
Books:
DCE for OS/2 Warp: Application Development Guide - Core Components
ΓòÉΓòÉΓòÉ 3.11.15. dced_binding_set_auth_info ΓòÉΓòÉΓòÉ
Purpose
Sets authentication and authorization information for a dced binding
handle.
Format
#include <dce\dced.h>
void dced_binding_set_auth_info(
dced_binding_handle_t dced_bh,
unsigned32 protect_level,
unsigned32 authn_service,
rpc_auth_identity_handle_t authn_identity,
unsigned32 authz_service,
error_status_t *status);
Parameters
Input
dced_bh Specifies the dced binding handle for which to set the
authentication and authorization information.
protect_level Specifies the protection level for dced API calls that
will use the dced binding handle dced_bh.
authn_service Specifies the authentication service to use for dced
API calls that will use the dced binding handle
dced_bh.
authn_identity Specifies a handle for the data structure that
contains the calling application's authentication and
authorization credentials appropriate for the selected
authn_service and authz_service services.
Specify NULL to use the default security login context
for the current address space.
authz_service Specifies the authorization service to be implemented
by dced for the host service accessed.
Output
status Returns the status code from this routine. This status
code indicates whether the routine completed
successfully or, if not, why not. The possible status
codes are:
error_status_ok
dced_s_bad_binding
dced_s_no_support
ept_s_not_registered
rpc_s_authn_authz_mismatch
rpc_s_binding_incomplete
rpc_s_comm_failure
rpc_s_invalid_binding
rpc_s_mgmt_op_disallowed
rpc_s_rpcd_comm_failure
rpc_s_unknown_authn_service
rpc_s_unsupported_protect_level
rpc_s_wrong_kind_of_binding
Usage
The dced_binding_set_auth_info routine sets up the dced binding
handle so that it can be used for authenticated calls that include
authorization information. The rpc_binding_set_auth_info routine
performs in the same way as this one. Prior to calling this routine,
the application must have established a valid dced binding handle by
calling either the dced_binding_create or
dced_binding_from_rpc_binding routine.
Examples
This example establishes a dced binding to a host's key table
service, and then it calls dced_binding_set_auth_info so that the
application is authorized to access remote key tables by using
additional calls to the key table service.
dced_binding_handle_t dced_bh;
error_status_t status;
dced_binding_create((dced_string_t)"keytab@hosts\patrick",
dced_c_binding_syntax_default,
&dced_bh, &status);
dced_binding_set_auth_info(dced_bh,
rpc_c_protect_level_default,
rpc_c_authn_pkt_privacy,
NULL, rpc_c_authz_dce, &status);
.
.
.
/* Other routines including dced API routines. */
.
.
.
Related Information
Routines:
rpc_binding_set_auth_info
dced_binding_create
dced_binding_from_rpc_binding
Books:
DCE for OS/2 Warp: Application Development Guide - Core Components
ΓòÉΓòÉΓòÉ 3.11.16. dced_entry_add ΓòÉΓòÉΓòÉ
Purpose
Adds a keytab or hostdata entry to a host's dced for an existing file
on that host.
Format
#include <dce\dced.h>
void dced_entry_add(
dced_binding_handle_t dced_bh,
dced_entry_t *entry,
error_status_t *status);
Parameters
Input
dced_bh Specifies the dced binding handle for a dced service on
a specific host.
Input/Output
entry Specifies the data entry to add to the service.
Output
status Returns the status code from this routine. This status
code indicates whether the routine completed
successfully or, if not, why not. The possible status
codes are:
error_status_ok
db_s_readonly
db_s_store_failed
dced_s_already_exists
dced_s_bad_binding
dced_s_import_cant_access
dced_s_no_support
rpc_s_binding_has_no_auth
sec_acl_invalid_permission
uuid_s_no_address
Usage
The dced_entry_add routine adds a data entry to a dced service. The
data it refers to must already exist in a file on the dced's host.
You can add only hostdata or keytab entries.
A service's data entries do not contain the actual data. Instead,
they contain a UUID, a name for the entry, a brief description of the
item, and a storage tag that describes the location of the actual
data. In the cases of the hostdata and keytab services, the data for
each entry is stored in a file. The dced uses this two-level scheme
so that it can manipulate different kinds of data in the same way and
so names are independent of local file system requirements.
The hostdata and keytab services each have their respective routines
to create new data and, at the same time, add a new entry to the
appropriate service. These routines are dced_hostdata_create and
dced_keytab_create.
Prior to calling the dced_entry_add routine, the application must
have established a valid dced binding handle for the hostdata or
keytab service by calling either the dced_binding_create or the
dced_binding_from_rpc_binding routine.
Examples
The following example shows how to add a printer configuration file
to the hostdata service. The example creates a dced binding to the
local hostdata service, fills an entry data structure with the
storage tag containing the full path of the existing configuration
file, and finally calls the dced_entry_add routine.
dced_binding_handle_t dced_bh;
error_status_t status;
dced_entry_t entry;
dced_binding_create(dced_c_service_hostdata,
dced_c_binding_syntax_default,
&dced_bh, &status);
uuid_create(&(entry.id), &status);
entry.name = (dced_string_t)("NEWERprinter");
entry.description = (dced_string_t)("Configuration for a new printer.");
entry.storage_tag = (dced_string_t)("/etc/NEWprinter");
dced_entry_add(dced_bh, &entry, &status);
.
.
.
Related Information
Routines:
dced_entry_remove
dced_hostdata_create
dced_keytab_create
dced_binding_create
dced_binding_from_rpc_binding
Books:
DCE for OS/2 Warp: Application Development Guide - Core Components
ΓòÉΓòÉΓòÉ 3.11.17. dced_entry_get_next ΓòÉΓòÉΓòÉ
Purpose
Obtains one data entry from a list of entries of a dced service.
Format
#include <dce\dced.h>
void dced_entry_get_next(
dced_cursor_t cursor,
dced_entry_t **entry,
error_status_t *status);
Parameters
Input/Output
cursor Specifies the entry list's cursor that points to an
entry, and returns the cursor advanced to the next
entry in the list.
Output
entry Returns a pointer to an entry.
status Returns the error_status_ok status code upon successful
completion. Otherwise, dced_s_no_more_entries is
returned.
Usage
The dced_entry_get_next routine obtains a pointer to a data entry,
and advances the cursor to the next entry in the list. This routine
is commonly used in a loop to traverse a host service's entry list.
The data is obtained in an undetermined order. Prior to using this
routine, the application must call dced_initialize_cursor to obtain a
list of entries and to establish the beginning of the cursor. When
the application is finished traversing the entry list, it should call
dced_release_cursor to release resources.
A data entry does not contain the actual data, but it contains the
name, identity, description, and storage location of the data. In
the cases of hostdata and keytab services, the data for each entry is
stored in a file. In the cases of srvrconf and srvrexec services,
data is stored in memory. The dced uses this two-level scheme so
that it can manipulate different kinds of data in the same way.
Prior to using the dced_entry_get_next routine, the application must
have established a valid dced binding handle by calling either the
dced_binding_create or dced_binding_from_rpc_binding routine.
Examples
In the following example, a dced binding is obtained from a service
type and an existing rpc binding handle. After establishing an entry
list cursor, the dced_entry_get_next routine obtains entries, one at
a time, and the name and description of each entry is displayed until
the entry list is exhausted.
dced_binding_from_rpc_binding(service_type, rpc_bh, &dced_bh, &status);
dced_initialize_cursor(dced_bh, &cursor, &status);
for( ; ; ) { /* infinite loop */
dced_entry_get_next(cursor, &entry, &status);
if(status != error_status_ok) break;
display(entry->name, entry->description); /* application specific */
}
dced_release_cursor(&cursor, &status);
dced_binding_free( dced_bh, &status);
Related Information
Routines:
dced_initialize_cursor
dced_release_cursor
dced_binding_create
dced_binding_from_rpc_binding
Books:
DCE for OS/2 Warp: Application Development Guide - Core Components
ΓòÉΓòÉΓòÉ 3.11.18. dced_entry_remove ΓòÉΓòÉΓòÉ
Purpose
Removes a hostdata or keytab data entry from a dced service's list of
entries.
Format
#include <dce\dced.h>
void dced_entry_remove(
dced_binding_handle_t dced_bh,
uuid_t *entry_uuid,
error_status_t *status);
Parameters
Input
dced_bh Specifies the dced binding handle for a dced service on
a specific host.
entry_uuid Specifies the UUID of the entry to be removed from the
service.
Output
status Returns the status code from this routine. This status
code indicates whether the routine completed
successfully or, if not, why not. The possible status
codes are:
error_status_ok
db_s_del_failed
db_s_key_not_found
db_s_readonly
dced_s_bad_binding
dced_s_no_support
dced_s_not_found
sec_acl_invalid_permission
Usage
The dced_entry_remove routine removes an entry from the hostdata or
keytab service entry list of dced. It does not remove the actual data
stored in the file, but makes it inaccessible from a remote host by
using the dced user interfaces, which include the dced API and the
DCE control program, dcecp. Each host service that maintains data
also maintains a list of data entries. A data entry contains a name,
a UUID, a brief description, and a storage tag indicating the
location of the actual data.
To delete both the data and entry for the hostdata, keytab, or
srvrconf services use dced_hostdata_delete, dced_keytab_delete, or
dced_server_delete, respectively. (The srvrexec service is maintained
by dced only and the secval service does not maintain data, so you
cannot remove data for these services.)
Applications commonly obtain an entry by traversing the entry list
using the dced_entry_get_next routine with its associated cursor
routines.
Prior to calling the dced_entry_remove routine, the application must
have established a valid dced binding handle to the hostdata or
keytab service by calling either the dced_binding_create or
dced_binding_from_rpc_binding routine.
Related Information
Routines:
dced_hostdata_delete
dced_keytab_delete
dced_server_delete
dced_initialize_cursor
dced_binding_create
dced_binding_from_rpc_binding
Books:
DCE for OS/2 Warp: Application Development Guide - Core Components
ΓòÉΓòÉΓòÉ 3.11.19. dced_hostdata_create ΓòÉΓòÉΓòÉ
Purpose
Creates a hostdata item and the associated entry in dced on a
specific host.
Format
#include <dce\dced.h>
void dced_hostdata_create(
dced_binding_handle_t dced_bh,
dced_entry_t *entry,
dced_attr_list_t *data,
error_status_t *status);
Parameters
Input
dced_bh Specifies the dced binding handle for the host data
service on a specific host.
data Specifies the data created and written to a file on the
host. The dced_attr_list_t consists of a count of the
number of attributes and an array of attributes of type
sec_attr_t. The reference implementation has one
attribute for a hostdata item (file contents). However,
some vendors may provide multiple attributes.
Input/Output
entry Specifies the hostdata entry to create. You supply a
name (entry->name), description (entry->description),
and file name (entry->storage_tag), in the form of dced
strings. You can supply a UUID (entry->id) for dced to
use or you can use a NULL value and dced generates a
new UUID for the entry.
Output
status Returns the status code from this routine. This status
code indicates whether the routine completed
successfully or, if not, why not. The possible status
codes are:
error_status_ok
db_s_key_not_found
db_s_readonly
db_s_store_failed
dced_s_already_exists
dced_s_bad_binding
dced_s_cant_open_storage_file
dced_s_import_already_exists
dced_s_unknown_attr_type
sec_acl_invalid_permission
Usage
The dced_hostdata_create routine creates a new host data item in a
file on the host to which the dced binding handle refers, and it
generates the associated hostdata entry in the host's dced.
If data that you want to add to the host data service already exists
on the host (in a file), you can add it to the service by calling
dced_entry_add, which creates the new data entry for dced only.
Prior to calling the dced_hostdata_create routine, the application
must have established a valid dced binding handle to the hostdata
service by calling either the dced_binding_create or
dced_binding_from_rpc_binding routine.
Examples
The following example creates a binding to the host data service on
the local host, creates the entry data, and fills in the data
structure for one attribute to a hypothetical printer configuration.
The attribute represents a plain-text file containing one string of
data.
dced_binding_handle_t dced_bh;
error_status_t status;
dced_entry_t entry;
dced_attr_list_t data;
int num_strings, str_size;
sec_attr_enc_str_array_t *attr_array;
dced_binding_create(dced_c_service_hostdata,
dced_c_binding_syntax_default,
&dced_bh, &status);
/*Create an Entry. */
uuid_create(&entry.id, &status);
entry.name = (dced_string_t)("NEWERprinter");
entry.description = (dced_string_t)("Configuration for a new printer.");
entry.storage_tag = (dced_string_t)("/etc/NEWprinter");
/* create the attributes */
data.count = 1;
num_strings = 1;
data.list = (sec_attr_t *)malloc(data.count * sizeof(sec_attr_t) );
data.list->attr_id = dced_g_uuid_fileattr;
data.list->attr_value.attr_encoding = sec_attr_enc_printstring_array;
str_size = sizeof(sec_attr_enc_str_array_t) +
num_strings * sizeof(sec_attr_enc_printstring_p_t);
attr_array = (sec_attr_enc_str_array_t *)malloc(str_size);
data.list->attr_value.tagged_union.string_array = attr_array;
attr_array->num_strings = num_strings;
attr_array->strings[0] = (dced_string_t)("New printer configuration data");
dced_hostdata_create(dced_bh, &entry, &data, &status);
dced_binding_free(dced_bh, &status);
Related Information
Routines:
dced_entry_add
dced_hostdata_read
dced_binding_create
dced_binding_from_rpc_binding
Books:
DCE for OS/2 Warp: Application Development Guide - Core Components
ΓòÉΓòÉΓòÉ 3.11.20. dced_hostdata_delete ΓòÉΓòÉΓòÉ
Purpose
Deletes a hostdata item from a specific host and removes the
associated entry from dced.
Format
#include <dce\dced.h>
void dced_hostdata_delete(
dced_binding_handle_t dced_bh,
uuid_t *entry_uuid,
error_status_t *status);
Parameters
Input
dced_bh Specifies the dced binding handle for the hostdata
service on a specific host.
entry_uuid Specifies the UUID of the hostdata entry (and
associated data) to delete.
Output
status Returns the status code from this routine. This status
code indicates whether the routine completed
successfully or, if not, why not. The possible status
codes are:
error_status_ok
db_s_bad_index_type
db_s_del_failed
db_s_iter_not_allowed
db_s_key_not_found
dced_s_bad_binding
dced_s_cant_remove_storage_file
dced_s_not_found
sec_acl_invalid_permission
Usage
The dced_hostdata_delete routine deletes a hostdata item (a file)
from a specific host and removes the associated entry from the
hostdata service of the dced for that host.
If you want to make the data inaccessible remotely but not delete it,
use the dced_entry_remove routine, which removes the data's hostdata
entry only.
Prior to calling the dced_hostdata_delete routine, the application
must have established a valid dced binding handle for the hostdata
service by calling either the dced_binding_create or
dced_binding_from_rpc_binding routine.
Attention
Do not delete the standard hostdata items such as cell_name,
cell_aliases, host_name, post_processors, or dce_cf.db. Removal of
any of these items causes operational problems for the host.
Related Information
Routines:
dced_entry_remove
dced_hostdata_read
dced_binding_create
dced_binding_from_rpc_binding
Books:
DCE for OS/2 Warp: Application Development Guide - Core Components
ΓòÉΓòÉΓòÉ 3.11.21. dced_hostdata_read ΓòÉΓòÉΓòÉ
Purpose
Reads a hostdata item maintained by dced on a specific host.
Format
#include <dce\dced.h>
void dced_hostdata_read(
dced_binding_handle_t dced_bh,
uuid_t *entry_uuid,
uuid_t *attr_uuid,
sec_attr_t **data,
error_status_t *status);
Parameters
Input
dced_bh Specifies the dced binding handle for the hostdata
service on a specific host.
entry_uuid Specifies the hostdata entry UUID associated with the
data to read.
attr_uuid Specifies the UUID associated with an attribute of the
data. The attribute is either plain text
(dced_g_uuid_fileattr) or binary
(dced_g_uuid_binfileattr). Some vendors might allow
other attributes.
Output
data Returns the data for the item. See DCE Security
Services API for details on the sec_attr_t data type.
status Returns the status code from this routine. This status
code indicates whether the routine completed
successfully or, if not, why not. The possible status
codes are:
error_status_ok
db_s_bad_index_type
db_s_key_not_found
dce_cf_e_file_open
dce_cf_e_no_match
dce_cf_e_no_mem
dced_s_bad_binding
dced_s_cant_open_storage_file
dced_s_invalid_attr_type
dced_s_no_memory
sec_acl_invalid_permission
uuid_s_bad_version
Usage
The dced_hostdata_read routine returns a hostdata item maintained by
dced on a specific host. The standard data items include the cell
name, a list of cell aliases, the DCE host name, a list of
UUID-program pairs (post_processors), and the DCE configuration
database, among other items. For programming convenience, the
following global variables are defined for the entry_uuid of some
standard data items:
dced_g_uuid_cell_name
dced_g_uuid_cell_aliases
dced_g_uuid_host_name
dced_g_uuid_hostdata_post_proc
dced_g_uuid_dce_cf_db
dced_g_uuid_pe_site
dced_g_uuid_svc_routing
Other host-specific data items can also be maintained by the hostdata
service. The UUIDs for these are established when the data item is
created (See dced_hostdata_create). After the application reads host
data and when it is done with the data, it should call the
dced_objects_release routine to release the resources allocated.
Each hostdata item for a specific host is stored in a local file.
The name of an item's storage file is indicated in the storage tag
field of each dced hostdata entry.
You can also use the dced_object_read routine to read the text of a
hostdata item. You can use this routine if your application needs to
read data for other host services (srvrconf, srvrexec, or keytab) in
addition to data for the hostdata service.
Prior to calling the dced_hostdata_read routine, the application must
have established a valid dced binding handle to the hostdata service
by calling either the dced_binding_create or
dced_binding_from_rpc_binding routine.
Related Information
Routines:
dced_objects_release
dced_object_read
dced_binding_create
dced_binding_from_rpc_binding
Books:
DCE for OS/2 Warp: Application Development Guide - Core Components
ΓòÉΓòÉΓòÉ 3.11.22. dced_hostdata_write ΓòÉΓòÉΓòÉ
Purpose
Replaces an existing hostdata item maintained by dced on a specific
host.
Format
#include <dce\dced.h>
void dced_hostdata_write(
dced_binding_handle_t dced_bh,
uuid_t *entry_uuid,
dced_attr_list_t *data,
error_status_t *status);
Parameters
Input
dced_bh Specifies the dced binding handle for the Host Data
service on a specific host.
entry_uuid Specifies the hostdata entry UUID to associate with the
data to be written.
data Specifies the data to write. The dced_attr_list_t
consists of a count of the number of attributes and an
array of attributes of type sec_attr_t. The reference
implementation has one attribute for a hostdata item
(file contents). Some vendors may require multiple
attributes.
Output
status Returns the status code from this routine. This status
code indicates whether the routine completed
successfully or, if not, why not. The possible status
codes are:
error_status_ok
db_s_bad_index_type
db_s_key_not_found
dced_s_bad_binding
dced_s_cant_open_storage_file
dced_s_no_postprocessors
dced_s_postprocessor_file_fail
dced_s_postprocessor_spawn_fail
dced_s_unknown_attr_type
sec_acl_invalid_permission
uuid_s_bad_version
Usage
The dced_hostdata_write routine replaces existing data for a hostdata
item maintained by dced on a specific host. If the entry_uuid is not
one maintained be dced, an error is returned and a new entry is not
created. Use dced_hostdata_create to create a new entry.
Prior to calling the dced_hostdata_write routine, the application
must have established a valid dced binding handle to the hostdata
service by calling either the dced_binding_create or
dced_binding_from_rpc_binding routine.
Related Information
Routines:
dced_hostdata_read
dced_hostdata_create
dced_binding_create
dced_binding_from_rpc_binding
Books:
DCE for OS/2 Warp: Application Development Guide - Core Components
ΓòÉΓòÉΓòÉ 3.11.23. dced_initialize_cursor ΓòÉΓòÉΓòÉ
Purpose
Sets a cursor to the start of a cached list of data entries for a
dced service.
Format
#include <dce\dced.h>
void dced_initialize_cursor(
dced_binding_handle_t dced_bh,
dced_cursor_t *cursor,
error_status_t *status);
Parameters
Input
dced_bh Specifies the dced binding handle for a dced service on
a specific host.
Output
cursor Returns the cursor used to traverse the list of data
entries, one at a time. The cursor is an opaque data
structure that is used to keep track of the entries
between invocations of the dced_entry_get_next routine.
status Returns the status code from this routine. This status
code indicates whether the routine completed
successfully or, if not, why not. The possible status
codes are:
error_status_ok
db_s_bad_index_type
db_s_iter_not_allowed
db_s_key_not_found
dced_s_bad_binding
dced_s_no_memory
dced_s_no_support
sec_acl_invalid_permission
Usage
The dced_initialize_cursor routine sets a cursor at the start of a
DCE host service's list of data entries. The cursor is then used in
subsequent calls to dced_entry_get_next to obtain individual data
entries. When the application finishes traversing the entry list, it
should call dced_release_cursor to free the resources allocated for
the cursor.
The valid services for this routine that have entry lists include
hostdata, srvrconf, srvrexec, and keytab.
If a service's entry list is small, it may be more efficient to
obtain the entire list using the dced_list_get routine rather than
using cursor routines. This is because dced_list_get guarantees the
list is obtained with one remote procedure call. However, your
application is scalable if you use the cursor routines, because if an
entry list is very large, it may be more efficient (or even
necessary) to obtain the list in chunks with more than one remote
procedure call.
Prior to calling the dced_initialize_cursor routine, the application
must have established a valid dced binding handle by calling either
the dced_binding_create or dced_binding_from_rpc_binding routine.
Related Information
Routines:
dced_entry_get_next
dced_release_cursor
dced_list_get
dced_binding_create
dced_binding_from_rpc_binding
Books:
DCE for OS/2 Warp: Application Development Guide - Core Components
ΓòÉΓòÉΓòÉ 3.11.24. dced_inq_id ΓòÉΓòÉΓòÉ
Purpose
Obtains the entry UUID that dced associates with a name.
Format
#include <dce\dced.h>
void dced_inq_id(
dced_binding_handle_t dced_bh,
dced_string_t name,
uuid_t *uuid,
error_status_t *status);
Parameters
Input
dced_bh Specifies the dced binding handle for a dced service on
a specific host.
name Specifies the name for which to obtain the UUID.
Output
uuid Returns the UUID associated with the name input.
status Returns the status code from this routine. This status
code indicates whether the routine completed
successfully or, if not, why not. The possible status
codes are:
error_status_ok
db_s_bad_index_type
db_s_iter_not_allowed
db_s_key_not_found
dced_s_not_found
sec_acl_invalid_permission
Usage
The dced_inq_id routine obtains the UUID associated with a name in a
service of a specific host's dced. Applications and administrators
use strings maintained by dced to identify data, but dced and its API
must associate each data entry with a UUID. This routine is valid for
the hostdata, srvrconf, srvrexec, and keytab services.
Prior to calling this routine, the application must have established
a valid dced binding handle by calling either the dced_binding_create
or dced_binding_from_rpc_binding routine.
Examples
The following example establishes a dced binding to a host's server
configuration service. The example then obtains the UUID of some
known server to read the server's configuration data.
dced_binding_handle_t dced_bh;
server_t conf;
dced_string_t server_name;
uuid_t srvrconf_id;
error_status_t status;
dced_binding_create("srvrconf@hosts/patrick",
dced_c_binding_syntax_default,
&dced_bh, &status);
dced_inq_id(dced_bh, server_name, &srvrconf_id, &status);
dced_object_read(dced_bh, &srvrconf_id, (void**)&(conf), &status);
.
.
.
Related Information
Routines:
dced_inq_name
dced_binding_create
dced_binding_from_rpc_binding
Books:
DCE for OS/2 Warp: Application Development Guide - Core Components
ΓòÉΓòÉΓòÉ 3.11.25. dced_inq_name ΓòÉΓòÉΓòÉ
Purpose
Obtains the entry name that dced associates with a UUID.
Format
#include <dce\dced.h>
void dced_inq_name(
dced_binding_handle_t dced_bh,
uuid_t *uuid,
dced_string_t *name,
error_status_t *status);
Parameters
Input
dced_bh Specifies the dced binding handle for a dced service on
a specific host.
uuid Specifies the UUID for which to obtain the name.
Output
name Returns the name associated with the uuid input.
status Returns the status code from this routine. This status
code indicates whether the routine completed
successfully or, if not, why not. The possible status
codes are:
error_status_ok
db_s_bad_index_type
db_s_iter_not_allowed
db_s_key_not_found
dced_s_not_found
sec_acl_invalid_permission
uuid_s_bad_version
Usage
The dced_inq_name routine obtains the name associated with a UUID in
a service of a specific host's dced.
A name is a label for each data entry to help applications and
administrators identify all data maintained by dced. The dced
requires UUIDs to keep track of the data it maintains. But it also
maintains a mapping of UUIDs to names so that other applications and
administrators can more easily access the data by using a
recognizable name rather than a cumbersome UUID. A name is a label
for hostdata items, srvrconf and srvrexec servers, and keytab tables.
Prior to calling this routine, the application must have established
a valid dced binding handle by calling either the dced_binding_create
or dced_binding_from_rpc_binding routine.
Examples
The following example establishes a dced binding handle to the local
host data service, reads an entry, and uses dced_inq_name to get the
name associated with the attribute ID.
dced_binding_handle_t dced_bh;
uuid_t entry_uuid;
sec_attr_t *data_ptr;
error_status_t status;
.
.
.
dced_binding_create(dced_c_service_hostdata,
dced_c_binding_syntax_default,
&dced_bh, &status);
dced_hostdata_read(dced_bh, &entry_uuid,
&dced_g_uuid_fileattr,
&data_ptr, &status);
dced_inq_name(dced_bh, data_ptr->sec_attr.attr_id, &name, &status);
.
.
.
Related Information
Routines:
dced_inq_id
dced_binding_create
dced_binding_from_rpc_binding
Books:
DCE for OS/2 Warp: Application Development Guide - Core Components
ΓòÉΓòÉΓòÉ 3.11.26. dced_keytab_add_key ΓòÉΓòÉΓòÉ
Purpose
Adds a key (server password) to a specified key table on a specific
host.
Format
#include <dce\dced.h>
void dced_keytab_add_key(
dced_binding_handle_t dced_bh,
uuid_t *keytab_uuid,
dced_key_t *key,
error_status_t *status);
Parameters
Input
dced_bh Specifies the dced binding handle for the keytab
service on a specific host.
keytab_uuid Specifies the UUID that dced uses to identify the key
table to which the key is to be added.
Input/Output
key Specifies the key to be added.
Output
status Returns the status code from this routine. This status
code indicates whether the routine completed
successfully or, if not, why not. The possible status
codes are:
error_status_ok
db_s_bad_index_type
db_s_key_not_found
dced_s_bad_binding
dced_s_key_v0_not_allowed
dced_s_key_version_mismatch
dced_s_need_privacy
dced_s_random_key_not_allowed
rpc_s_binding_has_no_auth
rpc_s_invalid_binding
rpc_s_wrong_kind_of_binding
sec_acl_invalid_permission
sec_key_mgmt_e_authn_invalid
sec_key_mgmt_e_key_unavailable
sec_key_mgmt_e_key_unsupported
sec_key_mgmt_e_key_version_exists
sec_key_mgmt_e_unauthorized
Usage
The dced_keytab_add_key routine adds a key to a server key table
(file) on a specific host, without changing the key in the security
registry. (Servers use sec_key_mgmt_set_key to do this for their own
local key table.)
Most management applications use the dced_keytab_change_key routine
to remotely change a key, because it also changes the key in the
Security Registry.
Managing the same key in multiple key tables is a more complex
process. The Security Registry needs a copy of the server's key so
that during the authentication process, it can encrypt tickets that
only a server with that key can later decrypt. Part of updating a
key in the Security Registry also includes automatic version number
updating. When servers share the same principal identity, they use
the same key. If these servers are on different hosts, the key must
be in more than one key table. (Even if the servers are on the same
host, it is possible for their keys to be in different key tables,
although this is not a recommended key management practice.) When
the same keys in different tables need changing, one (perhaps the
master server or the busiest one) is changed using
dced_keytab_change_key, which also causes an automatic version
update. However, all other copies of the key must be changed using
the dced_keytab_add_key routine so that the version number does not
change again.
Prior to calling dced_keytab_add_key, the application must have
established a valid dced binding handle to the keytab service by
calling either the dced_binding_create or
dced_binding_from_rpc_binding routine.
Related Information
Routines:
dced_keytab_change_key
sec_key_mgmt_set_key
dced_binding_create
dced_binding_from_rpc_binding
Books:
DCE for OS/2 Warp: Application Development Guide - Core Components
ΓòÉΓòÉΓòÉ 3.11.27. dced_keytab_change_key ΓòÉΓòÉΓòÉ
Purpose
Changes a key (server password) in both a key table and the security
registry.
Format
#include <dce\dced.h>
void dced_keytab_change_key(
dced_binding_handle_t dced_bh,
uuid_t *keytab_uuid,
dced_key_t *key,
error_status_t *status);
Parameters
Input
dced_bh Specifies the dced binding handle for the keytab
service on a specific host.
keytab_uuid Specifies the UUID that dced uses to identify the key
table where the key is to be changed.
Input/Output
key Specifies the new key. Some fields are modified by
dced.
Output
status Returns the status code from this routine. This status
code indicates whether the routine completed
successfully or, if not, why not. The possible status
codes are:
error_status_ok
db_s_bad_index_type
db_s_key_not_found
dced_s_bad_binding
dced_s_key_version_mismatch
dced_s_need_privacy
rpc_s_binding_has_no_auth
rpc_s_invalid_binding
rpc_s_wrong_kind_of_binding
sec_acl_invalid_permission
sec_key_mgmt_e_authn_invalid
sec_key_mgmt_e_authn_unavailable
sec_key_mgmt_e_key_unavailable
sec_key_mgmt_e_key_unsupported
sec_key_mgmt_e_key_version_exists
sec_key_mgmt_e_not_implemented
sec_key_mgmt_e_unauthorized
sec_rgy_object_not_found
sec_rgy_server_unavailable
Usage
The dced_keytab_change_key routine updates a key in both the key
table on a specific host and in the Security Registry. Management
applications change keys remotely with this routine. (Servers can
change their own keys locally with the sec_key_mgmt_change_key
routine.)
The Security Registry needs a copy of the server's current key so
that during the authentication process, it can encrypt tickets that
only a server with that key can later decrypt. When a management
application calls dced_keytab_change_key, dced first tries to make
the modification in the Security Registry, and, if successful, it
then modifies the key in the key table. The old key is not really
replaced, but a new version and key are established for all new
authenticated communication. The old version is maintained in the
key table (and Registry too) for a time so that existing clients with
valid tickets can still communicate with the server. The old key is
removed, depending on the local cell's change policy and if the
server calls sec_key_mgmt_garbage_collect to purge its old keys
explicitly, or sec_key_mgmt_manage_key to purge them implicitly.
When more than one server shares the same principal identity, they
use the same key. If you need to change the same key in more than
one key table, use decd_keytab_change_key for one change and then use
the dced_keytab_add_key routine for all others.
Related Information
Routines:
dced_keytab_add_key
sec_key_mgmt_change_key
dced_binding_create
dced_binding_from_rpc_binding
Books:
DCE for OS/2 Warp: Application Development Guide - Core Components
ΓòÉΓòÉΓòÉ 3.11.28. dced_keytab_create ΓòÉΓòÉΓòÉ
Purpose
Creates a key table with a list of keys (server passwords) in a new
file on a specific host.
Format
#include <dce\dced.h>
void dced_keytab_create(
dced_binding_handle_t dced_bh,
dced_entry_t *keytab_entry,
dced_key_list_t *keys,
error_status_t *status);
Parameters
Input
dced_bh Specifies the dced binding handle for the keytab
service on a specific host.
Input/Output
keytab_entry Specifies the keytab entry to create for dced.
keys Specifies the list of keys to be written to the key
table file.
Output
status Returns the status code from this routine. This status
code indicates whether the routine completed
successfully or, if not, why not. The possible status
codes are:
error_status_ok
db_s_bad_header_type
db_s_bad_index_type
db_s_iter_not_allowed
db_s_key_not_found
db_s_readonly
db_s_store_failed
dced_s_already_exists
dced_s_bad_binding
dced_s_import_already_exists
dced_s_need_privacy
rpc_s_binding_has_no_auth
rpc_s_invalid_binding
rpc_s_wrong_kind_of_binding
sec_acl_invalid_permission
sec_key_mgmt_e_authn_invalid
sec_key_mgmt_e_key_unavailable
sec_key_mgmt_e_key_unsupported
sec_key_mgmt_e_key_version_exists
sec_key_mgmt_e_unauthorized
uuid_s_bad_version
Usage
The dced_keytab_create routine creates a new key table file on a
specific host, and it generates the associated keytab service entry
in dced. This routine is used by management applications to remotely
create a key table. Servers typically create their own key table
locally using the sec_key_mgmt_set_key routine. However, if several
servers on different hosts share the same principal, each host
requires a local copy of the key table.
If a key table that you want to add to the keytab service already
exists on the host, you can add it to the service by calling
dced_entry_add. This routine creates a new keytab service entry by
associating the existing key table file with a new UUID in dced.
Prior to calling the dced_keytab_create routine, the application must
have established a valid dced binding handle to the keytab service by
calling either the dced_binding_create or
dced_binding_from_rpc_binding routine.
Related Information
Routines:
sec_key_mgmt_set_key
dced_entry_add
dced_binding_create
dced_binding_from_rpc_binding
Books:
DCE for OS/2 Warp: Application Development Guide - Core Components
ΓòÉΓòÉΓòÉ 3.11.29. dced_keytab_delete ΓòÉΓòÉΓòÉ
Purpose
Deletes a key table file from a specific host.
Format
#include <dce\dced.h>
void dced_keytab_delete(
dced_binding_handle_t dced_bh,
uuid_t *keytab_uuid,
error_status_t *status);
Parameters
Input
dced_bh Specifies the dced binding handle for the keytab
service on a specific host.
keytab_uuid Specifies the UUID of the keytab entry and associated
key table to be deleted.
Output
status Returns the status code from this routine. This status
code indicates whether the routine completed
successfully or, if not, why not. The possible status
codes are:
error_status_ok
db_s_bad_index_type
db_s_del_failed
db_s_iter_not_allowed
db_s_key_not_found
dced_s_bad_binding
dced_s_cant_remove_storage_file
dced_s_need_privacy
rpc_s_binding_has_no_auth
rpc_s_invalid_binding
rpc_s_wrong_kind_of_binding
sec_acl_invalid_permission
Usage
The dced_keytab_delete routine deletes a key table (file) from a
specific host and removes the associated entry from the keytab
service of the host's dced. A key table is a file containing a list
of server keys (passwords). This routine is used by management
applications to remotely delete a key table.
To remove individual keys from a remote key table, use the
dced_keytab_remove_key routine. If you want to only make the key
table inaccessible remotely (with dced) but not delete it, use the
dced_entry_remove routine. This routine only removes the key table's
keytab entry from dced.
Prior to calling the dced_keytab_delete routine, the application must
have established a valid dced binding handle to the keytab service by
calling either the dced_binding_create or
dced_binding_from_rpc_binding routine.
Related Information
Routines:
dced_keytab_remove_key
dced_entry_remove
dced_binding_create
dced_binding_from_rpc_binding
Books:
DCE for OS/2 Warp: Application Development Guide - Core Components
ΓòÉΓòÉΓòÉ 3.11.30. dced_keytab_get_next_key ΓòÉΓòÉΓòÉ
Purpose
Returns a key from a cached list, and advances the cursor in the
list.
Format
#include <dce\dced.h>
void dced_keytab_get_next_key(
dced_keytab_cursor_t cursor,
dced_key_t **key,
error_status_t *status);
Parameters
Input/Output
cursor Specifies the cursor that points to a key and returns
the cursor advanced to the next key in the list.
Output
key Returns the current key to which cursor points.
status Returns the status code from this routine. This status
code indicates whether the routine completed
successfully or, if not, why not. The possible status
codes are:
error_status_ok
dced_s_no_more_entries
Usage
The dced_keytab_get_next_key routine obtains the current key to which
the key-list cursor points. This routine is commonly used in a loop
to traverse a key table's keys. The keys are returned in an
undetermined order. Prior to using this routine in the loop, the
application must call dced_keytab_initialize_cursor to obtain the key
list and establish the beginning of the cursor. When the application
finishes traversing the key list, it should call
dced_keytab_release_cursor to release the resources allocated.
Management applications use dced_keytab_get_next_key to remotely
access the server's individual keys. Servers use
sec_key_mgmt_get_next_key to access their own local keys
individually.
You can also use the dced_object_read routine to read an entire key
table. You can use dced_object_read if your application needs to bind
to and read data for other host services (srvrconf, srvrexec, or
hostdata) in addition to data for the keytab service.
Related Information
Routines:
dced_keytab_initialize_cursor
dced_keytab_release_cursor
sec_key_mgmt_get_next_key
dced_object_read
Books:
DCE for OS/2 Warp: Application Development Guide - Core Components
ΓòÉΓòÉΓòÉ 3.11.31. dced_keytab_initialize_cursor ΓòÉΓòÉΓòÉ
Purpose
Obtains a list of keys from a key table and sets a cursor at the
beginning of the list.
Format
#include <dce\dced.h>
void dced_keytab_initialize_cursor(
dced_binding_handle_t dced_bh,
uuid_t *keytab_uuid,
dced_keytab_cursor_t *cursor,
error_status_t *status);
Parameters
Input
dced_bh Specifies the dced binding handle for the keytab
service on a specific host.
keytab_uuid Specifies the keytab entry dced associates with a key
table.
Output
cursor Returns the cursor that is used to traverse the list of
keys.
status Returns the status code from this routine. This status
code indicates whether the routine completed
successfully or, if not, why not. The possible status
codes are:
error_status_ok
dced_s_bad_binding
dced_s_need_privacy
dced_s_no_memory
dced_s_no_support
sec_acl_invalid_permission
sec_key_mgmt_e_authn_invalid
sec_key_mgmt_e_unauthorized
Usage
The dced_keytab_initialize_cursor routine obtains the complete list
of keys from a remote key table and sets a cursor at the beginning of
the cached list keys. In order to minimize the security risks of keys
exposed to the network, the entire set of keys is encrypted and
transferred in one remote procedure call rather than individually or
in chunks. The cursor is then used in subsequent calls to
dced_keytab_get_next_key to obtain individual keys. When the
application finishes traversing the key list, it should call
dced_keytab_release_cursor to release the resources previously
allocated.
Management applications use dced_keytab_initialize_cursor and its
associated routines to remotely access server keys. Servers use
sec_key_mgmt_initialize_cursor and its associated routines to manage
their own keys locally.
Prior to calling the dced_keytab_initialize_cursor routine, the
application must have established a valid dced binding handle to the
keytab service by calling either the dced_binding_create or
dced_binding_from_rpc_binding routine.
Related Information
Routines:
dced_keytab_get_next_key
dced_keytab_release_cursor
sec_key_mgmt_initialize_cursor
dced_binding_create
dced_binding_from_rpc_binding
Books:
DCE for OS/2 Warp: Application Development Guide - Core Components
ΓòÉΓòÉΓòÉ 3.11.32. dced_keytab_release_cursor ΓòÉΓòÉΓòÉ
Purpose
Releases the resources of a cursor that traverses a key table's list
of keys (server passwords).
Format
#include <dce\dced.h>
void dced_keytab_release_cursor(
dced_keytab_cursor_t *cursor,
error_status_t *status);
Parameters
Input/Output
cursor Specifies the cursor for which resources are released.
Output
status Returns the status code from this routine. This status
code indicates whether the routine completed
successfully or, if not, why not. The possible status
codes are:
error_status_ok
dced_s_bad_binding
dced_s_no_support
Usage
The dced_keytab_release_cursor routine releases the cursor and
resources initially set by the dced_keytab_initialize_cursor routine
and used by the dced_keytab_get_next_key routine.
Prior to calling this routine, the application must have first
established a valid dced binding handle by calling either
dced_binding_create or dced_binding_from_rpc_binding, and then the
application must have called the dced_keytab_initialize_cursor
routine.
Related Information
Routines:
dced_keytab_initialize_cursor
dced_keytab_get_next_key
Books:
DCE for OS/2 Warp: Application Development Guide - Core Components
ΓòÉΓòÉΓòÉ 3.11.33. dced_keytab_remove_key ΓòÉΓòÉΓòÉ
Purpose
Removes a key (server password) from a specified key table on a
specific host.
Format
#include <dce\dced.h>
void dced_keytab_remove_key(
dced_binding_handle_t dced_bh,
uuid_t *keytab_uuid,
dced_key_t *key,
error_status_t *status);
Parameters
Input
dced_bh Specifies the dced binding handle for the keytab
service on a specific host.
keytab_uuid Specifies the UUID dced maintains to identify the key
table from which the key is to be removed.
key Specifies the key to be removed from the key table.
Output
status Returns the status code from this routine. This status
code indicates whether the routine completed
successfully or, if not, why not. The possible status
codes are:
error_status_ok
db_s_bad_index_type
db_s_key_not_found
dced_s_bad_binding
dced_s_need_privacy
rpc_s_binding_has_no_auth
rpc_s_invalid_binding
rpc_s_wrong_kind_of_binding
sec_acl_invalid_permission
sec_key_mgmt_e_authn_invalid
sec_key_mgmt_e_key_unavailable
sec_key_mgmt_e_unauthorized
Usage
The dced_keytab_remove_key routine removes a key from a key table
(file) on a specific host. The key table is specified with a keytab
entry UUID from the host's dced. Management applications use
dced_keytab_remove_key to remotely remove server keys from key
tables. Typically, servers delete their own keys from their local
key tables implicitly by calling sec_key_mgmt_manage_key, or
explicitly by calling sec_key_mgmt_delete_key. Applications can
delete an entire key table file using the dced_keytab_delete routine.
Prior to calling this routine, the application must have established
a valid dced binding handle to the keytab service by calling either
the dced_binding_create or dced_binding_from_rpc_binding routine.
Related Information
Routines:
sec_key_mgmt_delete_key_type
dced_keytab_delete
dced_binding_create
dced_binding_from_rpc_binding
Books:
DCE for OS/2 Warp: Application Development Guide - Core Components
ΓòÉΓòÉΓòÉ 3.11.34. dced_list_get ΓòÉΓòÉΓòÉ
Purpose
Returns the list of data entries maintained by a dced service on a
specific host.
Format
#include <dce\dced.h>
void dced_list_get(
dced_binding_handle_t dced_bh,
dced_entry_list_t *list,
error_status_t *status);
Parameters
Input
dced_bh Specifies the dced binding handle for a dced service on
a specific host.
Output
list Returns a list of data entries for the service.
status Returns the status code from this routine. This status
code indicates whether the routine completed
successfully or, if not, why not. The possible status
codes are:
error_status_ok
dced_s_bad_binding
dced_s_no_memory
dced_s_no_support
sec_acl_invalid_permission
Usage
The dced_list_get routine obtains all the data entries for a dced
service on a specific host. The list of data entries obtained is not
the actual data. Each entry contains a UUID, name, description, and
storage tag that describes where the data is located (for example, a
file name or memory location). Call the dced_list_release routine
when your application finishes with the entry list to release
resources allocated with dced_list_get routine.
If a service's entry list is small, it may be efficient to obtain the
entire list using the dced_list_get routine because it guarantees
that the list is obtained with one remote procedure call. However, to
make your application scalable, use the dced_initialize_cursor,
dced_entry_get_next, and dced_release_cursor set of routines, because
if an entry list is very large, it may be more efficient (or even
necessary) to obtain the list in chunks with more than one remote
procedure call.
Prior to calling this routine, the application must have established
a valid dced binding handle by calling either the dced_binding_create
or dced_binding_from_rpc_binding routine.
Examples
In the following example, a dced binding is obtained from a service
type and an existing RPC binding handle. The list of entries for the
service is obtained with the dced_list_get routine and each entry's
name and description are displayed.
dced_binding_from_rpc_binding(service_type, rpc_bh, &dced_bh, &status);
dced_list_get(dced_bh, &entries, &status);
for(i=0; i<entries.count; i++)
display(&entries); /* application specific */
dced_list_release(dced_bh, &entries, &status);
dced_binding_free( dced_bh, &status);
Related Information
Routines:
dced_list_release
dced_initialize_cursor
dced_binding_create
dced_binding_from_rpc_binding
Books:
DCE for OS/2 Warp: Application Development Guide - Core Components
ΓòÉΓòÉΓòÉ 3.11.35. dced_list_release ΓòÉΓòÉΓòÉ
Purpose
Releases the resources for a list of entries of a dced service.
Format
#include <dce\dced.h>
void dced_list_release(
dced_binding_handle_t dced_bh,
dced_entry_list_t *list,
error_status_t *status);
Parameters
Input
dced_bh Specifies the dced binding handle for a dced service on
a specific host.
Input/Output
list Specifies a list of data entries for the service.
Output
status Returns the status code from this routine. This status
code indicates whether the routine completed
successfully or, if not, why not. The only possible
status code is error_status_ok.
Usage
The dced_list_release routine releases the resources allocated for a
list of data entries previously retrieved by the dced_list_get
routine.
Prior to calling this routine, the application must have first
established a valid dced binding handle by calling either the
dced_binding_create or dced_binding_from_rpc_binding routine, and
then the application must have called the dced_list_get routine.
Related Information
Routines:
dced_list_get
dced_binding_create
dced_binding_from_rpc_binding
Books:
DCE for OS/2 Warp: Application Development Guide - Core Components
ΓòÉΓòÉΓòÉ 3.11.36. dced_object_read ΓòÉΓòÉΓòÉ
Purpose
Reads a data item of a dced service on a specific host.
Format
#include <dce\dced.h>
void dced_object_read(
dced_binding_handle_t dced_bh,
uuid_t *entry_uuid,
void **data,
error_status_t *status);
Parameters
Input
dced_bh Specifies the dced binding handle for a dced service on
a specific host.
entry_uuid Specifies the UUID of the dced service's data entry
associated with the data item.
Output
data Returns the data read. The data returned is one of the
following structures, depending on the service:
Service Data Type Returned
hostdata sec_attr_t
srvrconf server_t
srvrexec server_t
keytab dced_key_list_t
status Returns the status code from this routine. This status
code indicates whether the routine completed
successfully or, if not, why not. The possible status
codes are:
error_status_ok
db_s_bad_index_type
db_s_key_not_found
dce_cf_e_file_open
dce_cf_e_no_match
dce_cf_e_no_mem
dced_s_bad_binding
dced_s_need_privacy
dced_s_no_memory
dced_s_no_support
dced_s_not_found
rpc_s_binding_has_no_auth
rpc_s_invalid_binding
rpc_s_wrong_kind_of_binding
sec_acl_invalid_permission
sec_key_mgmt_e_authn_invalid
sec_key_mgmt_e_key_unavailable
sec_key_mgmt_e_unauthorized
uuid_s_bad_version
Usage
The dced_object_read routine reads the data for a specified entry of
a dced service. When the application finishes with the data, it
should call the dced_objects_release routine with a value of 1 for
the count parameter.
The valid services for which you can read data include hostdata,
srvrconf, srvrexec, and keytab. Each of these host services has a
list of data entries maintained by dced. The entries do not contain
the actual data, but contain the data's identity and an indicator of
the location of the data item. The hostdata service also has the
dced_hostdata_read routine to read data, and the keytab service has a
series of routines that traverse over the keys in a key table. (See
the dced_keytab_initialize_cursor routine.) The secval and endpoint
services do not have data items to read with this routine.
Applications can also read the data for all entries of a service
using one call to dced_objects_read_all.
Before reading the actual data, an application commonly obtains the
entries to read using the series of cursor routines that begin with
dced_entry_initialize_cursor.
Before calling the dced_object_read routine, the application must
have established a valid dced binding handle by calling either the
dced_binding_create or dced_binding_from_rpc_binding routine.
Examples
The following example creates a dced binding to a dced service based
on a service type and host in an RPC binding handle. The example then
obtains the service's entry list and reads the data associated with
each entry.
dced_binding_from_rpc_binding(service_type, rpc_bh, &dced_bh, &status);
dced_list_get(dced_bh, &entries, &status);
for(i=0; i<entries.count; i++) {
dced_object_read(dced_bh, &entries.list[i.]id, &data, &status);
.
.
.
dced_objects_release(dced_bh, 1, data, &status);
}
Related Information
Routines:
dced_objects_release
dced_object_read_all
dced_hostdata_read
dced_keytab_initialize_cursor
dced_initialize_cursor
dced_binding_create
dced_binding_from_rpc_binding
Books:
DCE for OS/2 Warp: Application Development Guide - Core Components
ΓòÉΓòÉΓòÉ 3.11.37. dced_object_read_all ΓòÉΓòÉΓòÉ
Purpose
Reads all the data for a service of the DCE Host daemon (dced) on a
specific host.
Format
#include <dce\dced.h>
void dced_object_read_all(
dced_binding_handle_t dced_bh,
unsigned32 *count,
void **data_list,
error_status_t *status);
Parameters
Input
dced_bh Specifies the dced binding handle for a dced service on
a specific host.
Output
count Returns the count of the number of data items read.
data_list Returns the list of data items read. The data returned
is an array of one of the following types, depending on
the service:
Service Data Type of Array Returned
hostdata sec_attr_t
srvrconf server_t
srvrexec server_t
keytab dced_key_list_t
status Returns the status code from this routine. This status
code indicates whether the routine completed
successfully or, if not, why not. The possible status
codes are:
error_status_ok
db_s_bad_index_type
db_s_key_not_found
dce_cf_e_file_open
dce_cf_e_no_match
dce_cf_e_no_mem
dced_s_bad_binding
dced_s_need_privacy
dced_s_no_memory
dced_s_no_support
dced_s_not_found
rpc_s_binding_has_no_auth
rpc_s_invalid_binding
rpc_s_wrong_kind_of_binding
sec_acl_invalid_permission
sec_key_mgmt_e_authn_invalid
sec_key_mgmt_e_key_unavailable
sec_key_mgmt_e_unauthorized
sec_s_no_memory
uuid_s_bad_version
Usage
The dced_object_read_all routine reads all the data for a specified
host service on a specific host. When the application finishes with
the data, it should call the dced_objects_release routine.
Applications can also read individual data objects for a service
using the dced_object_read routine.
The valid services for which you can read data include hostdata,
srvrconf, srvrexec, and keytab.
Prior to calling the dced_object_read_all routine, the application
must have established a valid dced binding handle by calling either
the dced_binding_create or dced_binding_from_rpc_binding routine.
Examples
The following example reads and displays all the data for a
particular dced service.
dced_binding_handle_t dced_bh;
dced_string_t host_service;
void *data_list;
unsigned32 count;
error_status_t status;
dced_binding_create(host_service, dced_c_binding_syntax_default, &dced_bh, &status);
dced_object_read_all(dced_bh, &count, &data_list, &status);
display(host_service, count, &data_list); /* application specific */
dced_objects_release(dced_bh, count, data_list, &status);
dced_binding_free(dced_bh, &status);
Related Information
Routines:
dced_objects_release
dced_object_read
dced_binding_create
dced_binding_from_rpc_binding
Books:
DCE for OS/2 Warp: Application Development Guide - Core Components
ΓòÉΓòÉΓòÉ 3.11.38. dced_objects_release ΓòÉΓòÉΓòÉ
Purpose
Releases the resources allocated for data read from a dced service.
Format
#include <dce\dced.h>
void dced_objects_release(
dced_binding_handle_t dced_bh,
unsigned32 count,
void *data,
error_status_t *status);
Parameters
Input
dced_bh Specifies the dced binding handle for a dced service on
a specific host.
count Specifies the number of data items previously read and
now to be released.
Input/Output
data Specifies the data for which resources are released.
Output
status Returns the status code from this routine. This status
code indicates whether the routine completed
successfully or, if not, why not. The possible status
codes are:
error_status_ok
dced_s_bad_binding
dced_s_no_support
Usage
The dced_objects_release routine releases the resources allocated
when data for dced is read. Applications should call
dced_objects_release when finished with data allocated by the
following dced API routines:
dced_object_read_all
dced_object_read
dced_hostdata_read
If the data being released was read by using dced_object_read_all,
the count returned from this routine is used as input to the
dced_objects_release routine. If the data being released was read by
using dced_object_read or dced_hostdata_read, the count value
required as input for the dced_objects_release routine is 1.
Examples
In the following example, a binding is created to a dced service on
some host for a service that stores data, and the service's entry
list is obtained. For each entry, the data is read, displayed, and
released.
dced_binding_handle_t dced_bh;
dced_entry_list_t entries;
unsigned32 i;
void *data;
error_status_t status;
dced_binding_create(host_service, dced_c_binding_syntax_default, &dced_bh, &status);
dced_list_get(dced_bh, &entries, &status);
for(i=0; i<entries.count; i++) {
dced_object_read(dced_bh, &(entries.list[i].id), &data, &status);
display(host_service, 1, &data); /* application specific */
dced_objects_release(dced_bh, 1, data, &status);
.
.
.
Related Information
Routines:
dced_object_read
dced_object_read_all
dced_hostdata_read
dced_binding_create
dced_binding_from_rpc_binding
Books:
DCE for OS/2 Warp: Application Development Guide - Core Components
ΓòÉΓòÉΓòÉ 3.11.39. dced_release_cursor ΓòÉΓòÉΓòÉ
Purpose
Releases the resources of a cursor that traverses a dced service's
list of entries.
Format
#include <dce\dced.h>
void dced_release_cursor(
dced_cursor_t *cursor,
error_status_t *status);
Parameters
Input/Output
cursor Specifies the cursor for which resources are released.
Output
status Returns the status code from this routine. This status
code indicates whether the routine completed
successfully or, if not, why not. The only possible
status code is error_status_ok.
Usage
The dced_release_cursor routine releases the resources of a cursor
initially set by the dced_initilalize_cursor routine and used by the
dced_entry_get_next routine.
Prior to calling this routine, the application must have first
established a valid dced binding handle by calling either the
dced_binding_create or dced_binding_from_rpc_binding routine, and
then the application must have called the dced_initialize_cursor
routine.
Related Information
Routines:
dced_initialize_cursor
dced_entry_get_next
dced_binding_create
dced_binding_from_rpc_binding
Books:
DCE for OS/2 Warp: Application Development Guide - Core Components
ΓòÉΓòÉΓòÉ 3.11.40. dced_secval_start ΓòÉΓòÉΓòÉ
Purpose
Starts the security validation (secval) service of a specific host's
dced.
Format
#include <dce\dced.h>
void dced_secval_start(
dced_binding_handle_t dced_bh,
error_status_t *status);
Parameters
Input
dced_bh Specifies the dced binding handle for the secval
service on a specific host.
Output
status Returns the status code from this routine. This status
code indicates whether the routine completed
successfully or, if not, why not. The possible status
codes are:
error_status_ok
dced_s_bad_binding
dced_s_sv_already_enabled
sec_acl_invalid_permission
Usage
The dced_secval_start routine starts the Security Validation service
of a specific host's dced. This routine is typically used by
management applications.
The Security Validation service (secval) has two major functions:
o Maintains a login context for the host's self identity.
o Validates and certifies to applications (usually login programs)
that the DCE Security daemon (secd) is legitimate.
The secval is commonly started by default when dced starts. See the
dced_secval_stop routine for a discussion of when to use the
combination of dced_secval_stop and dced_secval_start.
Prior to calling this routine, the application must have established
a valid dced binding handle to the secval service by calling either
the dced_binding_create or dced_binding_from_rpc_binding routine.
Related Information
Routines:
dced_secval_stop
dced_binding_create
dced_binding_from_rpc_binding
Commands:
dced - The secval object of dcecp.
Books:
DCE for OS/2 Warp: Application Development Guide - Core Components
ΓòÉΓòÉΓòÉ 3.11.41. dced_secval_status ΓòÉΓòÉΓòÉ
Purpose
Indicates whether a specific host's dced security validation service
is running.
Format
#include <dce\dced.h>
void dced_secval_status(
dced_binding_handle_t dced_bh,
boolean32 *secval_active,
error_status_t *status);
Parameters
Input
dced_bh Specifies the dced binding handle for the secval
service on a specific host.
Output
secval_active Returns a value of TRUE if the security validation
service is running and FALSE if it is not running.
status Returns the status code from this routine. This status
code indicates whether the routine completed
successfully or, if not, why not. The possible status
codes are:
error_status_ok
dced_s_bad_binding
Usage
The dced_secval_status routine sets a parameter to TRUE or FALSE
depending on whether the security validation service has been
activated or deactivated.
Prior to calling this routine, the application must have established
a valid dced binding handle to the secval service by calling either
the dced_binding_create or dced_binding_from_rpc_binding routine.
Related Information
Routines:
dced_secval_start
dced_secval_stop
dced_binding_create
dced_binding_from_rpc_binding
Commands:
dced - The secval object of dcecp.
Books:
DCE for OS/2 Warp: Application Development Guide - Core Components
ΓòÉΓòÉΓòÉ 3.11.42. dced_secval_stop ΓòÉΓòÉΓòÉ
Purpose
Stops the security validation (secval) service of a specific host's
dced.
Format
#include <dce\dced.h>
void dced_secval_stop(
dced_binding_handle_t dced_bh,
error_status_t *status);
Parameters
Input
dced_bh Specifies the dced binding handle for the secval
service on a specific host.
Output
status Returns the status code from this routine. This status
code indicates whether the routine completed
successfully or, if not, why not. The possible status
codes are:
error_status_ok
dced_s_bad_binding
dced_s_sv_not_enabled
sec_acl_invalid_permission
Usage
The dced_secval_stop routine stops the security validation service
(secval) of a specific host's dced. This routine is typically used by
management applications.
The secval service is commonly started by default when dced starts.
The main use of dced_secval_stop and dced_secval_start is to force a
refresh of the host principal credentials. This is the only way to
force certain registry changes made by the host principal (such as
groupset membership) to be seen by processes running on the host.
You can easily stop and then start the secval service with the
following operations:
dcecp -c secval deactivate
dcecp -c secval activate
It is not a good idea to remove the machine principal self
credentials for an extended period of time, because this causes
processes running as self to fail in their attempts to perform
authenticated operations.
Related Information
Routines:
dced_secval_start
dced_binding_create
dced_binding_from_rpc_binding
Commands:
dced - The secval object of dcecp.
Books:
DCE for OS/2 Warp: Application Development Guide - Core Components
ΓòÉΓòÉΓòÉ 3.11.43. dced_secval_validate ΓòÉΓòÉΓòÉ
Purpose
Validates that the secd used by a specific host is legitimate.
Format
#include <dce\dced.h>
void dced_secval_validate(
dced_binding_handle_t dced_bh,
error_status_t *status);
Parameters
Input
dced_bh Specifies the dced binding handle for the secval
service on a specific host.
Output
status Returns the status code from this routine. This status
code indicates whether the routine completed
successfully or, if not, why not. The possible status
codes are:
error_status_ok
dced_s_bad_binding
ept_s_not_registered
rpc_s_comm_failure
rpc_s_invalid_binding
rpc_s_rpcd_comm_failure
rpc_s_wrong_kind_of_binding
sec_login_s_no_current_context
Usage
The dced_secval_validate routine validates and certifies for a
specific host that the DCE Security daemon (secd) is legitimate.
Typically, a login program uses the security validation service when
it uses the Security Service's Login API (routines that begin with
sec_login). However, if a management application trusts some remote
host, it can use dced_secval_validate to validate secd without
logging in to the host.
Related Information
Routines:
DCE Login API
dced_secval_start
dced_binding_create
dced_binding_from_rpc_binding
Commands:
dced - The secval object of dcecp.
Books:
DCE for OS/2 Warp: Application Development Guide - Core Components
ΓòÉΓòÉΓòÉ 3.11.44. dced_server_create ΓòÉΓòÉΓòÉ
Purpose
Creates DCE server configuration data for the host's dced.
Format
#include <dce\dced.h>
void dced_server_create(
dced_binding_handle_t dced_bh,
server_t *conf_data,
error_status_t *status);
Parameters
Input
dced_bh Specifies the dced binding handle for the srvrconf
service on a specific host.
Input/Output
conf_data Specifies the configuration data for the server. The
dced_intro reference page describes the server_t
structure.
Output
status Returns the status code from this routine. This status
code indicates whether the routine completed
successfully or, if not, why not. The possible status
codes are:
error_status_ok
db_s_bad_header_type
db_s_bad_index_type
db_s_iter_not_allowed
db_s_key_not_found
db_s_readonly
db_s_store_failed
dced_s_already_exists
dced_s_bad_binding
dced_s_name_missing
sec_acl_invalid_permission
Usage
The dced_server_create routine creates server configuration data.
This routine is used by management installation applications to
remotely (or locally) establish the data used to control how a DCE
server starts. However, it does not create the program or start it.
Because this activity is typically part of a server's installation,
you can also use the dcecp server create operation.
Management applications use the dced_object_read routine to read the
configuration data.
Prior to calling dced_server_create, the application must have
established a valid dced binding handle to the srvrconf service by
calling either dced_binding_create or dced_binding_from_rpc_binding.
Examples
The following example shows how to fill in some of the fields of a
server_t structure and then create the configuration in dced.
dced_binding_handle_t dced_bh;
server_t conf;
error_status_t status;
dced_binding_create("srvrconf@hosts/katharine",
dced_c_binding_syntax_default,
&dced_bh, &status);
/* setup a server_t structure */
uuid_create(&conf.id, &status);
conf.name = (dced_string_t)"application";
conf.entryname = (dced_string_t)"/.:/development/new_app";
conf.services.count = 1;
/* service_t structure(s) */
conf.services.list = malloc(conf.services.count * sizeof(service_t));
rpc_if_inq_id(application_v1_0_c_ifspec, &(conf.services.list[0].ifspec), &status);
conf.services.list[0].ifname = (dced_string_t)"application";
conf.services.list[0].annotation = (dced_string_t)"A new application";
conf.services.list[0].flags = 0;
/* server_fixedattr_t structure */
conf.fixed.startupflags = server_c_startup_explicit | server_c_startup_on_failure;
conf.fixed.flags = 0;
conf.fixed.program = (dced_string_t)"/usr/users/bin/new_app";
dced_server_create(dced_bh, &conf, &status);
.
.
.
Related Information
Routines:
dced_object_read
dced_binding_create
dced_binding_from_rpc_binding
Commands:
The server object of dcecp
Books:
DCE for OS/2 Warp: Application Development Guide - Core Components
ΓòÉΓòÉΓòÉ 3.11.45. dced_server_delete ΓòÉΓòÉΓòÉ
Purpose
Deletes DCE server configuration data from dced.
Format
#include <dce\dced.h>
void dced_server_delete(
dced_binding_handle_t dced_bh,
uuid_t *conf_uuid,
error_status_t *status);
Parameters
Input
dced_bh Specifies the dced binding handle for the srvrconf
service on a specific host.
conf_uuid Specifies the UUID that dced uses to identify the
server configuration data to delete.
Output
status Returns the status code from this routine. This status
code indicates whether the routine completed
successfully or, if not, why not. The possible status
codes are:
error_status_ok
db_s_bad_index_type
db_s_del_failed
db_s_iter_not_allowed
dced_s_bad_binding
dced_s_not_found
sec_acl_invalid_permission
Usage
The dced_server_delete routine deletes server configuration data from
the server's dced. This routine removes a server from DCE control by
making it incapable of being starting by dced. It does not delete
the program from disk, nor does it affect the server if it is
currently running.
Prior to using dced_server_delete, the server configuration data must
be created by an administrator using the dcecp server create
operation or by an application that is using dced_server_create.
Prior to calling dced_server_delete, the application must have
established a valid dced binding handle to the srvrconf service by
calling either dced_binding_create or dced_binding_from_rpc_binding.
Examples
In the following example, a dced binding is created to the server
configuration service on a host, and then an inquiry is made to
determine UUID associated with a particular server. The
dced_server_delete routine is then used to delete the configuration.
dced_binding_handle_t dced_bh;
dced_string_t server_name;
uuid_t srvrconf_id;
error_status_t status;
name_server(&server_name); /* application specific */
dced_binding_create("srvrconf@hosts/katharine",
dced_c_binding_syntax_default, &dced_bh, &status);
dced_inq_id(dced_bh, server_name, &srvrconf_id, &status);
dced_server_delete(dced_bh, &srvrconf_id, &status);
dced_binding_free(dced_bh, &status);
Related Information
Routines:
dced_server_create
dced_server_modify_attributes
dced_binding_create
dced_binding_from_rpc_binding
Commands:
The server object of dcecp
Books:
DCE for OS/2 Warp: Application Development Guide - Core Components
ΓòÉΓòÉΓòÉ 3.11.46. dced_server_disable_if ΓòÉΓòÉΓòÉ
Purpose
Disables a service (rpc interface) provided by a specific server on a
specific host.
Format
#include <dce\dced.h>
void dced_server_disable_if(
dced_binding_handle_t dced_bh,
uuid_t *exec_uuid,
rpc_if_id_t *interface,
error_status_t *status);
Parameters
Input
dced_bh Specifies the dced binding handle for the srvrexec
service on a specific host.
exec_uuid Specifies the UUID that dced uses to identify the
running server.
interface Specifies the RPC interface identifier that represents
the service to disable. The interface identifier is
generated when idl compiles an interface definition
file. The interface identifier is an rpc_if_id_t
structure that contains the interface UUID (uuid) of
type uuid_t, and numbers of type unsigned16
representing the major (vers_major) and minor
(vers_minor) version numbers for the interface.
Output
status Returns the status code from this routine. This status
code indicates whether the routine completed
successfully or, if not, why not. The possible status
codes are:
error_status_ok
db_s_bad_index_type
db_s_iter_not_allowed
db_s_readonly
db_s_store_failed
dced_s_bad_binding
dced_s_not_found
sec_acl_invalid_permission
Usage
The dced_server_disable_if routine disables a service provided by a
server on a specific host. A service is represented by an RPC
interface identifier. Management applications use this routine to
remotely disable an interface so that it is inaccessible by clients,
without completely stopping the entire server.
When a server starts and initializes itself, it must call the
dce_server_register routine to enable all of its services. The server
can then disable its own individual services by using
dce_server_disable_service. This routine unregisters the service's
interface from the RPC runtime and marks the interface as disabled in
the endpoint map. As an alternative, a management application can
use dced_server_disable_if to disable individual services. However,
this routine affects only the endpoint map in dced by marking the
interface as disabled and does not affect the server's runtime.
A management application can re-enable a service by calling the
dced_server_enable_if routine. (Servers re-enable their own services
using the dce_server_enable_if routine.)
Prior to calling dced_server_disable_if, the application must have
established a valid dced binding handle to the srvrexec service by
calling either dced_binding_create or dced_binding_from_rpc_binding.
Related Information
Routines:
dce_server_register
dced_server_enable_if
dced_binding_create
dced_binding_from_rpc_binding
Commands:
The server object of dcecp
Books:
DCE for OS/2 Warp: Application Development Guide - Core Components
ΓòÉΓòÉΓòÉ 3.11.47. dced_server_enable_if ΓòÉΓòÉΓòÉ
Purpose
Enables a service (rpc interface) of a specific server on a specific
host.
Format
#include <dce\dced.h>
void dced_server_enable_if(
dced_binding_handle_t dced_bh,
uuid_t *exec_uuid,
rpc_if_id_t *interface,
error_status_t *status);
Parameters
Input
dced_bh Specifies the dced binding handle for the srvrexec
service on a specific host.
exec_uuid Specifies the UUID that dced uses to identify the
running server.
interface Specifies the RPC interface identifier that represents
the service to enable. The interface identifier is
generated when idl compiles an interface definition
file. The interface identifier is a structure that
contains the interface UUID (interface->uuid), and the
major (interface->vers_major) and minor
(interface->vers_minor) version numbers for the
interface.
Output
status Returns the status code from this routine. This status
code indicates whether the routine completed
successfully or, if not, why not. The possible status
codes are:
error_status_ok
db_s_bad_index_type
db_s_iter_not_allowed
db_s_readonly
db_s_store_failed
dced_s_bad_binding
dced_s_not_found
sec_acl_invalid_permission
Usage
The dced_server_enable_if routine enables a service (or re-enables a
previously disabled service) that a specific server provides.
Management applications use this routine. A service is represented by
an RPC interface identifier.
When a server starts and initializes itself, it typically calls the
dce_server_register routine to enable all of its services. The
services can then be disabled and re-enabled, as needed. A server
enables and disables its own services by using
dce_server_enable_service and dce_server_disable_service and a
management application enables and disables a remote server's service
using dced_server_enable_if and dced_server_disable_if. The
dce_server_xxx routines affect both the RPC runtime and the local
endpoint map by registering (or unregistering) with the runtime and
setting a flag for the interface in the endpoint map as enabled (or
disabled). The dced_server_enable_if and dced_server_disable_if
routines affect only the remote endpoint map by setting the flag.
Before calling dced_server_enable_if, the application must have
established a valid dced binding handle to the srvrexec service by
calling either dced_binding_create or dced_binding_from_rpc_binding.
Related Information
Routines:
dce_server_register
dced_server_disable_if
dced_binding_create
dced_binding_from_rpc_binding
Commands:
The server object of dcecp
Books:
DCE for OS/2 Warp: Application Development Guide - Core Components
ΓòÉΓòÉΓòÉ 3.11.48. dced_server_modify_attributes ΓòÉΓòÉΓòÉ
Purpose
Modifies attributes for a DCE server's configuration data.
Format
#include <dce\dced.h>
void dced_server_modify_attributes(
dced_binding_handle_t dced_bh,
uuid_t *conf_uuid,
dced_attr_list_t *data,
error_status_t *status);
Parameters
Input
dced_bh Specifies the dced binding handle for the srvrconf
service on a specific host.
conf_uuid Specifies the UUID that dced uses to identify a
server's configuration data to modify.
data Specifies the attributes to be modified.
Output
status Returns the status code from this routine. This status
code indicates whether the routine completed
successfully or, if not, why not. The possible status
codes are:
error_status_ok
db_s_bad_index_type
db_s_iter_not_allowed
db_s_readonly
db_s_store_failed
dced_s_bad_binding
dced_s_not_found
sec_acl_invalid_permission
Usage
The dced_server_modify_attributes routine replaces the attributes of
a server's configuration data that are maintained by dced on a
specific host. This routine is typically called after a configuration
is created with the dced_server_create routine.
A server's configuration is manipulated in a server_t data structure,
and the dced_server_modify_attributes routine affects only the
attributes member of this structure. To change other server
configuration data, you must first delete the configuration by using
dced_server_delete and then create the configuration again by using
dced_server_create.
Prior to calling dced_server_modify_attributes, the application must
have established a valid dced binding handle to the srvrconf service
by calling either dced_binding_create or
dced_binding_from_rpc_binding.
Related Information
Routines:
dced_object_read
dced_binding_create
dced_binding_from_rpc_binding
Commands:
The server object of dcecp
Books:
DCE for OS/2 Warp: Application Development Guide - Core Components
ΓòÉΓòÉΓòÉ 3.11.49. dced_server_start ΓòÉΓòÉΓòÉ
Purpose
Starts a DCE-configured server on a specified host.
Format
#include <dce\dced.h>
void dced_server_start(
dced_binding_handle_t dced_bh,
uuid_t *conf_uuid,
dced_attr_list_t *attributes,
uuid_t *exec_uuid,
error_status_t *status);
Parameters
Input
dced_bh Specifies the dced binding handle for the srvrconf
service on a specific host.
conf_uuid Specifies the UUID that dced uses to identify the
server to start. If the value input is that of a
server that is already running, dced starts a new
instance.
attributes Specifies the configuration attributes to use to start
the server. If the value is NULL, the default
configuration defined in dced is used.
Input/Output
exec_uuid Specifies a new UUID for dced to use to identify the
running server. If a NIL UUID is input, a new UUID is
created and returned. If the value input is that of a
server that is already running, dced starts a new
instance and returns a new value.
Output
status Returns the status code from this routine. This status
code indicates whether the routine completed
successfully or, if not, why not. The possible status
codes are:
error_status_ok
db_s_bad_header_type
db_s_iter_not_allowed
db_s_key_not_found
db_s_readonly
db_s_store_failed
dced_s_bad_binding
dced_s_no_support
dced_s_not_found
dced_s_sc_cant_fork
dced_s_sc_invalid_attr_type
dced_s_sc_open_file_failed
sec_acl_invalid_permission
uuid_s_bad_version
Usage
The dced_server_start routine starts DCE-configured servers on a
specific remote host (or the local host). The configuration data is
stored in an object in the srvrconf service of dced. When the server
starts, dced uses the server configuration object and creates a
server execution object in the srvrexec service. A server execution
object consists of data that describes the executing server.
Management applications create the configuration data by using the
dced_server_create. Use the dced_object_read routine to read the
configuration or execution data.
Prior to calling dced_server_start, the application must have
established a valid dced binding handle to the srvrconf service by
calling either dced_binding_create or dced_binding_from_rpc_binding.
Examples
The following example starts a configured server using a nil UUID as
input for the executing server.
dced_binding_handle_t conf_bh;
dced_string_t server_name;
uuid_t srvrconf_id, srvrexec_id;
error_status_t status;
dced_binding_create("srvrconf@hosts/patrick",
dced_c_binding_syntax_default,
&conf_bh, &status);
dced_inq_id(conf_bh, server_name, &srvrconf_id, &status);
uuid_create_nil(&srvrexec_id, &status);
dced_server_start(conf_bh, &srvrconf_id, NULL, &srvrexec_id, &status);
.
.
.
Related Information
Routines:
dced_server_create
dced_server_stop
dced_binding_create
dced_binding_from_rpc_binding
Commands:
The server object of dcecp
Books:
DCE for OS/2 Warp: Application Development Guide - Core Components
ΓòÉΓòÉΓòÉ 3.11.50. dced_server_stop ΓòÉΓòÉΓòÉ
Purpose
Stops a DCE-configured server running on a specific host.
Format
#include <dce\dced.h>
void dced_server_stop(
dced_binding_handle_t dced_bh,
uuid_t *exec_uuid,
srvrexec_stop_method_t method,
error_status_t *status);
Parameters
Input
dced_bh Specifies the dced binding handle for the srvrexec
service on a specific host.
exec_uuid Specifies a UUID that dced uses to identify the running
server. If the value input is dced_g_uuid_all_servers,
dced attempts to stop all the DCE servers running on
that host.
method Specifies the method dced uses to stop a server. A
method is represented by one of the following values:
srvrexec_stop_rpc Uses the
rpc_mgmt_stop_server_listening
routine. This is the cleanest
way to stop a server, because
it waits for outstanding
remote procedure calls to
finish before making the
server's rpc_server_listen
routine return.
srvrexec_stop_soft Uses a soft local host
mechanism (such as the TERM
signal in UNIX).
srvrexec_stop_hard Uses a hard local host
mechanism (such as the KILL
signal in UNIX).
srvrexec_stop_error Uses a mechanism that saves
the program state (such as the
ABORT signal in UNIX).
Output
status Returns the status code from this routine. This status
code indicates whether the routine completed
successfully or, if not, why not. The possible status
codes are:
error_status_ok
dced_s_bad_binding
dced_s_no_support
dced_s_not_found
rpc_s_binding_incomplete
rpc_s_comm_failure
rpc_s_invalid_binding
rpc_s_mgmt_op_disallowed
rpc_s_unknown_if
rpc_s_wrong_kind_of_binding
sec_acl_invalid_permission
uuid_s_bad_version
Usage
The dced_server_stop routine stops DCE-configured servers on specific
hosts. When the server is completely stopped and no longer a running
process, dced deletes the associated execution data it maintained.
Administrators use the dcecp operations server create and server
start to configure and start a server, and management applications
use the associated dced_server_create and dced_server_start routines.
Prior to calling dced_server_stop, the application must have
established a valid dced binding handle to the srvrexec service by
calling either dced_binding_create or dced_binding_from_rpc_binding.
Cautions
Using the value dced_g_uuid_all_servers for the exec_uuid parameter
causes dced to shut down all servers including itself.
Examples
The following example obtains dced binding handles to the server
configuration and execution services of dced on the host patrick. The
example then checks to see if the server is running by seeing if dced
has a UUID and entry for the executing server. However, the server
may be in the process of starting up or stopping, so the example also
checks to be sure the instance UUID of the running server matches the
UUID of the configuration for that server. If there is a match, the
server is running. Finally, the example stops the server by calling
dced_server_stop with the srvrexec_stop_rpc parameter.
dced_binding_handle_t conf_bh, exec_bh;
dced_string_t server_name;
void *data;
server_t *exec_ptr;
uuid_t svrconf_id, srvrexec_id;
error_status_t status;
.
.
.
dced_binding_create("srvrconf@hosts/patrick",
dced_c_binding_syntax_default,
&conf_bh, &status);
dced_binding_create("srvrexec@hosts/patrick",
dced_c_binding_syntax_default,
&exec_bh, &status);
/* is server running? */
dced_inq_id(exec_bh, server_name, &srvrexec_id, &status);
/* also check to be sure server is not coming up or going down */
dced_object_read(exec_bh, &srvrexec_id, &data, &status);
exec_ptr = (server_t*)data;
dced_inq_id(conf_bh, server_name, &srvrconf_id, &status);
if(uuid_equal(&srvrconf_id,
&exec_ptr->exec_data.tagged_union.running_data.instance,
&status) ) {
dced_server_stop(exec_bh, &srvrexec_id, srvrexec_stop_rpc, &status);
}
dced_objects_release(exec_bh, 1, data, &status);
dced_binding_free(conf_bh, &status);
dced_binding_free(exec_bh, &status);
Related Information
Routines:
dced_server_create
dced_server_start
rpc_mgmt_stop_server_listening
dced_binding_create
dced_binding_from_rpc_binding
Commands:
The server object of dcecp
Books:
DCE for OS/2 Warp: Application Development Guide - Core Components
ΓòÉΓòÉΓòÉ 4. The DCE Threads API ΓòÉΓòÉΓòÉ
DCE Threads is a set of routines that you can call to create a multithreaded
program. Multithreading is used to improve the performance of a program.
Routines implemented by DCE Threads that are not specified by draft 4 of the
POSIX 1003.4a standard are indicated with an _np suffix. These routines are not
portable.
See the following subtopics for more information:
Exception Handling in DCE Threads
Data Types Used by DCE Threads
Threads Routines
ΓòÉΓòÉΓòÉ 4.1. Exception Handling in DCE Threads ΓòÉΓòÉΓòÉ
DCE Threads provides two ways to obtain information about the status of a
threads routine:
o The routine returns a status value to the thread.
o The routine raises an exception.
Before you write a multithreaded program, you must choose only one of these
two methods of receiving status. These two methods cannot be used together in
the same code module.
The POSIX P1003.4a (pthreads) draft standard specifies that errors be reported
to the thread by setting the external variable errno to an error code and
returning a routine value of -1. The threads reference pages document this
status value-returning interface. However, an alternative to status values is
provided by DCE Threads in the exception-returning interface.
Access to exceptions from the C language is defined by the macros in the
exc_handling.h file. The exc_handling.h header file is included automatically
when you include pthread_exc.h.
In order to catch DCE exceptions in the main thread, the main routine in a C
language program must make a call to the macro pthread_inst_exception_handler
as the first executable statement in that routine. Additionally, the macro
pthread_dinst_exception_handler must be called as the last executable
statement just before any return statement in the main routine. This macro
does not need to be installed at exit points that use the exit routine.
Exception handling is automatically installed in all threads created through
pthread_create.
The following example shows the syntax for handling exceptions:
TRY
try_block
[CATCH (exception_name)
handler_block]....
[CATCH_ALL
handler_block]
ENDTRY
ΓòÉΓòÉΓòÉ 4.2. Data Types Used by DCE Threads ΓòÉΓòÉΓòÉ
The DCE Threads data types can be divided into two broad categories, primitive
system and application level.
Primitive system data types consist of types that represent structures used by
(and internal to) DCE Threads. The following are defined as being primitive
system data types:
pthread_attr_t
pthread_cond_t
pthread_condattr_t
pthread_key_t
pthread_mutex_t
pthread_mutexattr_t
pthread_once_t
pthread_t
Although applications must know about these types, passing them in and
receiving them from various DCE Threads routines, the structures themselves
are opaque: they cannot be directly modified by applications, and they can be
manipulated only (and only in some cases) through specific DCE Threads
routines. (The pthread_key_t type is somewhat different from the others in
this list in that it is essentially a handle to a thread-private block of
memory requested by a call to pthread_keycreate.)
The application level data types consist of types used to describe objects
that originate in the application:
pthread_addr_t
pthread_destructor_t
pthread_initroutine_t
pthread_startroutine_t
sigset_t
All of the above types, with the exception of the last, are various kinds of
memory addresses that must be passed by callers of certain DCE Threads
routines. These types are extensions to POSIX. They permit DCE Threads to be
used on platforms that are not fully ANSI C compliant. While being extensions
to permit the use of compilers that are not ANSI C compatible, they are fully
portable data types.
The last data type, sigset_t, exhibits properties of both primitive system and
application level data types. While objects of this type originate in the
application, the data type is opaque. A set of routines is provided to
manipulate objects of this type.
Following are individual descriptions of each of the DCE Threads data types.
The descriptions include the routines where the data type is modified, for
example, created, changed or deleted, but not the routines referencing or
using them that do not change them.
pthread_addr_t A miscellaneous data type representing an address value
that must be passed by the caller of various Threads
routines. Usually the pthread_addr_t value is the address
of an area which contains various parameters to be made
accessible to an implicitly called routine. For example,
when the pthread_create routine is called, one of the
parameters passed is a pthread_addr_t value that contains
an address that will be passed to the start_routine, which
the thread is being created to run. Presumably the
routine will extract necessary parameters from the area
referenced by this address.
pthread_attr_t Threads attribute object, used to specify the attributes
of a thread when it is created by a call to
pthread_create. The object is created by a call to
pthread_attr_create, then modified as desired by calls to:
pthread_attr_setinheritsched
pthread_attr_setprio
pthread_attr_setsched
pthread_attr_setstacksize
(Note that there are _get versions of these four calls, which can be used to
retrieve the respective values.)
pthread_cond_t Data type representing a Threads condition variable. The
variable is created by a call to pthread_cond_init, and
destroyed by a call to pthread_cond_destroy.
pthread_condattr_t Data type representing a Threads condition variable
attributes object, created by a call to
pthread_condattr_create. The range of possible
modifications to a condition variable attributes object is
not great: creation (by means of pthread_condattr_create)
and deletion (by means of pthread_condattr_delete) are
all. The object is created with default values.
pthread_destructor_t Data type, passed in a call to pthread_keycreate,
representing the address of a procedure to be called to
destroy a data value associated with a unique
thread-specific data key value when the thread terminates.
pthread_initroutine_t Data type representing the address of a procedure that
performs a one-time initialization for a thread. It is
passed in a call to pthread_once. The pthread_once
routine, when called, runs the initialization routine. The
specified routine is guaranteed to be run only once, even
though the pthread_once call occurs in multi-threaded
code.
pthread_key_t Data type representing a thread-specific data key, created
by a call to pthread_keycreate. The key is an address of
memory. Associating a static block of memory with a
specific thread in this way is an alternative to using
stack memory for the thread. The key is destroyed by the
application-supplied procedure specified by the routine
specified using the pthread_destructor_t data type in the
call to pthread_keycreate.
pthread_mutex_t Data type representing a mutex object. It is created by a
call to pthread_mutex_init and destroyed by a call to
pthread_mutex_destroy. Care should be taken not to attempt
to destroy a locked mutex.
pthread_mutexattr_t Data type representing an attributes object which defines
the characteristics of a mutex. The mutex attributes
object is created by a call to pthread_mutexattr_create.
Objects of this data type can be modified by calls to
pthread_mutexattr_setkind_np (which allows you to specify
fast, recursive, or non-recursive mutexes), and passed to
pthread_mutex_init to create a mutex with the specified
attributes. The only other modification allowed is to
destroy the mutex attributes object, with
pthread_mutexattr_delete.
pthread_once_t A data structure that defines the characteristics of the
one-time initialization routine run by calling
pthread_once. The structure is opaque to the application,
and cannot be modified by it, but it must be explicitly
declared by the client code, and initialized by a call to
pthread_once_init. The pthread_once_t type must not be an
array.
pthread_startroutine_t Data type representing the address of the application
routine or other routine that a new thread is created to
run as its start routine.
pthread_t Data type representing a thread handle, created by a call
to pthread_create. The thread handle is used to identify
the thread to calls such as pthread_cancel,
pthread_detach, pthread_equal (to which two handles are
passed for comparison).
sigset_t Data type representing a set of signals. It is always an
integer or structure type. If a structure, it is intended
to be a simple structure, for example, a set of arrays as
opposed to a set of pointers. It is opaque in that a set
of routines called the sigsetops primitives is provided to
manipulate signal sets. These routines operate on signal
set data objects addressable by the application, not on
any objects known to the system.
The primitives are sigemptyset and sigfillset, which
initialize the set as either empty or full, sigaddset and
sigdelset, which add or delete signals from the set, and
sigismember, which permits the application to check if an
object (signal) of type sigset_t is a member of the signal
set. Applications must call at least one of the
initialization primitives at least once for each object of
type sigset_t prior to any other use of that object
(signal set).
The object, or objects, represented by this data type when
used by sigaction are used in conjunction with a sigaction
structure by the sigaction routine to describe an action
to be taken with specified sigset_t objects.
ΓòÉΓòÉΓòÉ 4.3. Threads Routines ΓòÉΓòÉΓòÉ
The Threads routines can be divided into ten different functional groups. They
include:
o Threads Routines
o Routines that Implicitly Perform Threads Initialization
o Attributes Object Routines
o Mutex Routines
o Condition Variable Routines
o Thread-Specific Data Routines
o Threads Cancelation Routines
o Threads Priority and Scheduling Routines
o Threads Cleanup Routines
ΓòÉΓòÉΓòÉ 4.3.1. Threads Routines ΓòÉΓòÉΓòÉ
pthread_create Creates a thread.
pthread_delay_np Causes a thread to wait for a period of time.
pthread_detach Marks a thread for deletion.
pthread_equal Compares one thread identifier to another thread
identifier.
pthread_exit Terminates the calling thread.
pthread_getunique_np Obtains the sequence number associated with a
thread.
pthread_join Causes the calling thread to wait for the
termination of a specified thread.
pthread_once Calls an initialization routine to be executed
only once.
pthread_self Obtains the identifier of the current thread.
pthread_yield Notifies the scheduler that the current thread
will release its processor to other threads of
the same or higher priority.
ΓòÉΓòÉΓòÉ 4.3.2. Routines that Implicitly Perform Threads Initialization ΓòÉΓòÉΓòÉ
pthread_attr_create Creates a thread attributes object.
pthread_create Creates a thread.
pthread_cond_init Creates a condition variable.
pthread_condattr_create Creates a condition variable attributes object.
pthread_delay_np Causes a thread to wait for a period of time.
pthread_attr_getprio Obtains the scheduling priority attribute.
pthread_attr_getsched Obtains the scheduling policy attribute.
pthread_keycreate Generates a unique thread-specific data key
value.
pthread_mutex_init Creates a mutex.
pthread_mutexattr_create Creates a mutex attributes object.
pthread_once Calls an initialization routine to be executed
only once.
pthread_self Obtains the identifier of the current thread.
pthread_setasynccancel Enables or disables the current thread's
asynchronous cancelling ability.
pthread_cancel Enables or disables the current thread's general
cancelability.
pthread_setprio Changes the scheduling priority attribute.
pthread_setscheduler Obtains the scheduling policy attribute
pthread_testcancel Requests delivery of a pending cancel.
ΓòÉΓòÉΓòÉ 4.3.3. Attributes Object Routines ΓòÉΓòÉΓòÉ
pthread_attr_create Creates a thread attributes object.
pthread_attr_delete Deletes a thread attributes object.
pthread_attr_getinheritsched Obtains the inherit scheduling attribute
pthread_attr_getprio Obtains the scheduling priority attribute.
pthread_attr_getsched Obtains the scheduling policy attribute.
pthread_attr_getstacksize Obtains the stacksize attribute.
pthread_attr_setinheritsched Changes the inherit scheduling attribute.
pthread_attr_setprio Changes the scheduling priority attribute.
pthread_attr_setsched Changes the scheduling policy attribute.
pthread_attr_setstacksize Changes the stacksize attribute.
pthread_condattr_create Creates a condition variable attributes object.
pthread_condattr_delete Deletes a condition variable attributes object.
pthread_mutexattr_create Creates a mutex attributes object.
pthread_mutexattr_delete Deletes a mutex attributes object.
pthread_mutexattr_getkind_np Obtains the mutex type attribute.
pthread_mutexattr_setkind_np Changes the mutex type attribute.
ΓòÉΓòÉΓòÉ 4.3.4. Mutex Routines ΓòÉΓòÉΓòÉ
pthread_lock_global_np Locks a global mutex.
pthread_mutex_destroy Deletes a mutex.
pthread_mutex_init Creates a mutex.
pthread_mutex_lock Locks a mutex and waits if the mutex is already
locked.
pthread_mutex_trylock Locks a mutex and returns if the mutex is
already locked.
pthread_mutex_unlock Unlocks a mutex.
pthread_unlock_global_np Unlocks a global mutex.
ΓòÉΓòÉΓòÉ 4.3.5. Condition Variable Routines ΓòÉΓòÉΓòÉ
pthread_cond_broadcast Wakes all threads waiting on a condition
variable.
pthread_cond_destroy Deletes a condition variable.
pthread_cond_init Creates a condition variable.
pthread_cond_signal Wakes one thread waiting on a condition
variable.
pthread_cond_timedwait Causes a thread to wait for a specified period
of time for a condition variable to be signaled
or broadcast.
pthread_cond_wait Causes a thread to wait for a condition variable
to be signaled or broadcast.
pthread_get_expiration_np Obtains a value representing a desired
expiration time.
ΓòÉΓòÉΓòÉ 4.3.6. Thread-Specific Data Routines ΓòÉΓòÉΓòÉ
pthread_getspecific Obtains the thread-specific data associated with
the specified key.
pthread_keycreate Generates a unique thread-specific data key
value.
pthread_setspecific Sets the thread-specific data associated with
the specified key.
ΓòÉΓòÉΓòÉ 4.3.7. Threads Cancelation Routines ΓòÉΓòÉΓòÉ
pthread_cancel Allows a thread to request termination.
pthread_setasynccancel Enables or disables the current thread's
asynchronous cancelability.
pthread_setcancel Enables or disables the current thread's general
cancelability.
pthread_testcancel Requests delivery of a pending cancel.
ΓòÉΓòÉΓòÉ 4.3.8. Threads Priority and Scheduling Routines ΓòÉΓòÉΓòÉ
pthread_getprio Obtains the current priority of a thread.
pthread_getscheduler Obtains the current scheduling policy of a
thread.
pthread_setprio Changes the current priority of a thread.
pthread_setscheduler Changes the current scheduling policy and
priority of a thread.
ΓòÉΓòÉΓòÉ 4.3.9. Threads Cleanup Routines ΓòÉΓòÉΓòÉ
pthread_cleanup_pop Removes a cleanup handler from the stack.
pthread_cleanup_push Establishes a cleanup handler.
ΓòÉΓòÉΓòÉ 4.3.10. pthread_attr_create ΓòÉΓòÉΓòÉ
Purpose
Creates a thread attributes object.
Format
#include <pthread.h>
int pthread_attr_create(
pthread_attr_t *attr);
Parameters
attr Thread attributes object created.
Usage
The pthread_attr_create routine creates a thread attributes object
that is used to specify the attributes of threads when they are
created. The attributes object created by this routine is used in
calls to pthread_create.
The individual attributes (internal fields) of the attributes object
are set to default values. (The default values of each attribute are
discussed in the descriptions of the following services.) Use the
following routines to change the individual attributes:
o pthread_attr_setinheritsched
o pthread_attr_setprio
o pthread_attr_setsched
o pthread_attr_setstacksize
When an attributes object is used to create a thread, the values of
the individual attributes determine the characteristics of the new
thread. Attributes objects perform in a manner similar to additional
parameters. Changing individual attributes does not affect any
threads that were previously created using the attributes object.
Note that if the pthreads exception handling header file
pthread_exc.h is used instead of pthread.h, then a DCE exception is
raised.
Return Codes
If the routine fails, -1 is returned and errno may be set to one of
the following values:
Error Description
-1 [ENOMEM] Insufficient memory exists to create the thread
attributes object.
-1 [EINVAL] The value specified by attr is invalid.
Related Information
Routines: pthread_attr_delete
pthread_attr_setinheritsched
pthread_attr_setprio
pthread_attr_setsched
pthread_attr_setstacksize
pthread_create
ΓòÉΓòÉΓòÉ 4.3.11. pthread_attr_delete ΓòÉΓòÉΓòÉ
Purpose
Deletes a thread attributes object.
Format
#include <pthread.h>
int pthread_attr_delete(
pthread_attr_t *attr);
Parameters
attr Thread attributes object deleted.
Usage
The pthread_attr_delete routine deletes a thread attributes object
and gives permission to reclaim storage for the thread attributes
object. Threads that were created using the thread attributes object
are not affected by the deletion of the thread attributes object.
The results of calling this routine are unpredictable if the value
specified by the attr parameter refers to a thread attributes object
that does not exist. Note that if the pthreads exception handling
header file pthread_exc.h is used instead of pthread.h, then a DCE
exception is raised.
Return Codes
If the routine fails, errno may be set to the following value:
Error Description
-1 [EINVAL] The value specified by attr is invalid.
Related Information
Routines:
pthread_attr_create
ΓòÉΓòÉΓòÉ 4.3.12. pthread_attr_getinheritsched ΓòÉΓòÉΓòÉ
Purpose
Obtains the inherit scheduling attribute of the specified thread
attributes object.
Format
#include <pthread.h>
int pthread_attr_getinheritsched(
pthread_attr_t attr);
Parameters
attr Thread attributes object whose inherit scheduling
attribute is obtained.
Usage
The pthread_attr_getinheritsched routine obtains the value of the
inherit scheduling attribute in the specified thread attributes
object. The inherit scheduling attribute specifies whether threads
created using the attributes object inherit the scheduling attributes
of the creating thread, or use the scheduling attributes stored in
the attributes object that is passed to pthread_create.
The default value of the inherit scheduling attribute is
PTHREAD_INHERIT_SCHED.
Return Codes
On successful completion, this routine returns the inherit scheduling
attribute value.
If the routine fails, errno may be set to the following value:
Error Description
-1 [EINVAL] The value specified by attr is invalid.
Related Information
Routines: pthread_attr_create
pthread_attr_setinheritsched
pthread_create
ΓòÉΓòÉΓòÉ 4.3.13. pthread_attr_getprio ΓòÉΓòÉΓòÉ
Purpose
Obtains the scheduling priority attribute of the specified thread
attributes object.
Format
#include <pthread.h>
int pthread_attr_getprio(
pthread_attr_t attr);
Parameters
attr Thread attributes object whose priority attribute is
obtained.
Usage
The pthread_attr_getprio routine obtains the value of the scheduling
priority of threads created using the thread attributes object
specified by the attr parameter.
Return Codes
On successful completion, this routine returns the scheduling
priority attribute value.
If the routine fails, errno may be set to the following value:
Error Description
-1 [EINVAL] The value specified by attr is invalid.
Related Information
Routines: pthread_attr_create
pthread_attr_setprio
pthread_create
ΓòÉΓòÉΓòÉ 4.3.14. pthread_attr_getsched ΓòÉΓòÉΓòÉ
Purpose
Obtains the value of the scheduling policy attribute in the specified
thread attributes object.
Format
#include <pthread.h>
int pthread_attr_getsched(
pthread_attr_t attr);
Parameters
attr Thread attributes object whose scheduling policy
attribute is obtained.
Usage
The pthread_attr_getsched routine obtains the scheduling policy of
threads created using the thread attributes object specified by the
attr parameter. The default value of the scheduling attribute is
SCHED_HRR.
Return Codes
On successful completion, this routine returns the value of the
scheduling policy attribute.
If the routine fails, errno may be set to the following value:
Error Description
-1 [EINVAL] The value specified by attr is invalid.
Related Information
Routines: pthread_attr_create
pthread_attr_setsched
pthread_create
ΓòÉΓòÉΓòÉ 4.3.15. pthread_attr_getstacksize ΓòÉΓòÉΓòÉ
Purpose
Obtains the value of the stacksize attribute in the specified thread
attributes object.
Format
#include <pthread.h>
long pthread_attr_getstacksize(
pthread_attr_t attr);
Parameters
attr Thread attributes object whose stacksize attribute is
obtained.
Usage
The pthread_attr_getstacksize routine obtains the minimum size (in
bytes) of the stack for a thread created using the thread attributes
object specified by the attr parameter.
Return Codes
On successful completion, this routine returns the stacksize
attribute value.
If the routine fails, errno may be set to the following value:
Error Description
-1 [EINVAL] The value specified by attr is invalid.
Related Information
Routines: pthread_attr_create
pthread_attr_setstacksize
pthread_create
ΓòÉΓòÉΓòÉ 4.3.16. pthread_attr_setinheritsched ΓòÉΓòÉΓòÉ
Purpose
Changes the inherit scheduling attribute of the specified thread
attributes object.
Format
#include <pthread.h>
int pthread_attr_setinheritsched(
pthread_attr_t *attr,
int inherit);
Parameters
attr Thread attributes object to be modified.
inherit New value for the inherit scheduling attribute. Valid
values are as follows:
PTHREAD_INHERIT_SCHED This is the default value.
The created thread inherits
the current priority and
scheduling policy of the
thread calling
pthread_create.
PTHREAD_DEFAULT_SCHED The created thread starts
execution with the priority
and scheduling policy stored
in the thread attributes
object.
Usage
The pthread_attr_setinheritsched routine changes the inherit
scheduling attribute of thread creation. The inherit scheduling
attribute specifies whether threads created using the specified
thread attributes object inherit the scheduling attributes of the
creating thread, or use the scheduling attributes stored in the
thread attributes object that is passed to pthread_create.
The first thread in an application that is not created by an explicit
call to pthread_create has a scheduling policy of SCHED_HRR. See the
pthread_attr_setprio and pthread_attr_setsched routines for more
information on valid priority values and valid scheduling policy
values, respectively.
Inheriting scheduling attributes (instead of using the scheduling
attributes stored in the attributes object) is useful when a thread
is creating several helper threads. That is, threads that are
intended to work closely with the creating thread to cooperatively
solve the same problem. For example, inherited scheduling attributes
ensure that helper threads created in a sort routine run with the
same priority as the calling thread. Note that if the pthreads
exception handling header file pthread_exc.h is used instead of
pthread.h, then a DCE exception is raised.
Return Codes
If the routine fails, -1 is returned and errno may be set to one of
the following values:
Error Description
-1 [EINVAL] The value specified by attr is invalid.
-1 [EINVAL] The value specified by inherit is invalid.
Related Information
Routines: pthread_attr_create
pthread_attr_getinheritsched
pthread_attr_setprio
pthread_attr_setsched
pthread_create
ΓòÉΓòÉΓòÉ 4.3.17. pthread_attr_setprio ΓòÉΓòÉΓòÉ
Purpose
Changes the scheduling priority attribute of thread creation.
Format
#include <pthread.h>
int pthread_attr_setprio(
pthread_attr_t *attr,
int priority);
Parameters
attr Thread attributes object modified.
priority New value for the priority attribute. The priority
attribute depends upon scheduling policy. Valid values
fall within the following range:
o PRI_HRR_MIN <= priority <= PRI_HRR_MAX
The default priority is PRI_HRR_MIN. To specify a
minimum or maximum priority, use the appropriate
symbol. For example, PRI_HRR_MIN or PRI_HRR_MAX. To
specify a value between the minimum and maximum, use an
appropriate arithmetic expression. For example, to set
a priority midway between the minimum and maximum,
specify the following concept using your programming
language's syntax:
pri_hrr_mid = (PRI_HRR_MIN + PRI_HRR_MAX + 1)/2
If your expression results in a value outside the range
of minimum to maximum, an error results when you
attempt to use it.
Usage
The pthread_attr_setprio routine sets the execution priority of
threads that are created using the attributes object specified by the
attr parameter.
By default, a created thread inherits the priority of the thread
calling pthread_create. To specify a priority using this routine,
scheduling inheritance must be disabled at the time the thread is
created. Call pthread_attr_setinheritsched and specify the value
PTHREAD_DEFAULT_SCHED for the inherit parameter before calling this
routine and pthread_create.
An application specifies priority only to express the urgency of
executing the thread relative to other threads. Priority is not used
to control mutual exclusion when accessing shared data. With a
sufficient number of processors executing, all ready threads,
regardless of priority, run simultaneously.
Note: Changing the scheduling priority of a thread should only be
done from root.
Note that if the pthreads exception handling header file
pthread_exc.h is used instead of pthread.h, then a DCE exception is
raised.
Return Codes
If the routine fails, errno may be set to one of the following
values:
Error Description
-1 [EINVAL] The value specified by attr is invalid.
-1 [ERANGE] One or more parameters supplied have an invalid value.
Related Information
Routines:
pthread_attr_create
pthread_attr_getprio
pthread_attr_setinheritsched
pthread_create
ΓòÉΓòÉΓòÉ 4.3.18. pthread_attr_setsched ΓòÉΓòÉΓòÉ
Purpose
Changes the scheduling policy attribute of thread creation.
Format
#include <pthread.h>
int pthread_attr_setsched(
pthread_attr_t *attr,
int scheduler);
Parameters
attr Thread attributes object modified.
scheduler New value for the scheduling policy attribute. Valid
values are as follows:
SCHED_HRR (Hierarchical Round Robin). Each
thread has a priority associated with
it. Threads of a higher priority are
given access to the CPU before
threads of lower priority. If a
thread with a higher priority than
the currently running thread becomes
ready to run, the current thread is
stopped immediately. Threads of the
same priority are given time-slices
in a round robin manner.
Usage
The pthread_attr_setsched routine sets the scheduling policy of a
thread that is created using the attributes object specified by the
attr parameter. The default value of the scheduling attribute is
SCHED_HRR.
Note: Setting and changing the scheduling policy should only be done
from root.
Note that if the pthreads exception handling header file
pthread_exc.h is used instead of pthread.h, then a DCE exception is
raised.
Return Codes
If the routine fails, errno may be set to one of the following
values:
Error Description
-1 [EINVAL] The value specified by attr is invalid.
-1 [EINVAL] The value specified by scheduler is invalid.
-1 [EPERM] The caller does not have the appropriate privileges to
set the scheduling policy attribute of the specified
thread attributes object.
Related Information
Routines:
pthread_attr_create
pthread_attr_getsched
pthread_attr_setinheritsched
pthread_create
ΓòÉΓòÉΓòÉ 4.3.19. pthread_attr_setstacksize ΓòÉΓòÉΓòÉ
Purpose
Changes the stacksize attribute of thread creation.
Format
#include <pthread.h>
int pthread_attr_setstacksize(
pthread_attr_t *attr,
long stacksize);
Parameters
attr Thread attributes object modified.
stacksize New value for the stacksize attribute. The stacksize
parameter specifies the minimum size (in bytes) of the
stack needed for a thread.
Usage
The pthread_attr_setstacksize routine sets the minimum size (in
bytes) of the stack needed for a thread created using the attributes
object specified by the attr parameter. Use this routine to adjust
the size of the writable area of the stack. The default value of the
stacksize attribute is 32,768 bytes.
A thread's stack is fixed at the time of thread creation. Only the
main or initial thread can dynamically extend its stack.
Most compilers do not check for stack overflow. Ensure that your
thread stack is large enough for anything that you call from the
thread. Note that if the pthreads exception handling header file
pthread_exc.h is used instead of pthread.h, then a DCE exception is
raised.
Return Codes
If the routine fails, errno may be set to one of the following
values:
Error Description
-1 [EINVAL] The value specified by attr is invalid.
-1 [EINVAL] The value specified by stacksize is invalid.
Related Information
Routines: pthread_attr_create
pthread_attr_getstacksize
pthread_create
ΓòÉΓòÉΓòÉ 4.3.20. pthread_cancel ΓòÉΓòÉΓòÉ
Purpose
Allows a thread to request that it or another thread stop running.
Format
#include <pthread.h>
int pthread_cancel(
pthread_t thread);
Parameters
thread Thread that receives a cancel request.
Usage
The pthread_cancel routine sends a cancel to the specified thread. A
cancel is a mechanism by which a calling thread informs either itself
or the called thread to terminate as quickly as possible. Issuing a
cancel does not guarantee that the canceled thread receives or
handles the cancel. The canceled thread can delay processing the
cancel after receiving it. For instance, if a cancel arrives during
an important operation, the canceled thread can continue if what it
is doing cannot be interrupted at the point where the cancel is
requested.
Because of communication delays, the calling thread can only rely on
the fact that a cancel eventually becomes pending in the designated
thread (provided that the thread does not terminate beforehand).
Furthermore, the calling thread has no guarantee that a pending
cancel is to be delivered because delivery is controlled by the
designated thread.
Termination processing when a cancel is delivered to a thread is
similar to pthread_exit. Outstanding cleanup routines are run in the
context of the target thread, and a status of -1 is made available to
any threads joining with the target thread.
The results of this routine are unpredictable if the value specified
in thread refers to a thread that does not currently exist. Note that
if the pthreads exception handling header file pthread_exc.h is used
instead of pthread.h, then a DCE exception is raised.
Return Codes
If the routine fails, errno may be set to one of the following
values:
Error Description
-1 [EINVAL] The specified thread is invalid.
-1 [ERSCH] The specified thread does not refer to a currently
existing thread.
Related Information
Routines: pthread_exit
pthread_join
pthread_setasynccancel
pthread_setcancel
pthread_testcancel
ΓòÉΓòÉΓòÉ 4.3.21. pthread_cleanup_pop ΓòÉΓòÉΓòÉ
Purpose
Removes the cleanup handler at the top of the cleanup stack and
optionally runs it.
Format
#include <pthread.h>
void pthread_cleanup_pop(
int execute);
Parameters
execute Integer that specifies whether the cleanup routine that
is popped should be run or just discarded. If the
value is non-zero, the cleanup routine is run.
Usage
The pthread_cleanup_pop routine removes the routine specified in
pthread_cleanup_push from the top of the calling thread's cleanup
stack and runs it if the value specified in execute is nonzero.
This routine and pthread_cleanup_push are implemented as macros and
must be displayed as statements and in pairs within the same lexical
scope. You can think of the pthread_cleanup_push macro as expanding
to a string whose first character is a left brace ({) and
pthread_cleanup_pop expanding to a string containing the
corresponding right brace (}).
This routine must be used as a statement.
Related Information
Routines:
pthread_cleanup_push
ΓòÉΓòÉΓòÉ 4.3.22. pthread_cleanup_push ΓòÉΓòÉΓòÉ
Purpose
Establishes a cleanup handler.
Format
#include <pthread.h>
void pthread_cleanup_push(
void( *routine) (),
pthread_addr_t arg);
Parameters
routine Routine run as the cleanup handler.
arg Parameter run with the cleanup routine.
Usage
The pthread_cleanup_push routine pushes the specified routine onto
the calling thread's cleanup stack. The cleanup routine is popped
from the stack and run with the arg parameter when any of the
following actions occur:
o The thread calls pthread_exit.
o The thread is canceled.
o The thread calls pthread_cleanup_pop and specifies a nonzero
value for the execute parameter.
This routine and pthread_cleanup_pop are implemented as macros and
must be displayed as statements and in pairs within the same lexical
scope. You can think of the pthread_cleanup_push macro as expanding
to a string whose first character is a left brace ({) and
pthread_cleanup_pop as expanding to a string containing the
corresponding right brace (}).
This routine must be used as a statement.
Related Information
Routines: pthread_cancel
pthread_cleanup_pop
pthread_exit
pthread_testcancel
ΓòÉΓòÉΓòÉ 4.3.23. pthread_cond_broadcast ΓòÉΓòÉΓòÉ
Purpose
Wakes all threads that are waiting for a condition variable.
Format
#include <pthread.h>
int pthread_cond_broadcast(
pthread_cond_t *cond);
Parameters
cond Condition variable broadcast.
Usage
The pthread_cond_broadcast routine wakes all threads waiting for a
condition variable. Calling this routine implies that data guarded by
the associated mutex has changed. This allows one or more waiting
threads to proceed. If any thread is waiting to proceed, call
pthread_cond_signal.
You can call this routine when the associated mutex is either locked
or unlocked. Note that if the pthreads exception handling header file
pthread_exc.h is used instead of pthread.h, then a DCE exception is
raised.
Return Codes
If the routine fails, errno may be set to one of the following
values:
Error Description
0 Successful completion.
-1 [EINVAL] The value specified by cond is invalid.
Related Information
Routines: pthread_cond_destroy
pthread_cond_init
pthread_cond_signal
pthread_cond_timedwait
pthread_cond_wait
ΓòÉΓòÉΓòÉ 4.3.24. pthread_cond_destroy ΓòÉΓòÉΓòÉ
Purpose
Deletes a condition variable.
Format
#include <pthread.h>
int pthread_cond_destroy(
pthread_cond_t *cond);
Parameters
cond Condition variable deleted.
Usage
The pthread_cond_destroy routine deletes a condition variable. Call
this routine when a condition variable is no longer referenced. The
effect of calling this routine is to give permission to reclaim
storage for the condition variable.
The results of this routine are unpredictable if the condition
variable specified in cond does not exist.
The results of this routine are also unpredictable if there are
threads waiting for the specified condition variable to be signaled
or broadcast when it is deleted. Note that if the pthreads exception
handling header file pthread_exc.h is used instead of pthread.h, then
a DCE exception is raised.
Return Codes
If the routine fails, errno may be set to one of the following
values:
Error Description
0 Successful completion.
-1 [EINVAL] The value specified by cond is invalid.
-1 [EBUSY] A thread is currently executing a pthread_cond_wait or
pthread_cond_timedwait on the condition variable
specified in cond.
Related Information
Routines: pthread_cond_broadcast
pthread_cond_init
pthread_cond_signal
pthread_cond_timedwait
pthread_cond_wait
ΓòÉΓòÉΓòÉ 4.3.25. pthread_cond_init ΓòÉΓòÉΓòÉ
Purpose
Creates a condition variable.
Format
#include <pthread.h>
int pthread_cond_init(
pthread_cond_t *cond,
pthread_condattr_t attr);
Parameters
cond Condition variable that is created.
attr Condition variable attributes object that defines the
characteristics of the condition variable created. If
you specify pthread_condattr_default, default
attributes are used.
Usage
The pthread_cond_init routine creates and initializes a condition
variable. A condition variable is a synchronization object used in
conjunction with a mutex. A mutex controls access to shared data,
whereas a condition variable allows threads to wait for that data to
enter a defined state. The state is defined by a Boolean expression
called a predicate.
A condition variable is signaled or broadcast to indicate that a
predicate may have become true. The broadcast operation indicates
that all waiting threads need to resume and re-evaluate the
predicate. The signal operation is used when any one waiting thread
can continue.
If a thread that holds a mutex determines that the shared data is not
in the correct state for it to proceed (the associated predicate is
not true), it waits for a condition variable associated with the
desired state. Waiting for the condition variable automatically
releases the mutex so that other threads can modify or examine the
shared data. When a thread modifies the state of the shared data so
that a predicate might be true, it signals or broadcasts on the
appropriate condition variable so that threads waiting for that
predicate can continue.
It is important that all threads waiting for a particular condition
variable at any time hold the same mutex. If they do not, the
behavior of the wait operation is unpredictable (an implementation
can use the mutex to control internal access to the condition
variable object). However, it is legal for a client to store
condition variables and mutexes and later reuse them in different
combinations. The client must ensure that no threads use the
condition variable with the old mutex. At any time, an arbitrary
number of condition variables can be associated with a single mutex,
each representing a different predicate of the shared data protected
by that mutex.
Condition variables are not owned by a particular thread. Any
associated storage is not automatically deallocated when the creating
thread terminates. Note that if the pthreads exception handling
header file pthread_exc.h is used instead of pthread.h, then a DCE
exception is raised.
Return Codes
If the routine fails, errno may be set to one of the following
values:
Error Description
0 Successful completion.
-1 [EAGAIN] The system lacks the necessary resources to initialize
another condition variable.
-1 [EINVAL] Invalid attributes object.
-1 [ENOMEM] Insufficient memory exists to initialize the condition
variable.
Related Information
Routines: pthread_cond_broadcast
pthread_cond_destroy
pthread_cond_signal
pthread_cond_timedwait
pthread_cond_wait
ΓòÉΓòÉΓòÉ 4.3.26. pthread_cond_signal ΓòÉΓòÉΓòÉ
Purpose
Wakes one thread that is waiting for a condition variable.
Format
#include <pthread.h>
int pthread_cond_signal(
pthread_cond_t *cond);
Parameters
cond Condition variable signaled.
Usage
The pthread_cond_signal routine wakes one thread waiting for a
condition variable. Calling this routine implies that data guarded by
the associated mutex has changed so that it is possible for a single
waiting thread to proceed. Call this routine when any thread waiting
for the specified condition variable might find its predicate true,
but only if one thread needs to proceed.
The scheduling policy determines which thread is awakened. For policy
SCHED_HRR a thread is chosen in priority order.
You can call this routine when the associated mutex is either locked
or unlocked. Note that if the pthreads exception handling header file
pthread_exc.h is used instead of pthread.h, then a DCE exception is
raised.
Return Codes
If the routine fails, errno may be set to one of the following
values:
Error Description
0 Successful completion.
-1 [EINVAL] The value specified by cond is invalid.
Related Information
Routines:
pthread_cond_broadcast
pthread_cond_destroy
pthread_cond_init
pthread_cond_timedwait
pthread_cond_wait
ΓòÉΓòÉΓòÉ 4.3.27. pthread_cond_timedwait ΓòÉΓòÉΓòÉ
Purpose
Causes a thread to wait for a condition variable to be signaled or
broadcast for a specified period of time.
Format
#include <pthread.h>
int pthread_cond_timedwait(
pthread_cond_t *cond,
pthread_mutex_t *mutex,
struct timespec *abstime);
Parameters
cond Condition variable waited for.
mutex Mutex associated with the condition variable specified
in cond.
abstime Absolute time at which the wait expires, if the
condition has not been signaled or broadcast. (See
pthread_get_expiration_np, which you can use to obtain
a value for this parameter.)
Usage
The pthread_cond_timedwait routine causes a thread to wait until one
of the following occurs:
o The specified condition variable is signaled or broadcast.
o The current system clock time is greater than or equal to the
time specified by the abstime parameter.
This routine is identical to pthread_cond_wait except that this
routine can return before a condition variable is signaled or
broadcast - specifically, when a specified time expires.
If the current time equals or exceeds the expiration time, this
routine returns immediately, without causing the current thread to
wait.
Call this routine after you lock the mutex specified in mutex. The
results of this routine are unpredictable if this routine is called
without first locking the mutex.
Return Codes
If the routine fails, errno may be set to one of the following
values:
Error Description
0 Successful completion.
-1 [EINVAL] The value specified by cond, mutex or abstime is
invalid.
-1 [EAGAIN] The time specified by abstime expired.
-1 [EDEADLK] A deadlock condition is detected.
Related Information
Routines: pthread_cond_broadcast
pthread_cond_destroy
pthread_cond_init
pthread_cond_signal
pthread_cond_wait
pthread_get_expiration_np
ΓòÉΓòÉΓòÉ 4.3.28. pthread_cond_wait ΓòÉΓòÉΓòÉ
Purpose
Causes a thread to wait for a condition variable to be signaled or
broadcast.
Format
#include <pthread.h>
int pthread_cond_wait(
pthread_cond_t *cond,
pthread_mutex_t *mutex);
Parameters
cond Condition variable waited for.
mutex Mutex associated with the condition variable specified
in cond.
Usage
The pthread_cond_wait routine causes a thread to wait for a condition
variable to be signaled or broadcast. Each condition corresponds to
one or more predicates based on shared data. The calling thread
waits for the data to reach a particular state (for the predicate to
become true).
Call this routine after you have locked the mutex specified in mutex.
The results of this routine are unpredictable if this routine is
called without first locking the mutex.
This routine automatically releases the mutex and causes the calling
thread to wait for the condition. If the wait is satisfied as a
result of some thread calling pthread_cond_signal or
pthread_cond_broadcast, the mutex is re-acquired and the routine
returns.
A thread that changes the state of storage protected by the mutex in
such a way that a predicate associated with a condition variable
might now be true must call either pthread_cond_signal or
pthread_cond_broadcast for that condition variable. If neither call
is made, any thread waiting for the condition variable continues to
wait.
This routine will, with low probability, return when the condition
variable has not been signaled or broadcast. When a spurious wakeup
occurs, the mutex is re-acquired before the routine returns. (To
handle this situation, enclose the routine in a loop that checks the
predicate.) Note that if the pthreads exception handling header file
pthread_exc.h is used instead of pthread.h, then a DCE exception is
raised.
Return Codes
If the routine fails, errno may be set to one of the following
values:
Error Description
0 Successful completion.
-1 [EINVAL] The value specified by cond or mutex is invalid.
-1 [EDEADLK] A deadlock condition is detected.
Related Information
Routines:
pthread_cond_broadcast
pthread_cond_destroy
pthread_cond_init
pthread_cond_signal
pthread_cond_timedwait
ΓòÉΓòÉΓòÉ 4.3.29. pthread_condattr_create ΓòÉΓòÉΓòÉ
Purpose
Creates a condition variable attributes object.
Format
#include <pthread.h>
int pthread_condattr_create(
pthread_condattr_t *attr);
Parameters
attr Condition variable attributes object that is created.
Usage
The pthread_condattr_create routine creates a condition variable
attributes object that is used to specify the attributes of condition
variables when they are created. The condition variable attributes
object is initialized with the default value for all of the
attributes defined by a given implementation.
When a condition variable attributes object is used to create a
condition variable, the values of the individual attributes determine
the characteristics of the new object. Attributes objects act like
additional parameters to object creation. Changing individual
attributes does not affect objects that were previously created using
the attributes object. Note that if the pthreads exception handling
header file pthread_exc.h is used instead of pthread.h, then a DCE
exception is raised.
Return Codes
The created condition variable attributes object is returned to the
attr parameter.
If the routine fails, errno may be set to one of the following
values:
Error Description
0 Successful completion
-1 [EINVAL] The value specified by attr is invalid.
-1 [ENOMEM] Insufficient memory exists to create the condition
variable attributes object.
Related Information
Routines: pthread_condattr_delete
pthread_cond_init
ΓòÉΓòÉΓòÉ 4.3.30. pthread_condattr_delete ΓòÉΓòÉΓòÉ
Purpose
Deletes a condition variable attributes object.
Format
#include <pthread.h>
int pthread_condattr_delete(
pthread_condattr_t *attr);
Parameters
attr Condition variable attributes object deleted.
Usage
The pthread_condattr_delete routine deletes a condition variable
attributes object. Call this routine when a condition variable
attributes object created by pthread_condattr_create is no longer
referenced.
This routine gives permission to reclaim storage for the condition
variable attributes object. Condition variables that are created
using this attributes object are not affected by the deletion of the
condition variable attributes object.
The results of calling this routine are unpredictable if the handle
specified by the attr parameter refers to an attributes object that
does not exist. Note that if the pthreads exception handling header
file pthread_exc.h is used instead of pthread.h, then a DCE exception
is raised.
Return Codes
If the routine fails, errno may be set to one of the following
values:
Error Description
0 Successful completion
-1 [EINVAL] The value specified by attr is invalid.
Related Information
Routines:
pthread_condattr_create
ΓòÉΓòÉΓòÉ 4.3.31. pthread_create ΓòÉΓòÉΓòÉ
Purpose
Creates a thread object and thread.
Format
#include <pthread.h>
int pthread_create(
pthread_t *thread,
pthread_attr_t attr,
pthread_startroutine_t start_routine,
pthread_addr_t arg);
Parameters
thread Handle to the thread object created.
attr Thread attributes object that defines the
characteristics of the thread being created. If you
specify pthread_attr_default, default attributes are
used.
start_routine Routine run as the new thread's start routine. If the
start routine is defined as having the IBM C/Set2
_optlink calling convention, then the application
module containing the pthread_create call must use
#define DCEOS2_THREAD_OPTLINK_LINKAGE prior to the
statement #include [pthread.h] or #include
[pthread_exc.h].
arg Address value copied and passed to the thread's start
routine.
Usage
The pthread_create routine creates a thread object and a thread. A
thread is a single, sequential flow of control within a program. It
is the active execution of a designated routine, including any nested
routine invocations. A thread object defines and controls the running
thread.
Calling this routine sets in motion the following actions:
o An internal thread object is created to describe the thread.
o The associated executable thread is created with attributes
specified by the attr parameter (or with default attributes if
pthread_attr_default is specified).
o The thread parameter receives the new thread.
o The start_routine routine is called when this routine
successfully completes.
The thread is created in the ready state and therefore might
immediately begin running the routine specified by the start_routine
parameter. The newly created thread can begin running before
pthread_create completes. This is true, if the new thread follows the
SCHED_HRR scheduling policy or has a priority higher than the
creating thread, or both. Otherwise, the new thread begins running at
its turn, which with sufficient processors might also be before
pthread_create returns.
The routine specified in start_routine is passed a copy of the arg
parameter. The value of the arg parameter is unspecified.
The thread object exists until the pthread_detach routine is called
or the thread terminates, whichever occurs last.
The synchronization between the caller of pthread_create and the
newly created thread is through the use of the pthread_join routine
(or any other mutexes or condition variables they agree to use).
A thread terminates when one of the following events occurs:
o The thread returns from its start routine.
o The thread exits (within a routine) as the result of calling the
pthread_exit routine.
o The thread is canceled.
The following actions are performed when a thread terminates:
o If the thread terminates by returning from its start routine or
calling pthread_exit, the return value is copied into the thread
object. If the start routine returns normally and the start
routine is a procedure that does not return a value, then the
result obtained by pthread_join is unpredictable. If the thread
has been cancelled, a return value of -1 is copied into the
thread object. The return value can be retrieved by other
threads by calling the pthread_join routine.
o A destructor for each thread-specific data point is removed from
the list of destructors for this thread and then is called.
This step destroys all the thread-specific data associated with
the current thread.
o Each cleanup handler that has been declared by
pthread_cleanup_push and not yet removed by pthread_cleanup_pop
is called. The most recently pushed handler is called first.
o A flag is set in the thread object indicating that the thread
has terminated. This flag must be set in order for callers of
pthread_join to return from the call.
o A broadcast is made so that all threads currently waiting in a
call to pthread_join can return from the call.
o The thread object is marked to indicate that it is no longer
needed by the thread itself. A check is made to determine if
the thread object is no longer needed by other threads, that is,
if pthread_detach has been called. If that routine is called,
then the thread object is deallocated.
Note that if the pthreads exception handling header file
pthread_exc.h is used instead of pthread.h, then a DCE exception is
raised.
Return Codes
Upon successful completion, this routine stores the identifier of the
created thread at threadand returns 0. Otherwise, a value of -1 is
returned and no thread is created, the contents of thread are
undefined, and errno may be set to one of the following values:
Error Description
-1 [EAGAIN] The system lacks the necessary resources to create
another thread.
-1 [ENOMEM] Insufficient memory exists to create the thread object.
This is not a temporary condition.
Related Information
Routines: pthread_attr_create
pthread_cancel
pthread_detach
pthread_exit
pthread_join
ΓòÉΓòÉΓòÉ 4.3.32. pthread_delay_np ΓòÉΓòÉΓòÉ
Purpose
Causes a thread to wait for a specified period of time before
continuing.
Format
#include <pthread.h>
int pthread_delay_np(
struct timespec *interval);
Parameters
interval Number of seconds and nanoseconds that the calling
thread waits before continuing execution. The value
specified must be greater than or equal to zero.
Usage
The pthread_delay_np routine causes a thread to delay execution for a
specified period of elapsed wall clock time. The period of time the
thread waits is at least as long as the number of seconds and
nanoseconds specified in the interval parameter.
Specifying an interval of 0 (zero) seconds and 0 (zero) nanoseconds
is allowed and can result in the thread giving up the processor or
delivering a pending cancel.
The struct timespec structure contains two fields, as follows:
tv_sec An integer number of seconds.
tv_nsec An integer number of nanoseconds.
Usage of this routine is not portable. Note that if the pthreads
exception handling header file pthread_exc.h is used instead of
pthread.h, then a DCE exception is raised.
Return Codes
If the routine fails, errno may be set to one of the following
values:
Error Description
0 Successful completion
-1 [EINVAL] The value specified by interval is invalid.
Related Information
Routines:
pthread_yield
ΓòÉΓòÉΓòÉ 4.3.33. pthread_detach ΓòÉΓòÉΓòÉ
Purpose
Marks a thread object for deletion.
Format
#include <pthread.h>
int pthread_detach(
pthread_t *thread);
Parameters
thread Thread object marked for deletion.
Usage
The pthread_detach routine indicates that storage for the specified
thread is reclaimed when the thread terminates. This includes
storage for the thread parameter's return value. If thread has not
terminated when this routine is called, this routine does not cause
it to terminate.
Call this routine when a thread object is no longer referenced.
Additionally, call this routine for every thread that is created to
ensure that storage for thread objects does not accumulate.
You cannot join with a thread after the thread has been detached.
The results of this routine are unpredictable if the value of thread
refers to a thread object that does not exist. Note that if the
pthreads exception handling header file pthread_exc.h is used instead
of pthread.h, then a DCE exception is raised.
Return Codes
If the routine fails, errno may be set to one of the following
values:
Error Description
0 Successful completion
-1 [EINVAL] The value specified by thread is invalid.
-1 [ERSCH] The value specified by thread does not refer to an
existing thread.
Related Information
Routines: pthread_cancel
pthread_create
pthread_exit
pthread_join
ΓòÉΓòÉΓòÉ 4.3.34. pthread_equal ΓòÉΓòÉΓòÉ
Purpose
Compares one thread identifier to another thread identifier.
Format
#include <pthread.h>
boolean32 pthread_equal(
pthread_t *thread1,
pthread_t *thread2);
Parameters
thread1 The first thread identifier to be compared.
thread2 The second thread identifier to be compared.
Usage
The pthread_equal routine compares one thread identifier to another
thread identifier. (This routine does not check whether the objects
that correspond to the identifiers currently exist.) If the
identifiers have values indicating that they designate the same
object, 1 (true) is returned. If the values do not designate the
same object, 0 (false) is returned.
This routine is implemented as a C macro.
Return Codes
Possible return values are as follows:
Error Description
0 Values of thread1 and thread2 do not designate the same
object.
1 Values of thread1 and thread2 designate the same
object.
Examples
equal = pthread_equal (thread1, thread2)
Related Information
Routine:
pthread_create
ΓòÉΓòÉΓòÉ 4.3.35. pthread_exit ΓòÉΓòÉΓòÉ
Purpose
Terminates the calling thread.
Format
#include <pthread.h>
void pthread_exit(
pthread_addr_t status);
Parameters
status Address value copied and returned to the caller of
pthread_join.
Usage
The pthread_exit routine terminates the calling thread and makes a
status value available to any thread that calls pthread_join and
specifies the terminating thread.
An implicit call to pthread_exit is issued when a thread returns from
the start routine that was used to create it. The routine's return
value serves as the thread's exit status. If the return value is -1,
an error exit is forced for the thread instead of a normal exit. The
process exits when the last running thread calls pthread_exit, with
an undefined exit status. Note that if the pthreads exception
handling header file pthread_exc.h is used instead of pthread.h, a
DCE exception is raised.
Restrictions
The pthread_exit routine does not work in the main (initial) thread
because DCE Threads relies on information at the base of thread
stacks; this information does not exist in the main thread.
Related Information
Routines: pthread_create
pthread_detach
pthread_join
ΓòÉΓòÉΓòÉ 4.3.36. pthread_get_expiration_np ΓòÉΓòÉΓòÉ
Purpose
Obtains a value representing a desired expiration time.
Format
#include <pthread.h>
int pthread_get_expiration_np(
struct timespec *delta,
struct timespec *abstime);
Parameters
delta Number of seconds and nanoseconds to add to the current
system time. The result is the time when a timed wait
expires.
abstime Value representing the expiration time.
Usage
The pthread_get_expiration_np routine adds a specified interval to
the current absolute system time and returns a new absolute time.
This new absolute time is used as the expiration time in a call to
pthread_cond_timedwait.
The struct timespec structure contains two fields:
tv_sec An integer number of seconds.
tv_nsec An integer number of nanoseconds.
Return Codes
If the routine fails, errno may be set to one of the following
values:
Error Description
-1 [EINVAL] The value specified by delta is not valid.
Related Information
Routines:
pthread_cond_timedwait
ΓòÉΓòÉΓòÉ 4.3.37. pthread_getprio ΓòÉΓòÉΓòÉ
Purpose
Obtains the current priority of a thread.
Format
#include <pthread.h>
int pthread_getprio(
pthread_t thread);
Parameters
thread Thread whose priority is obtained.
Usage
The pthread_getprio routine obtains the current priority of a thread.
The current priority is different from the initial priority of the
thread if the pthread_setprio routine is called.
The exact effect of different priority values depends upon the
scheduling policy assigned to the thread.
Return Codes
The current priority value of the thread specified in thread is
returned. See pthread_setprio for valid values.
If the routine fails, errno may be set to one of the following
values:
Error Description
-1 [EINVAL] The value specified by thread is not valid.
-1 [ESRCH] The value specified by thread does not refer to an
existing thread.
Related Information
Routines: pthread_attr_setprio
pthread_setprio
pthread_setscheduler
ΓòÉΓòÉΓòÉ 4.3.38. pthread_getscheduler ΓòÉΓòÉΓòÉ
Purpose
Obtains the current scheduling policy of a thread.
Format
#include <pthread.h>
int pthread_getscheduler(
pthread_t thread);
Parameters
thread Thread whose scheduling policy is obtained.
Usage
The pthread_getscheduler routine obtains the current scheduling
policy of a thread. The current scheduling policy of a thread is
different from the initial scheduling policy if the
pthread_setscheduler routine is called.
Return Codes
The current scheduling policy value of the thread specified in thread
is returned. See pthread_setscheduler for valid values.
If the routine fails, errno may be set to one of the following
values:
Error Description
-1 [EINVAL] The value specified by thread is not valid.
-1 [ESRCH] The value specified by thread does not refer to an
existing thread.
Related Information
Routines: pthread_attr_setsched
pthread_setscheduler
ΓòÉΓòÉΓòÉ 4.3.39. pthread_getspecific ΓòÉΓòÉΓòÉ
Purpose
Obtains the thread-specific data associated with the specified key.
Format
#include <pthread.h>
int pthread_getspecific(
pthread_key_t key,
pthread_addr_t *value);
Parameters
key Context key value that identifies the data value
obtained. This key value must be obtained from
pthread_keycreate.
value Address of the current thread-specific data value
associated with the specified key.
Usage
The pthread_getspecific routine obtains the thread-specific data
associated with the specified key for the current thread. Note that
if the pthreads exception handling header file pthread_exc.h is used
instead of pthread.h, a DCE exception is raised.
Return Codes
If the routine fails, errno may be set to one of the following
values:
Error Description
-1 [EINVAL] The key value is not valid.
Related Information
Routines: pthread_keycreate
pthread_setspecific
ΓòÉΓòÉΓòÉ 4.3.40. pthread_getunique_np ΓòÉΓòÉΓòÉ
Purpose
Obtains the sequence number associated with a thread.
Format
#include <pthread.h>
unsigned int pthread_getunique_np(
pthread_t *thread);
Parameters
thread Thread whose priority is obtained.
Usage
The pthread_getunique_np routine returns the sequence number
associated with the thread identifier passed to it. Note that if the
pthreads exception handling header file pthread_exc.h is used instead
of pthread.h, a DCE exception is raised.
Return Codes
The pthread_getunique_np routine returns the sequence number
associated with the thread identifier passed to it.
Related Information
Routines: pthread_create
pthread_self
ΓòÉΓòÉΓòÉ 4.3.41. pthread_join ΓòÉΓòÉΓòÉ
Purpose
Causes the calling thread to wait for the termination of a specified
thread.
Format
#include <pthread.h>
int pthread_join(
pthread_t thread,
pthread_addr_t *status);
Parameters
thread Thread whose termination is awaited by the caller of
this routine.
status Status value of the terminating thread when that thread
calls pthread_exit.
Usage
The pthread_join routine causes the calling thread to wait for the
termination of a specified thread. A call to this routine returns
after the specified thread has terminated.
Any number of threads can call this routine. All threads are
awakened when the specified thread terminates.
If the current thread calls this routine to join with itself, an
error is returned.
The results of this routine are unpredictable if the value for thread
refers to a thread object that no longer exists. Note that if the
pthreads exception handling header file pthread_exc.h is used instead
of pthread.h, then a DCE exception is raised.
Return Codes
If the routine fails, errno may be set to one of the following
values:
Error Description
-1 [EINVAL] The value specified by thread is not valid.
-1 [ESRCH] The value specified by thread does not refer to a
currently existing thread.
-1 [EDEADLK] A deadlock is detected.
Related Information
Routines: pthread_create
pthread_detach
pthread_exit
ΓòÉΓòÉΓòÉ 4.3.42. pthread_keycreate ΓòÉΓòÉΓòÉ
Purpose
Generates a unique thread-specific data key value.
Format
#include <pthread.h>
int pthread_keycreate(
pthread_key_t *key,
void (*destructor) (void *value));
Parameters
key Value of the new thread-specific data key.
destructor Procedure to be called to destroy a data value
associated with the created key when the thread
terminates.
Usage
The pthread_keycreate routine generates a unique thread-specific data
key value. This key value identifies a thread-specific data value,
which is an address of memory generated by the client containing
arbitrary data of any size.
Thread-specific data allow client software to associate information
with the current thread.
For example, thread-specific data can be used by a language run-time
library that needs to associate a language-specific thread-private
data structure with an individual thread. The thread-specific data
routines also provide a portable means of implementing the class of
storage called thread-private static, which is needed to support
parallel decomposition in the FORTRAN language.
This routine generates and returns a new key value. Each call to
this routine within a process returns a key value that is unique
within an application invocation. Calls to pthread_keycreate must
occur in initialization code guaranteed to run only once in each
process. The pthread_once routine provides a way of specifying such
code.
When multiple facilities share access to thread-specific data, the
facilities must agree on the key value that is associated with the
context. The key value must be created only once and needs to be
stored in a location known to each facility. (It may be desirable to
encapsulate the creation of a key, and the setting and getting of
context values for that key, within a special facility created for
that purpose.)
When a thread terminates, thread-specific data is automatically
destroyed. For each thread-specific datum currently associated with
the thread, the destructor routine associated with the key value of
that context is called. The order in which per-thread context
destructors are called at thread termination is undefined. Note that
if the pthreads exception handling header file pthread_exc.h is used
instead of pthread.h, then a DCE exception is raised.
Return Codes
If the routine fails, errno may be set to one of the following
values:
Error Description
-1 [EINVAL] The value specified by key is not valid.
-1 [EAGAIN] An attempt was made to allocate a key when the key name
space is exhausted. This is not a temporary condition.
-1 [ENOMEM] Insufficient memory exists to create the key.
Related Information
Routines: pthread_getspecific
pthread_setspecific
ΓòÉΓòÉΓòÉ 4.3.43. pthread_lock_global_np ΓòÉΓòÉΓòÉ
Purpose
Locks the global mutex.
Format
#include <pthread.h>
void pthread_lock_global_np( );
Usage
The pthread_lock_global_np routine locks the global mutex. If the
global mutex is currently held by another thread when a thread calls
this routine, the thread waits for the global mutex to become
available.
The thread that has locked the global mutex becomes its current owner
and remains the owner until the same thread has unlocked it. This
routine returns with the global mutex in the locked state and with
the current thread as the current owner of the global mutex.
Use the global mutex when calling a library package that is not
designed to run in a multithreaded environment. Assume that the
library routine is always non-compatible or nonreentrant, unless the
documentation for it specifically states that it is compatible with
multithreading.
The global mutex is one lock. Any code that calls any routine that
is not known to be reentrant uses the same lock. This prevents
dependencies among threads calling library routines and those
routines calling other routines, and so on.
The global mutex is a recursive mutex. A thread that has locked the
global mutex can relock it without deadlocking. (The locking thread
must call pthread_unlock_global_np as many times as it called this
routine to allow another thread to lock the global mutex.)
Usage of this routine is not portable.
Related Information
Routines: pthread_mutexattr_setkind_np
pthread_mutex_lock
pthread_mutex_unlock
pthread_unlock_global_np
ΓòÉΓòÉΓòÉ 4.3.44. pthread_mutex_destroy ΓòÉΓòÉΓòÉ
Purpose
Deletes a mutex.
Format
#include <pthread.h>
int pthread_mutex_destroy(
pthread_mutex_t *mutex);
Parameters
mutex Mutex to be deleted.
Usage
The pthread_mutex_destroy routine deletes a mutex and must be called
when a mutex object is no longer referenced. The effect of calling
this routine is to reclaim storage for the mutex object.
It is illegal to delete a mutex that has a current owner (in other
words, is locked).
The results of this routine are unpredictable if the mutex object
specified in the mutex parameter does not currently exist. Note that
if the pthreads exception handling header file pthread_exc.h is used
instead of pthread.h, then a DCE exception is raised.
Return Codes
If the function fails, errno may be set to one of the following
values:
Error Description
-1 [EBUSY] An attempt was made to destroy a mutex that is locked.
-1 [EINVAL] The value specified by mutex is not valid.
Related Information
Routines: pthread_mutex_init
pthread_mutex_lock
pthread_mutex_trylock
pthread_mutex_unlock
ΓòÉΓòÉΓòÉ 4.3.45. pthread_mutex_init ΓòÉΓòÉΓòÉ
Purpose
Creates a mutex.
Format
#include <pthread.h>
int pthread_mutex_init(
pthread_mutex_t *mutex,
pthread_mutexattr_t attr);
Parameters
mutex Mutex that is created.
attr Mutex attributes object that defines the
characteristics of the created mutex. If you specify
pthread_mutexattr_default, default attributes are used.
Usage
The pthread_mutex_init routine creates a mutex and initializes it to
the unlocked state.
If the thread that called this routine terminates, the created mutex
is not automatically deallocated, because it is considered shared
among multiple threads. Note that if the pthreads exception handling
header file pthread_exc.h is used instead of pthread.h, then a DCE
exception is raised.
Return Codes
If an error condition occurs, this routine returns -1, the mutex is
not initialized, the contents of mutex are undefined, and errno may
be set to one of the following values:
Error Description
-1 [EINVAL] The value specified by attr is not valid.
-1 [EAGAIN] The system lacks the necessary resources to initialize
another mutex.
-1 [ENOMEM] Insufficient memory exists to initialize the mutex.
Related Information
Routines:
pthread_mutexattr_create
pthread_mutexattr_getkind_np
pthread_mutexattr_setkind_np
pthread_mutex_lock
pthread_mutex_trylock
pthread_mutex_unlock
ΓòÉΓòÉΓòÉ 4.3.46. pthread_mutex_lock ΓòÉΓòÉΓòÉ
Purpose
Locks an unlocked mutex.
Format
#include <pthread.h>
int pthread_mutex_lock(
pthread_mutex_t *mutex);
Parameters
mutex Mutex that is locked.
Usage
The pthread_mutex_lock routine locks a mutex. If the mutex is locked
when a thread calls this routine, the thread waits for the mutex to
become available.
The thread that has locked a mutex becomes its current owner and
remains the owner until the same thread has unlocked it. This routine
returns with the mutex in the locked state and with the current
thread as the mutex's current owner.
If you specified a fast mutex in a call to
pthread_mutexattr_setkind_np, a deadlock can result if the current
owner of a mutex calls this routine in an attempt to lock the mutex a
second time. If you specified a recursive mutex in a call to
pthread_mutexattr_setkind_np, the current owner of a mutex can relock
the same mutex without blocking. If you specify a nonrecursive mutex
in a call to pthread_mutexattr_setkind_np, an error is returned and
the thread does not block if the current owner of a mutex calls this
routine in an attempt to lock the mutex a second time.
The preemption of a lower-priority thread that locks a mutex possibly
results in the indefinite blocking of higher-priority threads waiting
for the same mutex. The execution of the waiting, higher-priority
threads are blocked for as long as there is a sufficient number of
runable threads of any priority between the lower- and higher-
priority values. Priority inversion occurs when any resource is
shared between threads with different priorities. Note that if the
pthreads exception handling header file pthread_exc.h is used instead
of pthread.h, then a DCE exception is raised.
Return Codes
If the routine fails, errno may be set to one of the following
values:
Error Description
0 Successful completion
-1 [EINVAL] The value specified by mutex is not valid.
-1 [EDEADLK] A deadlock condition is detected.
Related Information
Routines: pthread_mutexattr_setkind_np
pthread_mutex_destroy
pthread_mutex_init
pthread_mutex_trylock
pthread_mutex_unlock
ΓòÉΓòÉΓòÉ 4.3.47. pthread_mutex_trylock ΓòÉΓòÉΓòÉ
Purpose
Locks a mutex.
Format
#include <pthread.h>
int pthread_mutex_trylock(
pthread_mutex_t *mutex);
Parameters
mutex Mutex that is locked.
Usage
The pthread_mutex_trylock routine locks a mutex. If the specified
mutex is locked when a thread calls this routine, the calling thread
does not wait for the mutex to become available.
When a thread calls this routine, an attempt is made to immediately
lock the mutex. If the mutex is successfully locked, 1 is returned
and the current thread is then the current owner of the mutex.
If the mutex is locked by another thread when this routine is called,
0 (zero) is returned and the thread does not wait to acquire the
lock. If a recursive mutex is owned by the current thread, 1 is
returned and the mutex is relocked. (To unlock a recursive mutex,
each call to pthread_mutex_trylock must be matched by a call to the
pthread_mutex_unlock routine.)
Return Codes
If the routine fails, errno may be set to one of the following
values:
Error Description
1 Successful completion
0 The mutex is locked; therefore, it was not acquired.
-1 [EINVAL] The value specified by mutex is not valid.
Related Information
Routines: pthread_mutexattr_setkind_np
pthread_mutex_destroy
pthread_mutex_init
pthread_mutex_lock
pthread_mutex_unlock
ΓòÉΓòÉΓòÉ 4.3.48. pthread_mutex_unlock ΓòÉΓòÉΓòÉ
Purpose
Unlocks a mutex.
Format
#include <pthread.h>
int pthread_mutex_unlock(
pthread_mutex_t *mutex);
Parameters
mutex Mutex that is unlocked.
Usage
The pthread_mutex_unlock routine unlocks a mutex. If no threads are
waiting for the mutex, the mutex unlocks with no current owner. If
one or more threads are waiting to lock the specified mutex, this
routine causes one thread to return from its call to
pthread_mutex_lock. The scheduling policy is used to determine the
thread that acquires the mutex. For the SCHED_HRR policy, a blocked
thread is chosen in priority order.
The results of calling this routine are unpredictable if the mutex
specified in mutex is unlocked. The results of calling this routine
are also unpredictable if the mutex specified in mutex is currently
owned by a thread other than the calling thread. Note that if the
pthreads exception handling header file pthread_exc.h is used instead
of pthread.h, then a DCE exception is raised.
Return Codes
If the routine fails, errno may be set to one of the following
values:
Error Description
0 Successful completion
-1 [EINVAL] The value specified by mutex is not valid.
Related Information
Routines:
pthread_mutexattr_setkind_np
pthread_mutex_destroy
pthread_mutex_init
pthread_mutex_lock
pthread_mutex_trylock
pthread_unlock_global_np
ΓòÉΓòÉΓòÉ 4.3.49. pthread_mutexattr_create ΓòÉΓòÉΓòÉ
Purpose
Creates a mutex attributes object.
Format
#include <pthread.h>
int pthread_mutexattr_create(
pthread_mutexattr_t *attr);
Parameters
attr Mutex attributes object that is created.
Usage
The pthread_mutexattr_create routine creates a mutex attributes
object used to specify the attributes of mutexes when they are
created. The mutex attributes object is initialized with the default
value for all of the attributes defined by a given implementation.
When a mutex attributes object is used to create a mutex, the values
of the individual attributes determine the characteristics of the new
object. Attributes objects act like additional parameters to object
creation. Changing individual attributes does not affect any objects
that were previously created using the attributes object. Note that
if the pthreads exception handling header file pthread_exc.h is used
instead of pthread.h, then a DCE exception is raised.
Return Codes
The created mutex attributes object is returned to the attr
parameter.
If the routine fails, errno may be set to one of the following
values:
Error Description
0 Successful completion
-1 [EINVAL] The value specified by attr is not valid.
-1 [ENOMEM] Insufficient memory exists to create the mutex
attributes object.
Related Information
Routines:
pthread_create
pthread_mutexattr_delete
pthread_mutexattr_getkind_np
pthread_mutexattr_setkind_np
pthread_mutex_init
ΓòÉΓòÉΓòÉ 4.3.50. pthread_mutexattr_delete ΓòÉΓòÉΓòÉ
Purpose
Deletes a mutex attributes object.
Format
#include <pthread.h>
int pthread_mutexattr_delete(
pthread_mutexattr_t *attr);
Parameters
attr Mutex attributes object that is deleted.
Usage
The pthread_mutexattr_delete routine deletes a mutex attributes
object. Call this routine when a mutex attributes object is no
longer referenced by the pthread_mutexattr_create routine.
This routine gives permission to reclaim storage for the mutex
attributes object. Mutexes that were created using this attributes
object are not affected by the deletion of the mutex attributes
object.
The results of calling this routine are unpredictable if the
attributes object specified in the attr parameter does not exist.
Note that if the pthreads exception handling header file
pthread_exc.h is used instead of pthread.h, then a DCE exception is
raised.
Return Codes
If the routine fails, errno may be set to one of the following
values:
Error Description
0 Successful completion
-1 [EINVAL] The value specified by attr is not valid.
Related Information
Routines:
pthread_mutexattr_create
ΓòÉΓòÉΓòÉ 4.3.51. pthread_mutexattr_getkind_np ΓòÉΓòÉΓòÉ
Purpose
Obtains the mutex type attribute used when a mutex is created.
Format
#include <pthread.h>
int pthread_mutexattr_getkind_np(
pthread_mutexattr_t attr);
Parameters
attr Mutex attributes object whose mutex type is obtained.
Usage
The pthread_mutexattr_getkind_np routine obtains the mutex type
attribute that is used when a mutex is created. See
pthread_mutexattr_setkind_np for information about mutex type
attributes.
This routine is not portable.
Return Codes
If the routine fails, errno may be set to one of the following
values:
Error Description
Mutex type attribute Successful completion
-1 [EINVAL] The value specified by attr is not valid.
Related Information
Routines:
pthread_mutexattr_create
pthread_mutexattr_setkind_np
pthread_mutex_init
ΓòÉΓòÉΓòÉ 4.3.52. pthread_mutexattr_setkind_np ΓòÉΓòÉΓòÉ
Purpose
Specifies the mutex type attribute that is used when a mutex is
created.
Format
#include <pthread.h>
int pthread_mutexattr_setkind_np(
pthread_mutexattr_t *attr,
int kind);
Parameters
attr Mutex attributes object modified.
kind New value for the mutex type attribute. The kind
parameter specifies the type of mutex that is created.
Valid values are:
o MUTEX_FAST_NP (the default)
o MUTEX_RECURSIVE_NP
o MUTEX_NONRECURSIVE_NP
Usage
This routine sets the mutex type attribute that is used when a mutex
is created.
A fast mutex is locked and unlocked in the fastest manner possible. A
fast mutex can only be locked (obtained) once. All subsequent calls
to pthread_mutex_lock cause the calling thread to block until the
mutex is freed by the thread that owns it. If the thread that owns
the mutex attempts to lock it again, the thread waits for itself to
release the mutex (causing a deadlock).
A recursive mutex can be locked more than once by the same thread
without causing that thread to deadlock. In other words, a single
thread can make consecutive calls to pthread_mutex_lock without
blocking. The thread must then call pthread_mutex_unlock the same
number of times as it called pthread_mutex_lock before another thread
can lock the mutex.
A nonrecursive mutex is locked only once by a thread, like a fast
mutex. If the thread tries to lock the mutex again without first
unlocking it, the thread receives an error. Thus, nonrecursive
mutexes are more informative than fast mutexes because fast mutexes
block in such a case, leaving it up to you to determine why the
thread no longer runs. Also, if someone other than the owner tries
to unlock a nonrecursive mutex, an error is returned.
Never use a recursive mutex with condition variables because the
implicit unlock performed for a pthread_cond_wait or
pthread_cond_timedwait might not actually release the mutex. In that
case, no other thread can satisfy the condition of the predicate.
This routine is not portable. Note that if the pthreads exception
handling header file pthread_exc.h is used instead of pthread.h, then
a DCE exception is raised.
Return Codes
If the routine fails, errno may be set to one of the following
values:
Error Description
0 Successful completion
-1 [EINVAL] The value specified by attr or kind is not valid.
-1 [EPERM] The caller does not have the appropriate privileges.
-1 [ERANGE] One or more parameters supplied have an not valid
value.
Related Information
Routines:
pthread_mutexattr_create
pthread_mutexattr_getkind_np
pthread_mutex_init
ΓòÉΓòÉΓòÉ 4.3.53. pthread_once ΓòÉΓòÉΓòÉ
Purpose
Calls an initialization routine run by one thread, a single time.
Format
#include <pthread.h>
int pthread_once(
pthread_once_t *once_block,
pthread_initroutine_t init_routine);
Parameters
once_block Address of a record that defines the one-time
initialization code. Each one-time initialization
routine must have its own unique pthread_once_t data
structure.
init_routine Address of a procedure that performs the
initialization. This routine is called only once,
regardless of the number of times it and its associated
once_block are passed to pthread_once.
Usage
The pthread_once routine calls an initialization routine run by one
thread, a single time. This routine allows you to create your own
initialization code that is guaranteed to be run only once, even if
called simultaneously by multiple threads or multiple times in the
same thread.
For example, a mutex or a thread-specific data key must be created
exactly once. Calling pthread_once prevents the code that creates a
mutex or thread-specific data from being called by multiple threads.
Without this routine, the execution must be serialized so that only
one thread performs the initialization. Other threads that reach the
same point in the code are delayed until the first thread is
finished.
This routine initializes the control record if it has not been
initialized and then determines if the client one-time initialization
routine has run once. If it has not run, this routine calls the
initialization routine specified in init_routine. If the client
one-time initialization code has run once, this routine returns.
The pthread_once_t data structure is a record that allows client
initialization operations to guarantee mutual exclusion of access to
the initialization routine, and that each initialization routine is
run exactly once.
The client code must declare a variable of type pthread_once_t to use
the client initialization operations. This variable must be
initialized using the pthread_once_init macro, as follows:
static pthread_once_t myOnceBlock = pthread_once_init;
Note that if the pthreads exception handling header file
pthread_exc.h is used instead of pthread.h, then a DCE exception is
raised.
Return Codes
If the routine fails, errno may be set to one of the following
values:
Error Description
-1 [EINVAL] The value specified by a parameter is not valid.
ΓòÉΓòÉΓòÉ 4.3.54. pthread_pseudo_thread_base_end ΓòÉΓòÉΓòÉ
Purpose
A macro that ends a pseudo-pthread wrapper, which allows OS/2 threads
to function within a DCE threads environment and use DCE threads
routines.
Format
#include <pthread.h>
void pthread_pseudo_thread_base_end( );
Usage
The pthread_pseudo_thread_base_end routine allows threads that were
created in an OS/2 environment to use DCE pthread libraries and
routines. This routine must be used with the
pthread_pseudo_thread_base_start routine to bracket code that uses
the DCE pthread environment. These two routines, called a
pseudo-pthread wrapper, are written as macros that are intended
primarily for use in existing OS/2 threads libraries to enable OS/2
threads applications to use DCE routines, which require a thread to
be of pthread type. This wrapper is not intended to be used by the
applications directly; you can write a new application to use pthread
routines directly, without using the wrapper.
The pseudo-pthread wrapper has some limits:
o You can only put one wrapper in the same routine
o There must be no returns from the code within the wrapper
because returning from within the code bypasses the
pthread_pseudo_thread_base_end routine.
o For maximum performance, the pair of macros should only be used
once. Do not locate them within a loop or other structure that
calls these routines repeatedly.
o You cannot nest these macros within the same routine. However,
the pseudo-thread wrapper supports recursion; code within the
wrapper can call another routine that also uses the wrapper.
When an OS/2 thread calls the library routine that contains the
pseudo-pthread wrapper, that thread temporarily becomes a DCE pthread
that can use the pthread libraries and routines. If the thread that
calls the library routine is already a pthread, the wrapper has no
effect.
Examples
The following is an example, in pseudocode, of a library routine with
a pseudo-pthread wrapper:
#include <pthread.h>
user_written_library_function
{
pthread_pseudo_thread_base_start( );
.
.
.
/*
existing code using the DCE pthread library
*/
.
.
.
pthread_pseudo_thread_base_end( );
}
Related Information
Routines:
pthread_pseudo_thread_base_start
ΓòÉΓòÉΓòÉ 4.3.55. pthread_pseudo_thread_base_start ΓòÉΓòÉΓòÉ
Purpose
A macro that starts a pseudo-pthread wrapper that allows OS/2 threads
to function within a DCE threads environment and use DCE pthread
routines.
Format
#include <pthread.h>
void pthread_pseudo_thread_base_start( );
Usage
The pthread_pseudo_thread_base_start routine allows threads that were
created in an OS/2 environment to use DCE pthread libraries and
routines. This routine must be used with the
pthread_pseudo_thread_base_end routine to bracket code that uses the
DCE pthread environment. These two routines, called a pseudo-pthread
wrapper, are written as macros that are intended primarily for use in
existing OS/2 threads libraries to enable OS/2 threads applications
to use DCE routines, which require a thread to be of pthread type.
This wrapper is not intended to be used by the applications directly;
you can write a new application to use pthread routines directly,
without using the wrapper.
The pseudo-pthread wrapper has some limits:
o You can only put one wrapper in the same routine
o There must be no returns from the code within the wrapper
because returning from within the code bypasses the
pthread_pseudo_thread_base_end routine.
o For maximum performance, the pair of macros should only be used
once. Do not locate them within a loop or other structure that
calls these routines repeatedly.
o You cannot nest these macros within the same routine. However,
the pseudo-thread wrapper supports recursion; code within the
wrapper can call another routine that also uses the wrapper.
When an OS/2 thread calls the library routine that contains the
pseudo-pthread wrapper, that thread temporarily becomes a DCE pthread
that can use the pthread libraries and routines. If the thread that
calls the library routine is already a pthread, the wrapper has no
effect.
Examples
The following is an example, in pseudocode, of a library routine with
a pseudo-pthread wrapper:
#include <pthread.h>
user_written_library_function
{
pthread_pseudo_thread_base_start( );
.
.
.
/*
existing code using the DCE pthread library
*/
.
.
.
pthread_pseudo_thread_base_end( );
}
Related Information
Routines:
pthread_pseudo_thread_base_end
ΓòÉΓòÉΓòÉ 4.3.56. pthread_self ΓòÉΓòÉΓòÉ
Purpose
Obtains the identifier of the current thread.
Format
#include <pthread.h>
pthread_t pthread_self( );
Usage
The pthread_self routine allows a thread to obtain its own
identifier. For example, this identifier allows a thread to set its
own priority.
This value becomes meaningless when the thread object is deleted -
that is, when the thread terminates its execution and pthread_detach
is called.
Return Codes
Returns the identifier of the calling thread to pthread_t.
Related Information
Routines:
pthread_create
pthread_setprio
pthread_setscheduler
ΓòÉΓòÉΓòÉ 4.3.57. pthread_setasynccancel ΓòÉΓòÉΓòÉ
Purpose
Enables or disables the current thread's asynchronous cancelability.
Format
#include <pthread.h>
int pthread_setasynccancel(
int state);
Parameters
state State of asynchronous cancelability set for the calling
thread. On return, this parameter receives the prior
state of asynchronous cancelability. Valid values are:
CANCEL_ON Asynchronous cancelability is
enabled.
CANCEL_OFF Asynchronous cancelability is
disabled.
Usage
The pthread_setasynccancel routine enables or disables the current
thread's asynchronous cancelability and returns the previous
cancelability state to the state parameter.
When general cancelability is set to CANCEL_OFF, a cancel cannot be
delivered to the thread, even if a cancelable routine is called or
asynchronous cancelability is enabled. When general cancelability is
set to CANCEL_ON, cancelability depends on the state of the thread's
asynchronous cancelability.
When general cancelability is set to CANCEL_ON and asynchronous
cancelability is set to CANCEL_OFF, the thread can only receive a
cancel at specific cancelation points (for example, condition waits,
thread joins, and calls to pthread_testcancel). If both general
cancelability and asynchronous cancelability are set to CANCEL_ON,
the thread can be canceled at any point in its execution.
When a thread is created, the default asynchronous cancelability
state is CANCEL_OFF.
If you call this routine to enable asynchronous cancels, call it in a
region of code where asynchronous delivery of cancels is disabled by
a previous call to this routine. Do not call threads routines in
regions of code where asynchronous delivery of cancels is enabled.
The previous state of asynchronous delivery can be restored later by
another call to this routine.
Return Codes
On successful completion, the previous state of asynchronous
cancelability is returned. If the routine fails, -1 is returned.
Following are the possible return values and the possible
corresponding values (if any) for errno:
Error Description
CANCEL_ON Asynchronous cancelability was on.
CANCEL_OFF Asynchronous cancelability was off.
-1 [EINVAL] The specified state is not CANCEL_ON or CANCEL_OFF.
Related Information
Routines:
pthread_cancel
pthread_setcancel
pthread_testcancel
ΓòÉΓòÉΓòÉ 4.3.58. pthread_setcancel ΓòÉΓòÉΓòÉ
Purpose
Enables or disables the general cancelability of the current thread.
Format
#include <pthread.h>
int pthread_setcancel(
int state);
Parameters
state State of general cancelability set for the calling
thread. On return, it receives the prior state of
general cancelability. Valid values are:
CANCEL_ON General cancelability is enabled.
CANCEL_OFF General cancelability is disabled.
Usage
The pthread_setcancel routine enables or disables the general
cancelability of the current thread and returns the previous
cancelability state to the state parameter.
When general cancelability is set to CANCEL_OFF, a cancel cannot be
delivered to the thread, even if a cancelable routine is called or
asynchronous cancelability is enabled.
When a thread is created, the default general cancelability state is
CANCEL_ON.
Possible Dangers of Disabling Cancelability
The most important use of cancels is to ensure that indefinite wait
operations are terminated. For example, a thread waiting for some
network connection, which may take days to respond (or may never
respond), is normally made cancelable.
However, when cancelability is disabled, no routine can be canceled.
Waits must be completed normally before a cancel can be delivered.
As a result, the program stops working and the user is unable to
cancel the operation.
When disabling cancelability, be sure that no long waits can occur or
that it is necessary for other reasons to defer cancels around that
particular region of code.
Return Codes
On successful completion, the previous state of general cancelability
is returned. If the routine fails, -1 is returned. Following are
the possible return values and the possible corresponding values (if
any) for errno:
Error Description
CANCEL_ON General cancelability was on.
CANCEL_OFF General cancelability was off.
-1 [EINVAL] The specified state is not CANCEL_ON or CANCEL_OFF.
Related Information
Routines:
pthread_cancel
pthread_setasynccancel
pthread_testcancel
ΓòÉΓòÉΓòÉ 4.3.59. pthread_setprio ΓòÉΓòÉΓòÉ
Purpose
Changes the current priority of a thread.
Format
#include <pthread.h>
int pthread_setprio(
pthread_t thread,
int priority);
Parameters
thread Thread whose priority is changed.
priority New priority value of the thread specified in thread.
The priority value is dependent on scheduling policy.
Valid values fall within the following range:
PRI_HRR_MIN <= priority <= PRI_HRR_MAX
If you create a new thread without specifying a thread attributes
object that contains a changed priority attribute, the default
priority of the newly created thread is PRI_HRR_MIN.
When you call this routine to specify a minimum or maximum priority,
use the appropriate symbol - for example, PRI_HRR_MIN or PRI_HRR_MAX.
To specify a value between the minimum and maximum, use an
appropriate arithmetic expression. For example, to set a priority
midway between the minimum and maximum, specify the following concept
using your programming language's syntax:
pri_hrr_mid = (PRI_HRR_MIN + PRI_HRR_MAX + 1)/2
If your expression results in a value outside the range of minimum to
maximum, an error results when you use it.
Usage
The pthread_setprio routine changes the current priority of a thread.
A thread can change its own priority using the identifier returned by
pthread_self.
Changing the priority of a thread can cause it to start running or be
preempted by another thread. The effect of setting different priority
values depends on the scheduling priority assigned to the thread. The
initial scheduling priority is set by calling the
pthread_attr_setprio routine.
Note that pthread_attr_setprio sets the priority attribute that is
used to establish the priority of a new thread when it is created.
However, pthread_setprio changes the priority of an existing thread.
Note: Setting and changing the priority of a thread can only be done
from root.
Return Codes
If successful, this routine returns the previous priority. If the
routine fails, errno may be set to one of the following values:
Error Description
-1 [EINVAL] The value specified by thread is invalid.
-1 [ESRCH] The value specified by thread does not refer to an
existing thread.
-1 [EPERM] The caller does not have the appropriate privileges to
set the priority of the specified thread.
Related Information
Routines:
pthread_attr_setprio
pthread_attr_setsched
pthread_create
pthread_self
pthread_setscheduler
ΓòÉΓòÉΓòÉ 4.3.60. pthread_setscheduler ΓòÉΓòÉΓòÉ
Purpose
Changes the current scheduling policy and priority of a thread.
Format
#include <pthread.h>
int pthread_setscheduler(
pthread_t thread,
int scheduler,
int priority);
Parameters
thread Thread whose scheduling policy is to be changed.
scheduler New scheduling policy value for the thread specified in
thread. Valid values are as follows:
SCHED_HRR (Hierarchical Round Robin) Each
thread has a priority associated with
it. threads of a higher priority are
given access to the CPU before
threads of lower priority. If a
thread with a higher priority than
the currently running thread becomes
ready to run, the current thread is
stopped immediately. Threads of the
same priority are given time-slices
in a round robin manner.
priority New priority value of the thread specified in thread.
The priority attribute is dependent upon scheduling
policy. Valid values fall within the following range:
PRI_HRR_MIN <= priority <= PRI_HRR_MAX
If you create a new thread without specifying a thread attributes
object that contains a changed priority attribute, the default
priority of the newly created thread is PRI_HRR_MIN.
When you call this routine to specify a minimum or maximum priority,
use the appropriate symbol, for example, PRI_HRR_MIN or PRI_HRR_MAX.
To specify a value between the minimum and maximum, use an
appropriate arithmetic expression. For example, to set a priority
mid-way between the minimum and maximum, specify the following
concept using your programming language's syntax:
pri_hrr_mid = (PRI_HRR_MIN + PRI_HRR_MAX)/2
If your expression results in a value outside the range of minimum to
maximum, an error results when you use it.
Usage
The pthread_setscheduler routine changes the current scheduling
policy and priority of a thread. Call this routine to change both the
priority and scheduling policy of a thread at the same time. To
change only the priority, call the pthread_setprio routine.
A thread changes its own scheduling policy and priority by using the
identifier returned by pthread_self. Changing the scheduling policy
or priority, or both, of a thread can cause it to start running or to
be pre-empted by another thread.
This routine is different from pthread_attr_setprio and
pthread_attr_setsched because those routines set the priority and
scheduling policy attributes that are used to establish the priority
and scheduling policy of a new thread when it is created. This
routine, however, changes the priority and scheduling policy of an
existing thread.
Note: Setting and changing the scheduling policy or priority of a
thread can only be done from root.
Return Codes
If successful, the previous scheduling policy value is returned. If
the routine fails, errno may be set to one of the following values:
Error Description
Previous policy Successful completion
-1 [EINVAL] The value specified by thread is invalid.
-1 [ESRCH] The value specified by thread does not refer to an
existing thread.
-1 [EPERM] The caller does not have the appropriate privileges to
set the priority of the specified thread.
Related Information
Routines:
pthread_attr_setprio
pthread_attr_setsched
pthread_create
pthread_self
pthread_setprio
ΓòÉΓòÉΓòÉ 4.3.61. pthread_setspecific ΓòÉΓòÉΓòÉ
Purpose
Sets the thread-specific data associated with the specified key for
the current thread.
Format
#include <pthread.h>
int pthread_setspecific(
pthread_key_t key,
pthread_attr_t value);
Parameters
key Context key value that uniquely identifies the context
value specified in value. This key value must have
been obtained from pthread_keycreate.
value Address containing data to be associated with the
specified key for the current thread; this is the
thread-specific data.
Usage
The pthread_setspecific routine sets the thread-specific data
associated with the specified key for the current thread. If a value
has already been defined for the key in this thread, the new value is
substituted for it.
Different threads can bind different values to the same key. These
values are typically pointers to blocks of dynamically allocated
memory that are reserved for use by the calling thread. Note that if
the pthreads exception handling header file pthread_exc.h is used
instead of pthread.h, then a DCE exception is raised.
Return Codes
If the routine fails, -1 is returned and errno may be set to one of
the following values:
Error Description
0 Successful completion
-1 [EINVAL] The key value is invalid.
Related Information
Routines:
pthread_getspecific
pthread_keycreate
ΓòÉΓòÉΓòÉ 4.3.62. pthread_signal_to_cancel_np ΓòÉΓòÉΓòÉ
Purpose
Cancels the specified thread.
Format
#include <pthread.h>
int pthread_signal_to_cancel_np(
sigset_t *sigset,
pthread_t *thread);
Parameters
sigset Signal mask containing a list of signals that, when
received by the process, cancels the specified thread.
thread Thread canceled if a valid signal is received by the
process.
Usage
The pthread_signal_to_cancel_np routine requests that the specified
thread be canceled if one of the signals specified in the signal mask
is received by the process. The set of legal signals is the same as
that for the sigwait service. The sigset parameter is not validated.
If it is invalid, this routine will return successfully but neither
the specified thread nor the previously specified thread will be
canceled if a signal occurs.
Note that the address of the specified thread is saved in a
per-process global variable. Therefore, any subsequent call to this
routine by your application or any library routine supersedes the
thread specified in the previous call, and that thread is not to be
canceled if one of the signals specified for it is delivered to the
process. In other words, be careful when you call this routine; if
another thread calls it after you do, the expected result of this
routine does not occur.
Return Codes
If the routine fails, errno may be set to one of the following
values:
0 Successful completion.
-1 [EINVAL] The value specified by sigset or thread is invalid.
Related Information
Routines:
pthread_cancel
sigwait
ΓòÉΓòÉΓòÉ 4.3.63. pthread_testcancel ΓòÉΓòÉΓòÉ
Purpose
Requests delivery of a pending cancel to the current thread.
Format
#include <pthread.h>
void pthread_testcancel( );
Usage
The pthread_testcancel routine requests delivery of a pending cancel
to the current thread. The cancel is delivered only if a cancel is
pending for the current thread and general cancel delivery is not
currently disabled. (A thread disables delivery of cancels to itself
by calling pthread_setcancel.)
This routine, when called within very long loops, ensures that a
pending cancel is noticed within a reasonable amount of time.
Related Information
Routines:
pthread_cancel
pthread_setasynccancel
pthread_setcancel
ΓòÉΓòÉΓòÉ 4.3.64. pthread_unlock_global_np ΓòÉΓòÉΓòÉ
Purpose
Unlocks a global mutex.
Format
#include <pthread.h>
void pthread_unlock_global_np( );
Usage
The pthread_unlock_global_np routine unlocks the global mutex when
each call to pthread_lock_global_np is matched by a call to this
routine. For example, if you called pthread_lock_global_np three
times, pthread_unlock_global_np unlocks the global mutex when you
call it the third time. If no threads are waiting for the global
mutex, it becomes unlocked with no current owner. If one or more
threads are waiting to lock the global mutex, one thread returns from
its call to pthread_lock_global_np. The scheduling policy is used to
determine which thread acquires the global mutex. For the policy
SCHED_HRR, a blocked thread is chosen in priority order.
The results of calling this routine are unpredictable if the global
mutex is already unlocked. The results of calling this routine are
also unpredictable if the global mutex is owned by a thread other
than the calling thread.
This routine is not portable.
Related Information
Routines:
pthread_lock_global_np
pthread_mutexattr_setkind_np
pthread_mutex_lock
pthread_mutex_unlock
ΓòÉΓòÉΓòÉ 4.3.65. pthread_yield ΓòÉΓòÉΓòÉ
Purpose
Notifies the scheduler that the current thread is willing to release
its processor to other threads of the same or higher priority.
Format
#include <pthread.h>
void pthread_yield( );
Usage
The pthread_yield routine notifies the scheduler that the current
thread is willing to release its processor to other threads of the
same priority. (A thread releases its processor to a thread of a
higher priority without calling this routine.)
If the current thread's scheduling policy (as specified in a call to
pthread_attr_setsched or pthread_setscheduler) is SCHED_HRR, this
routine yields the processor to other threads of the same or a higher
priority. If no threads of the same or higher priority are ready to
run, the thread continues.
This routine allows knowledge of the details of an application to be
used to increase fairness. It increases fairness of access to the
processor by removing the current thread from the processor. It also
increases fairness of access to shared resources by removing the
current thread from the processor as soon as it is finished with the
resource.
Use pthread_yield carefully because misuse causes unnecessary context
switching, which increases overhead without increasing fairness. For
example, it is counter-productive for a thread to yield while it has
a needed resource locked.
Related Information
Routines:
pthread_attr_setsched
pthread_setscheduler
ΓòÉΓòÉΓòÉ 4.3.66. sigwait ΓòÉΓòÉΓòÉ
Purpose
Suspends a calling thread.
Library
Threads Library (libpthreads.a)
Format
#include <signal.h>
int sigwait(
sigset *set);
Parameters
set Specifies the set of signals to wait for.
Usage
The sigwait routine suspends the calling thread until at least one of
the signals in the set parameter is in the threads set of pending
signals. When this happens, one of those signals is atomically chosen
and removed from the set of pending signals and that signal number is
returned.
The effect is unspecified if any signals in the set parameter are not
blocked when the sigwait routine is called.
The set parameter is created using the set manipulation routines
sigemptyset, sigfillset, sigaddset, and sigdelset.
Return Codes
Upon successful completion, the signal number of the pending signal
is returned. Otherwise, a value of -1 is returned, and errno is set
to indicate the error.
If the following condition occurs, the sigwait routine sets errno to
the corresponding value:
-1 [EINVAL] The value specified by set contains an invalid or
unsupported signal number.
Prerequisite Information
Subroutines Overview in AIX Version 3.2 General Programming Concepts.
ΓòÉΓòÉΓòÉ 5. The DCE Remote Procedure Call API ΓòÉΓòÉΓòÉ
This introduction gives general information about the DCE RPC Application
Programming Interface (API) and an overview of the different parts of the DCE
RPC API runtime. The following topics are covered in this introduction:
o IDL-to-C Mappings
o Management Commands for Programmers
o Overview of DCE RPC Runtime Services
o RPC Environment Variables
o RPC Data Types and Structures
o Permissions Required for RPC
o Frequently Used RPC Routine Parameters
o RPC Related Information
ΓòÉΓòÉΓòÉ 5.1. IDL-to-C Mappings ΓòÉΓòÉΓòÉ
The Interface Definition Language (IDL) compiler converts an interface
definition into output files. The DCE for OS/2 Warp: Administration Command
Reference contains a summary of the idl command, which runs the IDL compiler.
Additional information about the IDL compiler appears in the following table,
which shows the IDL base types and the IDL-to-C mappings.
The following table lists the IDL base data type specifiers. Where applicable,
the table shows the size of the corresponding transmittable type and the type
macro emitted by the IDL compiler for resulting declarations.
ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
Γöé Table 2. Base Data Type Specifiers Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé SPECIFIER Γöé Γöé Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ Γöé TYPE MACRO Γöé
Γöé (SIGN) Γöé (SIZE) Γöé (TYPE) Γöé SIZE Γöé EMITTED BY IDL Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé Γöé small Γöé int Γöé 8 bits Γöé idl_small_int Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé Γöé short Γöé int Γöé 16 bits Γöé idl_short_int Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé Γöé long Γöé int Γöé 32 bits Γöé idl_long_int Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé Γöé hyper Γöé int Γöé 64 bits Γöé idl_hyper_int Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé unsigned Γöé small Γöé int Γöé 8 bits Γöé idl_usmall_int Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé unsigned Γöé short Γöé int Γöé 16 bits Γöé idl_ushort_int Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé unsigned Γöé long Γöé int Γöé 32 bits Γöé idl_ulong_int Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé unsigned Γöé hyper Γöé int Γöé 64 bits Γöé idl_uhyper_int Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé Γöé Γöé float Γöé 32 bits Γöé idl_short_float Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé Γöé Γöé double Γöé 64 bits Γöé idl_long_float Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé Γöé Γöé char Γöé 8 bits Γöé idl_char Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé Γöé Γöé boolean Γöé 8 bits Γöé idl_boolean Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé Γöé Γöé byte Γöé 8 bits Γöé idl_byte Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé Γöé Γöé void Γöé ΓöÇΓöÇ Γöé idl_void_p_t Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé Γöé Γöé handle_t Γöé ΓöÇΓöÇ Γöé ΓöÇΓöÇ Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
Note that you can use the idl_ macros in the code you write for an application
to ensure that your type declarations are consistent with those in the stubs,
even when the application is ported to another platform. The idl_ macros are
especially useful when passing constant values to RPC calls. For maximum
portability, all constants passed to RPC calls declared in your network
interfaces should be cast to the appropriate type because the size of integer
constants (like the size of the int data type) is unspecified in the C
language.
The idl_ macros are defined in dce/idlbase.h, which is included by header files
that the IDL compiler generates.
ΓòÉΓòÉΓòÉ 5.2. Management Commands for Programmers ΓòÉΓòÉΓòÉ
In addition to the idl command for programmers, DCE RPC provides two management
commands for the RPC control program and the DCE Host daemon, as follows:
o The rpccp command accesses RPCCP, the RPC control program. This program
provides a set of commands for accessing the RPC Name Service Interface
(NSI) operations. RPCCP also supports the display of the elements of the
local endpoint map and the removal of elements from it.
You can manage the Name Service Interface with RPCCP commands or with DCE
RPC runtime routines. For example, suppose you want to obtain a list of
the members of a group. You can give the show group command to RPCCP or
you can write an application program that calls the following DCE RPC
runtime routines:
rpc_ns_group_mbr_inq_begin
rpc_ns_group_mbr_inq_next
rpc_ns_group_mbr_inq_done
o The dced command starts the DCE Host daemon. The daemon maintains the
local endpoint map for RPC servers and looks up endpoints for RPC
clients.
See the DCE for OS/2 Warp: Administration Command Reference for more
information about these two management commands.
ΓòÉΓòÉΓòÉ 5.3. Overview of DCE RPC Runtime Services ΓòÉΓòÉΓòÉ
The RPC runtime services consist of RPC routines that perform a variety of
operations.
Note: The RPC API is thread safe and synchronous cancel safe (in the context
of POSIX threads). However, the RPC API is not asynchronous cancel safe.
For more information about threads and their cancellation, see the DCE
for OS/2 Warp: Application Development Guide - Core Components.
The rest of this overview consists of the following items:
RPC Routine Abbreviations An explanation of abbreviations in the names of the
RPC runtime routines
RPC Runtime Routines An alphabetical list of DCE RPC runtime routines. With
each routine name is its description and the type of application
program that most likely calls the routine.
ΓòÉΓòÉΓòÉ 5.3.1. RPC Routine Abbreviations ΓòÉΓòÉΓòÉ
An alphabetical list of abbreviations in the names of the nonstub support
routines follows. The list can help you remember the names more easily. For
example, consider the routine name rpc_mgmt_ep_elt_inq_begin. Use the next list
to expand the name to "RPC management endpoint element inquiry begin," which
summarizes the description "Creates an inquiry context for viewing the elements
in a local or remote endpoint map."
auth authentication, authorization
com communication
cs character/code set interoperability
dce distributed computing environment
dflt default
elt element
ep endpoint
exp expiration
fn function
id identifier
idl_es IDL encoding services
if interface
inq inquiry
mbr member
mgmt management
ns name service
protseq protocol sequence
rgy DCE character and code set registry
rpc remote procedure call
stats statistics.
ΓòÉΓòÉΓòÉ 5.3.2. RPC Runtime Routines ΓòÉΓòÉΓòÉ
The following is an alphabetical list of the RPC routines. With each routine
name is its description and the type of application program that most likely
calls the routine.
cs_byte_from_netcs Converts international character data from a
network code set to a local code set (client,
server).
cs_byte_local_size Calculates the necessary buffer size for code
set conversion from a network code set to a
local code set (client, server).
cs_byte_net_size Calculates the necessary buffer size for code
set conversion from a local code set to a
network code set (client, server).
cs_byte_to_netcs Converts international character data from a
local code set to a network code set (client,
server).
dce_cs_loc_to_rgy Maps a local name for a code set to a code set
value in the code set registry (client, server).
dce_cs_rgy_to_loc Maps a code set value in the code set registry
to the local name for a code set (client,
server).
idl_es_decode_buffer Returns a buffer decoding handle (client,
server).
idl_es_decode_incremental Returns an incremental decoding handle (client,
server).
idl_es_encode_dyn_buffer Returns a dynamic buffer encoding handle
(client, server).
idl_es_encode_fixed_buffer Returns a fixed buffer encoding handle (client,
server).
idl_es_encode_incremental Returns an incremental encoding handle (client,
server).
idl_es_handle_free Frees an IDL encoding services handle (client,
server).
idl_es_inq_attrs Gets the flags from an IDL encoding services
handle (client, server).
idl_es_inq_encoding_id Identifies an application encoding operation
(client, server).
idl_es_set_attrs Sets attribute flags in an IDL encoding services
handle (client, server).
idl_es_set_transfer_syntax Sets a transfer syntax (client, server).
rpc_binding_copy Returns a copy of a binding handle (client or
server).
rpc_binding_free Releases binding handle resources (client or
server).
rpc_binding_from_string_binding Returns a binding handle from a string
representation of a binding handle (client or
management).
rpc_binding_inq_auth_caller Returns authentication and authorization
information from the binding handle for an
authenticated client (server).
rpc_binding_inq_auth_client Returns authentication and authorization
information from the client binding handle for
an authenticated client (server).
rpc_binding_inq_auth_info Returns authentication and authorization
information from a server binding handle
(client).
rpc_binding_inq_object Returns the object UUID from a binding handle
(client or server).
rpc_binding_reset Resets a server binding handle so the host
remains specified, but the server instance on
that host is unspecified (client or management).
rpc_binding_server_from_client Converts a client binding handle to a server
binding handle (server).
rpc_binding_set_auth_info Sets authentication and authorization
information into a server binding handle
(client).
rpc_binding_set_object Sets the object UUID value into a server binding
handle (client).
rpc_binding_to_string_binding Returns a string representation of a binding
handle (client, server, or management).
rpc_binding_vector_free Frees the memory used to store a vector and
binding handles (client or server).
rpc_cs_binding_set_tags Places code set tags into a server binding
handle (client).
rpc_cs_char_set_compat_check Evaluates character set compatibility between a
client and a server (client).
rpc_cs_eval_with_universal Evaluates a server's supported character sets
and code sets during the server binding
selection process (client).
rpc_cs_eval_without_universal Evaluates a server's supported character sets
and code sets during the server binding
selection process (client).
rpc_cs_get_tags Retrieves code set tags from a binding handle
(client, server).
rpc_ep_register Adds to, or replaces, server address information
in the local endpoint map (server).
rpc_ep_register_no_replace Adds to server address information in the local
endpoint map (server).
rpc_ep_resolve_binding Resolves a partially bound server binding handle
into a fully bound server binding handle (client
or management).
rpc_ep_unregister Removes server address information from the
local endpoint map (server).
rpc_if_id_vector_free Frees a vector and the interface identifier
structures it contains. (client, server, or
management).
rpc_if_inq_id Returns the interface identifier for an
interface specification (client or server).
rpc_mgmt_ep_elt_inq_begin Creates an inquiry context for viewing the
elements in a local or remote endpoint map
(management).
rpc_mgmt_ep_elt_inq_done Deletes the inquiry context for viewing the
elements in a local or remote endpoint map
(management).
rpc_mgmt_ep_elt_inq_next Returns one element at a time from a local or
remote endpoint map (management).
rpc_mgmt_ep_unregister Removes server address information from a local
or remote endpoint map (management).
rpc_mgmt_inq_com_timeout Returns the communication timeout value in a
binding handle (client).
rpc_mgmt_inq_dflt_protect_level Returns the default protection level for an
authentication service (client or server).
rpc_mgmt_inq_if_ids Returns a vector of interface identifiers of
interfaces a server offers (client, server, or
management).
rpc_mgmt_inq_server_princ_name Returns a server's principal name (client,
server, or management).
rpc_mgmt_inq_stats Returns RPC runtime statistics (client, server,
or management).
rpc_mgmt_is_server_listening Tells whether a server is listening for remote
procedure calls (client, server, or management).
rpc_mgmt_set_authorization_fn Establishes an authorization function for
processing remote calls to a server's management
routines (server).
rpc_mgmt_set_call_timeout Sets the amount of time the RPC runtime is to
wait for a server to complete (client).
rpc_mgmt_set_cancel_timeout Sets the lower bound on the time to wait before
timing out after forwarding a cancel (client).
rpc_mgmt_set_com_timeout Sets the communication timeout value in a
binding handle (client).
rpc_mgmt_set_server_stack_size Specifies the stack size for each server thread
(server).
rpc_mgmt_stats_vector_free Frees a statistics vector (client, server, or
management).
rpc_mgmt_stop_server_listening Tells a server to stop listening for remote
procedure calls (client, server, or management).
rpc_network_inq_protseqs Returns all protocol sequences supported by both
the RPC runtime and the operating system (client
or server).
rpc_network_is_protseq_valid Tells whether the specified protocol sequence is
supported by both the RPC runtime and the
operating system (client or server).
rpc_ns_binding_export Establishes a name service database entry with
binding handles or object UUIDs for a server
(server).
rpc_ns_binding_import_begin Creates an import context for an interface and
an object in the name service database (client).
rpc_ns_binding_import_done Deletes the import context for searching the
name service database (client).
rpc_ns_binding_import_next Returns a binding handle of a compatible server
(if found) from the name service database
(client).
rpc_ns_binding_inq_entry_name Returns the name of an entry in the name service
database from which the server binding handle
came (client).
rpc_ns_binding_lookup_begin Creates a lookup context for an interface and an
object in the name service database (client).
rpc_ns_binding_lookup_done Deletes the lookup context for searching the
name service database (client).
rpc_ns_binding_lookup_next Returns a list of binding handles of one or more
compatible servers (if found) from the name
service database (client).
rpc_ns_binding_select Returns a binding handle from a list of
compatible server binding handles (client).
rpc_ns_binding_unexport Removes the binding handles for an interface, or
object UUIDs, from an entry in the name service
database (server).
rpc_ns_entry_expand_name Expands the name of a name service entry
(client, server, or management).
rpc_ns_entry_inq_resolution Resolves the cell namespace components of a name
and returns partial results (client, server).
rpc_ns_entry_object_inq_begin Creates an inquiry context for viewing the
objects of an entry in the name service database
(client, server, or management).
rpc_ns_entry_object_inq_done Deletes the inquiry context for viewing the
objects of an entry in the name service database
(client, server, or management).
rpc_ns_entry_object_inq_next Returns one object at a time from an entry in
the name service database (client, server, or
management).
rpc_ns_group_delete Deletes a group attribute (client, server, or
management).
rpc_ns_group_mbr_add Adds an entry name to a group; if necessary,
creates the entry (client, server, or
management).
rpc_ns_group_mbr_inq_begin Creates an inquiry context for viewing group
members (client, server, or management).
rpc_ns_group_mbr_inq_done Deletes the inquiry context for a group (client,
server, or management).
rpc_ns_group_mbr_inq_next Returns one member name at a time from a group
(client, server, or management).
rpc_ns_group_mbr_remove Removes an entry name from a group (client,
server, or management).
rpc_ns_import_ctx_add_eval Adds an evaluation routine to an import context
(client).
rpc_ns_mgmt_binding_unexport Removes multiple binding handles, or object
UUIDs, from an entry in the name service
database (management).
rpc_ns_mgmt_entry_create Creates an entry in the name service database
(management).
rpc_ns_mgmt_entry_delete Deletes an entry from the name service database
(management).
rpc_ns_mgmt_entry_inq_if_ids Returns the list of interfaces exported to an
entry in the name service database (client,
server, or management).
rpc_ns_mgmt_free_codesets Frees a code sets array that has been allocated
by the RPC runtime (client, server).
rpc_ns_mgmt_handle_set_exp_age Sets a handle's expiration age for local copies
of name service data (client, server, or
management).
rpc_ns_mgmt_inq_exp_age Returns the application's global expiration age
for local copies of name service data (client,
server, or management).
rpc_ns_mgmt_read_codesets Reads the code sets attribute associated with an
RPC server entry in the name service database
(client).
rpc_ns_mgmt_remove_attribute Removes an attribute from an RPC server entry in
the name service database (server or
management).
rpc_ns_mgmt_set_attribute Adds an attribute to an RPC server entry in the
name service database (server or management).
rpc_ns_mgmt_set_exp_age Modifies the application's global expiration age
for local copies of name service data (client,
server, or management).
rpc_ns_profile_delete Deletes a profile attribute (client, server, or
management).
rpc_ns_profile_elt_add Adds an element to a profile. If necessary,
creates the entry (client, server, or
management).
rpc_ns_profile_elt_inq_begin Creates an inquiry context for viewing the
elements in a profile (client, server, or
management).
rpc_ns_profile_elt_inq_done Deletes the inquiry context for a profile
(client, server, or management).
rpc_ns_profile_elt_inq_next Returns one element at a time from a profile
(client, server, or management).
rpc_ns_profile_elt_remove Removes an element from a profile (client,
server, or management).
rpc_object_inq_type Returns the type of an object (server).
rpc_object_set_inq_fn Registers an object inquiry function (server).
rpc_object_set_type Assigns the type of an object (server).
rpc_protseq_vector_free Frees the memory used by a vector and its
protocol sequences (client or server).
rpc_rgy_get_codesets Gets supported code sets information from the
local host (client, server).
rpc_rgy_get_max_bytes Gets the maximum number of bytes that a code set
uses to encode one character from the code set
registry on a host (client, server).
rpc_server_inq_bindings Returns binding handles for communication with a
server (server).
rpc_server_inq_if Returns the manager entry point vector
registered for an interface (server).
rpc_server_listen Tells the RPC runtime to listen for remote
procedure calls (server).
rpc_server_register_auth_info Registers authentication information with the
RPC runtime (server).
rpc_server_register_if Registers an interface with the RPC runtime
(server).
rpc_server_unregister_if Unregisters an interface from the RPC runtime
(server).
rpc_server_use_all_protseqs Tells the RPC runtime to use all supported
protocol sequences for receiving remote
procedure calls (server).
rpc_server_use_all_protseqs_if Tells the RPC runtime to use all the protocol
sequences and endpoints specified in the
interface specification for receiving remote
procedure calls (server).
rpc_server_use_protseq Tells the RPC runtime to use the specified
protocol sequence for receiving remote procedure
calls (server).
rpc_server_use_protseq_ep Tells the RPC runtime to use the specified
protocol sequence combined with the specified
endpoint for receiving remote procedure calls
(server).
rpc_server_use_protseq_if Tells the RPC runtime to use the specified
protocol sequence combined with the endpoints in
the interface specification for receiving remote
procedure calls (server).
rpc_sm_allocate Allocates memory within the RPC stub memory
management scheme (usually server, possibly
client)
rpc_sm_client_free Frees memory returned from a client stub
(usually server, possibly client)
rpc_sm_destroy_client_context Reclaims the client memory resources for the
context handle, and sets the context handle to
NULL (client).
rpc_sm_disable_allocate Releases resources and allocated memory
(client).
rpc_sm_enable_allocate Enables the allocation of memory by the
rpc_sm_allocate routine when not in manager
code (client).
rpc_sm_free Frees memory allocated by the rpc_sm_allocate
routine (usually server, possibly client).
rpc_sm_get_thread_handle Gets a thread handle for the manager code before
it spawns additional threads, or for the client
code when it becomes a server (usually server,
possibly client).
rpc_sm_set_client_alloc_free Sets the memory allocation and freeing mechanism
used by the client stubs. This overrides the
default routines that the client stub uses to
manage memory for pointed-to nodes (client).
rpc_sm_set_thread_handle Sets the thread handle for either a newly
created spawned thread or for a server that was
formerly a client and is ready to be a client
again (usually server, possibly client).
rpc_sm_swap_client_alloc_free Exchanges the current memory allocation and
freeing mechanism used by the client stubs with
one supplied by the client (client).
rpc_ss_allocate Allocates memory within the RPC stub memory
management scheme (usually server, possibly
client).
rpc_ss_bind_authn_client Authenticates a client's identity to a server
from a client stub.
rpc_ss_client_free Frees memory returned from a client stub
(usually server, possibly client).
rpc_ss_destroy_client_context Reclaims the client memory resources for the
context handle, and sets the context handle to
NULL (client).
rpc_ss_disable_allocate Releases resources and allocated memory
(client).
rpc_ss_enable_allocate Enables the allocation of memory by the
rpc_ss_allocate routine when not in manager
code (client).
rpc_ss_free Frees memory allocated by the rpc_ss_allocate
routine (usually server, possibly client).
rpc_ss_get_thread_handle Gets a thread handle for the manager code before
it spawns additional threads, or for the client
code when it becomes a server (usually server,
possibly client).
rpc_ss_set_client_alloc_free Sets the memory allocation and freeing mechanism
used by the client stubs. This overrides the
default routines that the client stub uses to
manage memory for pointed-to nodes (client).
rpc_ss_set_thread_handle Sets the thread handle for either a newly
created spawned thread or for a server that was
formerly a client and is ready to be a client
again (usually server, possibly client).
rpc_ss_swap_client_alloc_free Exchanges the current memory allocation and
freeing mechanism used by the client stubs with
one supplied by the client (client).
rpc_string_binding_compose Combines the components of a string binding into
a string binding (client or server).
rpc_string_binding_parse Returns, as separate strings, the components of
a string binding (client or server).
rpc_string_free Frees a character string allocated by the
runtime (client, server, or management).
rpc_tower_to_binding Returns a binding handle from a tower
representation.
rpc_tower_vector_free Releases memory associated with a tower vector.
rpc_tower_vector_from_binding Creates a tower vector from a binding handle.
uuid_compare Compares two UUIDs and determines their order
(client, server, or management).
uuid_create Creates a new UUID (client, server, or
management).
uuid_create_nil Creates a nil UUID (client, server, or
management).
uuid_equal Determines if two UUIDs are equal (client,
server, or management).
uuid_from_string Converts a string UUID to its binary
representation (client, server, or management).
uuid_hash Creates a hash value for a UUID (client, server,
or management).
uuid_is_nil Determines if a UUID is nil (client, server, or
management).
uuid_to_string Converts a UUID from a binary representation to
a string representation (client, server, or
management).
ΓòÉΓòÉΓòÉ 5.4. RPC Environment Variables ΓòÉΓòÉΓòÉ
The RPC name service interface (NSI) routines use the following environment
variables:
RPC_DEFAULT_ENTRY Designates the default entry in the name service database
that the import and lookup routines use as the starting point to
search for binding information for a compatible server.
Normally, the starting entry is a profile.
An application that uses a default entry name must define this
environment variable. The RPC runtime does not provide a
default.
For example, suppose that a client application needs to search
the name service database for a server binding handle. The
application can use the rpc_ns_binding_import_begin routine as
part of the search. If so, the application must specify, to the
routine's entry_name parameter, the name of the entry in the
name service database at which to begin the search. If the
search is to begin at the entry that the RPC_DEFAULT_ENTRY
environment variable specifies, then the application must
specify the value NULL to parameter entry_name in routine
rpc_ns_binding_import_begin.
RPC_DEFAULT_ENTRY_SYNTAX Specifies the syntax for the name provided in the
RPC_DEFAULT_ENTRY environment variable. In addition, it provides
syntax for those RPC NSI routines that allow a default value for
the name syntax parameter.
If the RPC_DEFAULT_ENTRY_SYNTAX environment variable is not
defined, the RPC runtime uses the rpc_c_ns_syntax_dce name
syntax.
For the valid name syntaxes and syntax values, see name_syntax
in Frequently Used RPC Routine Parameters.
Each application may define either or both of the previous
environment variables. The application can change the value of
either one, or both, at any time during runtime.
RPC_UNSUPPORTED_NETADDRS Controls how a server registers itself in the CDS
database and endpoint map by masking out one or more networks
through TCP/IP addresses.
This is useful in a machine that has multiple network adapters
where the DCE traffic should be excluded from some of the
networks. For example, consider a server machine that has one
FDDI network connection for normal day-to-day traffic and is
also connected to two ethernet networks that are used only for
X-station traffic. If a DCE server is started on this machine,
it will register all three addresses in the CDS namespace and
also in the dced endpoint map. This means that all machines on
the FDDI network that want to communicate with this server have
to have valid routing interfaces to the ethernet networks
because when querying CDS for an address to the server, CDS
could return one of the ethernet addresses to a machine that is
only on the FDDI ring.
Suppose the machine described above has the following
interfaces:
Interface Address
en0 125.46.78.91
en1 125.46.125.91
fi0 9.25.47.91
The following example uses the RPC_UNSUPPORTED_NETADDRS
environment variable to eliminate both ethernet networks by
address:
RPC_UNSUPPORTED_NETADDRS=125.46.78.91:125.46.125.91
RPC_UNSUPPORTED_NETIFS Controls how a server registers itself in the CDS
database and endpoint map by masking out one or more networks
through TCP/IP interfaces.
The following example uses the RPC_UNSUPPORTED_NETIFS
environment variable to eliminate both ethernet networks by
interface:
RPC_UNSUPPORTED_NETIFS=en0:en1
It is probably better to mask out the networks by address
instead of by interface because in some instances the addresses
assigned to a specific interface could be changed while the
machine is running.
ΓòÉΓòÉΓòÉ 5.5. RPC Data Types and Structures ΓòÉΓòÉΓòÉ
This section contains the data types and structures used by client, server, and
management application programs.
Much of the information in this section is derived from the DCE for OS/2
Warp:Application Development Guide - Core Components. You might want to refer
to this book as you read this section. For example, this section contains a
brief description of a binding handle. The RPC chapters of the DCE for OS/2
Warp:Application Development Guide - Core Components explains binding handles
in detail. It also explains concepts related to binding handles, such as
binding information and string bindings.
The following are the data types used in the RPC interface:
Binding Handle
Binding Vector
Boolean
Code Set
Code Sets Array
Conversion Type
Endpoint Map Inquiry Handle
Global Name
IDL Encoding Service Handle
Interface Handle and Specification
Interface Identifier
Interface Identifier Vector
Manager Entry Point Vector
Name Service Handle
Protocol Sequence
Protocol Sequence Vector
Statistics Vector
String Binding
String UUID
Unsigned Character String
UUID Vector
ΓòÉΓòÉΓòÉ 5.5.1. Binding Handle ΓòÉΓòÉΓòÉ
A binding handle is a pointer-size opaque variable containing information the
RPC runtime uses to manage binding information. The RPC runtime uses binding
information to establish a client-server relationship that allows the running
of remote procedure calls.
Based on the context where it is created, a binding handle is considered a
server binding handle or a client binding handle.
A server binding handle is a reference to the binding information necessary for
a client to establish a relationship with a specific server. Many RPC API
runtime routines return a server binding handle that you can use to make a
remote procedure call.
A server binding handle refers to several components of binding information.
One is the network address of a server's host system. Each server instance has
one or more transport addresses (endpoints). A well-known endpoint is a stable
address on the host, while a dynamic endpoint is an address that the RPC
runtime requests for the server. Some transport protocols provide fewer
well-known endpoints than dynamic endpoints.
If binding information contains an endpoint, the corresponding binding handle
is a fully bound binding handle. If the information lacks an endpoint, the
binding handle is a partially bound binding handle.
The RPC runtime creates and provides a client binding handle to a called remote
procedure as a handle_t parameter. The client binding handle contains
information about the calling client. A client binding handle cannot be used to
make a remote procedure call. A server uses the client binding handle. The
rpc_binding_server_from_client routine converts a client binding handle to a
server binding handle. You can use the resulting server binding handle to make
a remote procedure call.
For an explanation of making a remote procedure call with a partially bound
binding handle, see the DCE for OS/2 Warp: Application Development Guide - Core
Components.
Binding information can contain an object UUID. The default object UUID
associated with a binding handle is a nil UUID. Clients can obtain a non-nil
UUID in various ways, such as from a string representation of binding
information (a string binding), or by importing it.
Client and Server Binding Handles contains RPC runtime routines that operate on
binding handles. The table also specifies the type of binding handle, client or
server, allowed.
ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
Γöé Table 3. Client and Server Binding Handles Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé ROUTINE Γöé INPUT PARAMETER Γöé OUTPUT Γöé
Γöé Γöé Γöé PARAMETER Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé rpc_binding_copy Γöé server Γöé server Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé rpc_binding_free Γöé server Γöé none Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé rpc_binding_from_string_binding Γöé none Γöé server Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé rpc_binding_inq_auth_caller Γöé client Γöé none Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé rpc_binding_inq_auth_client Γöé client Γöé none Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé rpc_binding_inq_auth_info Γöé server Γöé none Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé rpc_binding_inq_object Γöé server or Γöé none Γöé
Γöé Γöé client Γöé Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé rpc_binding_reset Γöé server Γöé none Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé rpc_binding_server_from_client Γöé client Γöé server Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé rpc_binding_set_auth_info Γöé server Γöé none Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé rpc_binding_set_object Γöé server Γöé none Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé rpc_binding_to_string_binding Γöé server or Γöé none Γöé
Γöé Γöé client Γöé Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé rpc_binding_vector_free Γöé server Γöé none Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé rpc_ns_binding_export Γöé server Γöé none Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé rpc_ns_binding_import_next Γöé none Γöé server Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé rpc_ns_binding_inq_entry_name Γöé server Γöé none Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé rpc_ns_binding_lookup_next Γöé none Γöé server Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé rpc_ns_binding_select Γöé server Γöé server Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé rpc_server_inq_bindings Γöé none Γöé server Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
If the input argument type is only a client or only a server, the routines
return the status code rpc_s_wrong_kind_of_binding when an application provides
the incorrect binding handle type.
An application can share a single binding handle across multiple threads of
execution. The RPC runtime, instead of the application, manages binding handle
concurrency control across concurrent remote procedure calls that use a single
binding handle. However, the client application has responsibility for binding
handle concurrency control for operations that read or modify a binding handle.
The related routines are as follows:
rpc_binding_free
rpc_binding_reset
rpc_binding_set_auth_info
rpc_binding_set_object
rpc_ep_resolve_binding
rpc_mgmt_set_com_timeout.
For example, suppose an application shares a binding handle across two threads
of execution and it resets the binding handle endpoint in one of the threads
(by calling the rpc_binding_reset routine). The binding handle in the other
thread is then also reset. Similarly, freeing the binding handle in one thread
(by calling the rpc_binding_free routine) also frees the binding handle in the
other thread.
If you do not want this effect, your application can create a copy of a
binding handle by calling the rpc_binding_copy routine. An operation on one
binding handle then has no effect on the second binding handle.
Clients and servers can access and set object UUIDs using the
rpc_binding_inq_object and rpc_binding_set_object routines.
Routines requiring a binding handle as an parameter show a data type of
rpc_binding_handle_t. Binding handle parameters are passed by value.
ΓòÉΓòÉΓòÉ 5.5.2. Binding Vector ΓòÉΓòÉΓòÉ
The binding vector data structure contains a list of binding handles over which
a server application can receive remote procedure calls.
The binding vector contains a count member count, followed by an array of
binding handle binding_h elements.
The C language representation of a binding vector is as follows:
typedef struct {
unsigned32 count;
rpc_binding_handle_t binding_h[1];
} rpc_binding_vector_t;
The RPC runtime creates binding handles when a server application registers
protocol sequences. To obtain a binding vector, a server application calls the
rpc_server_inq_bindings routine.
A client application obtains a binding vector of compatible servers from the
name service database by calling the rpc_ns_binding_lookup_next routine.
In both routines, the RPC runtime allocates memory for the binding vector. An
application calls the rpc_binding_vector_free routine to free the binding
vector.
To remove an individual binding handle from the vector, set its value in the
vector to NULL. When this is done, the application must free the individual
binding by calling the rpc_binding_free routine when it is finished with it. It
also cannot change the value of count before calling the
rpc_binding_vector_free routine because this allows the application to free the
unwanted binding handle and to set the vector entry to NULL.
An application, when it is finished with an individual binding handle in a
binding vector, frees the binding handle by calling the rpc_binding_free
routine. This routine also sets the corresponding pointer in the binding vector
to NULL.
Note that you should not decrement the field count in a binding vector
structure when you call routine rpc_binding_free to free an individual binding
handle.
The following routines require a binding vector and they show an parameter data
type of rpc_binding_vector_t:
rpc_binding_vector_free
rpc_ep_register
rpc_ep_register_no_replace
rpc_ep_unregister
rpc_ns_binding_export
rpc_ns_binding_lookup_next
rpc_ns_binding_select
rpc_server_inq_bindings
ΓòÉΓòÉΓòÉ 5.5.3. Boolean ΓòÉΓòÉΓòÉ
Routines that require a Boolean-valued parameter or return a Boolean value show
a data type of boolean32. DCE RPC provides the integer constants TRUE (1) and
FALSE (0) for use as Boolean values.
ΓòÉΓòÉΓòÉ 5.5.4. Code Set ΓòÉΓòÉΓòÉ
A code set is a mapping of the members of a character set to specific numeric
code values. Different code sets use different numeric code values to represent
the same character. In general, operating systems use string names to refer to
the code sets that the system supports. It is common for different operating
systems to use different string names to refer to the same code set.
Distributed applications that run in a network of heterogeneous operating
systems need to be able to identify the character sets and code sets that
client and server machines are using to avoid losing data during communications
between each other. DCE RPC supports transparent automatic conversion for
characters that are members of the DCE Portable Character Set (DCE PCS) and
which are encoded in the ASCII and U.S. EBCDIC code sets. The RPC runtime
automatically converts DCE PCS characters encoded in ASCII or U.S. EBCDIC, if
necessary, when they are passed over the network between client and server.
DCE RPC applications that need to transfer character data that is outside the
DCE PCS character set and ASCII and U.S. EBCDIC encodings (international
characters) can use special IDL constructs and a set of DCE RPC routines to set
up their applications so that they can pass this international character data
with minimal or no loss between client and server applications. An example of
such an application would be one that used European, Chinese, or Japanese
characters mapped to EUC, Big5, or SJIS encodings. Together, the IDL constructs
and the DCE RPC routines provide a method of automatic code set conversion for
applications that transfer international character data in heterogeneous code
set environments.
DCE provides a mechanism to uniquely identify a code set; this mechanism is the
code set registry. The code set registry assigns a unique identifier to each
character set and code set. Because the registry provides code set identifiers
that are consistent across a network of heterogeneous operating systems, it
provides a method for clients and servers in a heterogeneous environment to use
to identify code sets without having to rely on operating system-specific
string names.
The code set data structure contains the following fields:
c_set A 32-bit hexadecimal value that uniquely identifies the code
set. This value is one of the registered values in the code set
registry.
c_max_bytes A 16-bit decimal value that indicates the maximum number of
bytes this code set uses to encode one character in this code
set.
ch_sets_num A 16-bit decimal value that indicates the number of character
sets supported by the codeset.
ch_sets A 32-bit pointer to a dynamically allocated array of OSF
assigned character set identifiers.
The following routines require a code set value:
cs_byte_from_netcs
cs_byte_local_size
cs_byte_net_size
cs_byte_to_netcs
dce_cs_loc_to_rgy
dce_cs_rgy_to_loc
rpc_cs_get_tags
rpc_cs_binding_set_tags
rpc_rgy_get_max_bytes
In these routines, the code set value shows a data type of unsigned32.
The RPC stub buffer sizing routines xxx_net_size and xxx_local_size use the
value of c_max_bytes to calculate the size of a buffer for code set
conversion.
The RPC character set compatibility evaluation routine
rpc_cs_char_set_compat_check uses the value of ch_sets_num and values pointed
to by ch_sets to evaluate character set compatibility between a client and a
server.
The C language representation of a code set structure is as follows:
typedef struct {
long c_set;
short c_max_bytes;
short ch_sets_num;
short *ch_sets;
} rpc_cs_c_set_t;
The code set data structure is a member of the code sets array.
ΓòÉΓòÉΓòÉ 5.5.5. Code Sets Array ΓòÉΓòÉΓòÉ
The code sets array contains the list of the code sets that a client or server
supports. The structure consists of a version number member (version), followed
by a count member (count), followed by an array of code set data structures
(rpc_cs_c_set_t). This array is declared to be a conformant array so that its
size is determined at runtime. The count member indicates the number of code
sets contained in the array.
The first element in the code sets array represents the local code set of the
client or server process.
DCE RPC routines for character/code sets compatibility evaluation and code set
conversion support one intermediate code set, which is the ISO 10646 Universal
character/code set (UCS-2, Level 1). Consequently, DCE requires host systems
running applications that transfer international characters to provide
converters for this code set.
The remaining elements in the array represent other code sets that the
process's host supports (that is, code sets for which the system provides
converters).
The C language representation of a code sets array is:
typedef struct rpc_codeset_mgmt_s_t {
unsigned32 version;
unsigned32 count;
[size_is(count)] rpc_cs_c_set_t codesets[];
} rpc_codeset_mgmt_t, *rpc_codeset_mgmt_p_t;
Client and server applications and DCE RPC routines for automatic code set
conversion obtain a code sets array by calling the routine
rpc_rgy_get_codesets. Server applications use the code sets array as input to
the rpc_ns_mgmt_set_attribute routine, which registers their supported
character and code sets in the name service database. Client applications look
up a server's supported character and code sets in the name service database by
calling the routine rpc_ns_mgmt_read_codesets and then use their code sets
array to evaluate their supported code sets against the code sets that the
server supports.
The following DCE RPC routines require a code sets array and show an argument
data type of rpc_codeset_mgmt_t:
rpc_cs_char_set_compat_check
rpc_ns_mgmt_read_codesets
rpc_rgy_get_codesets
Server applications that use the routine rpc_ns_mgmt_set_attribute to register
their supported code sets in the name service database also specify the code
sets array, but show an argument data type of void.
ΓòÉΓòÉΓòÉ 5.5.6. Conversion Type ΓòÉΓòÉΓòÉ
The conversion type data structure is an enumerated type that RPC stub buffer
sizing routines return to indicate whether character data conversion is
necessary and whether existing storage is sufficient for the stub to store the
results of the conversion. The conversion type can be one of the following
values:
idl_cs_no_convert No code set conversion is required.
idl_cs_new_buffer_convert The converted data must be written to a new
storage area.
The C language representation of a conversion type structure is:
typedef enum {
idl_cs_no_convert,
idl_cs_new_buffer_convert,
} idl_cs_convert_t;
ΓòÉΓòÉΓòÉ 5.5.7. Endpoint Map Inquiry Handle ΓòÉΓòÉΓòÉ
An endpoint map inquiry handle is a pointer-size opaque variable. It contains
information the RPC runtime uses to access the elements in a local or remote
endpoint map. The description of the rpc_ep_register routine lists the
contents of an element.
The following routines require an endpoint map inquiry handle and they show an
parameter data type of rpc_ep_inq_handle_t:
rpc_mgmt_ep_elt_inq_begin
rpc_mgmt_ep_elt_inq_done
rpc_mgmt_ep_elt_inq_next.
ΓòÉΓòÉΓòÉ 5.5.8. Global Name ΓòÉΓòÉΓòÉ
The Name Service Interface (NSI) uses global names as the names of name service
entries. A global name includes both a cell name and a cell-relative name
composed of a directory path name and a leaf name. (For a description of global
names, see the DCE for OS/2 Warp: Application Development Guide - Core
Components). The cell name is assigned to a cell root at its creation. When
you specify only a cell-relative name to an NSI operation, the NSI
automatically expands the name into a global name by inserting the local cell
name. Thus, the name of a member in a group or in a profile element is always
stored as a global name. When returning the name of a name service entry or a
member, NSI operations return global names.
For example, when you specify a cell-relative name as the member_name parameter
to the rpc_ns_group_mbr_add routine, you can receive the corresponding global
name by calling the rpc_ns_group_mbr_inq_next routine.
ΓòÉΓòÉΓòÉ 5.5.9. IDL Encoding Service Handle ΓòÉΓòÉΓòÉ
An IDL encoding service handle is a pointer-size opaque variable that points to
routines that control how data encoding or decoding is performed. The following
routines return an IDL encoding service handle and show an argument data type
of idl_es_handle_t:
idl_es_encode_incremental
idl_es_decode_buffer
idl_es_decode_incremental
idl_es_encode_dyn_buffer
idl_es_encode_fixed_buffer
The idl_es_handle_free and idl_es_inq_encoding_id routines require an IDL
encoding service handle.
Note that in order to use the IDL encoding services, you must include a header
file that has been generated for an application that has used the encode and
decode ACF attributes on one or more of its operations.
ΓòÉΓòÉΓòÉ 5.5.10. Interface Handle and Specification ΓòÉΓòÉΓòÉ
An interface handle is a pointer-size opaque variable. It contains information
the RPC runtime uses to access the interface specification data structure.
The DCE IDL compiler automatically creates an interface specification data
structure from each IDL file, and it creates a global variable of type
rpc_if_handle_t for the interface specification.
The DCE IDL compiler places an interface handle declaration in the generated
interface-name.h file. The compiler generates this include file for each
interface.
Routines requiring the interface handle as a parameter show a data type of
rpc_if_handle_t.
The form of each interface handle name is as follows:
o For the client:
if-name_vmajor-version_minor-version_c_ifspec
o For the server:
if-name_vmajor-version_minor-version_s_ifspec
where:
o if-name is the interface identifier specified in the IDL file.
o major-version is the interface's major-version number specified in the
IDL file.
o minor-version is the interface's minor-version number specified in the
IDL file.
An example is notes_v1_2_c_ifspec.
The maximum combined length of the interface identifier and interface version
number is 19 characters. Since the major-version and minor-version numbers
must each be at least 1 character, the interface name can be no more than 17
characters. This limits the interface handle name to 31 or fewer characters.
No concurrency control is required for interface handles.
The following routines require an interface handle and show an parameter data
type of rpc_if_handle_t:
rpc_ep_register
rpc_ep_register_no_replace
rpc_ep_resolve_binding
rpc_ep_unregister
rpc_if_inq_id
rpc_ns_binding_export
rpc_ns_binding_import_begin
rpc_ns_binding_lookup_begin
rpc_ns_binding_unexport
rpc_server_inq_if
rpc_server_register_if
rpc_server_unregister_if
rpc_server_use_all_protseqs_if
rpc_server_use_protseq_if
ΓòÉΓòÉΓòÉ 5.5.11. Interface Identifier ΓòÉΓòÉΓòÉ
The interface identifier (ID) data structure contains the interface UUID and
major-version and minor-version numbers of an interface. The interface
identifier is a subset of the data contained in the interface specification
structure.
The C language representation of an interface identifier structure is as
follows:
typedef struct {
uuid_t uuid;
unsigned16 vers_major;
unsigned16 vers_minor;
} rpc_if_id_t;
Routines that require an interface identifier structure show a data type of
rpc_if_id_t. In these routines, the application is responsible for providing
memory for the structure.
The rpc_if_inq_id routine returns the interface identifier from an interface
specification. The following routines require an interface identifier:
rpc_mgmt_ep_elt_inq_begin
rpc_mgmt_ep_elt_inq_next
rpc_mgmt_ep_unregister
rpc_ns_mgmt_binding_unexport
rpc_ns_profile_elt_add
rpc_ns_profile_elt_inq_begin
rpc_ns_profile_elt_inq_next
rpc_ns_profile_elt_remove.
ΓòÉΓòÉΓòÉ 5.5.12. Interface Identifier Vector ΓòÉΓòÉΓòÉ
The interface identifier (ID) vector data structure contains a list of
interfaces offered by a server. The interface identifier vector contains a
count member count, followed by an array of pointers (of pointer type
rpc_if_id_t) to interface identifiers.
The C language representation of an interface identifier vector is as follows:
typedef struct {
unsigned32 count;
rpc_if_id_t *if_id[1];
} rpc_if_id_vector_t;
The interface identifier vector is a read-only vector. To obtain a vector of
the interface identifiers registered by a server with the RPC runtime, an
application calls the rpc_mgmt_inq_if_ids routine. To obtain a vector of the
interface identifiers exported by a server to a name service database, an
application calls the rpc_ns_mgmt_entry_inq_if_ids routine.
The RPC runtime allocates memory for the interface identifier vector. The
application calls the rpc_if_id_vector_free routine to free the interface
identifier vector.
ΓòÉΓòÉΓòÉ 5.5.13. Manager Entry Point Vector ΓòÉΓòÉΓòÉ
The manager Entry Point Vector (EPV) is an array of pointers to remote
procedures.
The DCE IDL compiler automatically generates a manager EPV data type, into the
header file generated by the IDL compiler, for use in constructing manager
EPVs. The data type is named as follows:
if-name_v major-version_minor-version_epv_t
where:
o if-name is the interface identifier specified in the IDL file.
o major-version is the interface's major version number specified in the
IDL file.
o minor-version is the interface's minor version number specified in the
IDL file.
By default, the DCE IDL compiler automatically creates and initializes a
manager EPV. DCE IDL creates this EPV assuming that a manager routine of the
same name exists for each procedure in the interface (as specified in the IDL
file).
The DCE IDL compiler can define a client Entry Point Vector with addresses of
local routines. Client applications can call these routines. For more
information about client entry point vectors, see the explanation of the -cepv
parameter in the DCE for OS/2 Warp: Administration Command Reference.
If the server offers multiple implementations of the same interface, the
server must create additional manager EPVs, one for each implementation. Each
EPV must contain exactly one entry point (address of a routine) for each
procedure defined in the IDL file. The server application declares and
initializes one manager EPV variable of type
if-name_vmajor-version_minor-version_epv_t for each implementation of the
interface.
The rpc_server_register_if and rpc_server_inq_if routines use the manager EPV
data type and show the manager EPV parameter as having an rpc_mgr_epv_t data
type.
ΓòÉΓòÉΓòÉ 5.5.14. Name Service Handle ΓòÉΓòÉΓòÉ
A name service handle is a pointer-size opaque variable containing information
the RPC runtime uses to return the following RPC data from the name service
database:
o Server binding handles
o UUIDs of resources offered by a server
o Profile members
o Group members.
The following routines require a name service handle and show an parameter
data type of rpc_ns_handle_t:
rpc_ns_binding_import_begin
rpc_ns_binding_import_next
rpc_ns_binding_import_done
rpc_ns_binding_lookup_begin
rpc_ns_binding_lookup_next
rpc_ns_binding_lookup_done
rpc_ns_entry_object_inq_begin
rpc_ns_entry_object_inq_next
rpc_ns_entry_object_inq_done
rpc_ns_group_mbr_inq_begin
rpc_ns_group_mbr_inq_next
rpc_ns_group_mbr_inq_done
rpc_ns_profile_elt_inq_begin
rpc_ns_profile_elt_inq_next
rpc_ns_profile_elt_inq_done
rpc_ns_mgmt_handle_set_exp_age.
The scope of a name service handle is from a xxx_begin routine through the
corresponding xxx_done routine.
Applications have responsibility for concurrency control of name service
handles across threads.
ΓòÉΓòÉΓòÉ 5.5.15. Protocol Sequence ΓòÉΓòÉΓòÉ
A protocol sequence is a character string identifying the network protocols
used to establish a relationship between a client and server. The protocol
sequence contains a set of options that the RPC runtime must know about. The
following options are in this set:
o The RPC protocol used for communications (choices are ncacn and ncadg).
o The format used in the network address supplied in the binding (choices
are AF-INET and AF-NETBIOS).
o The transport protocol used for communications.
Only certain combinations of these options are useful for interoperation. RPC
provides predefined strings that represent the valid combinations. RPC
applications use only these strings.
The following list contains predefined strings representing valid protocol
sequences. In the descriptions, NCA is an abbreviation of Network Computing
Architecture.
Protocol Sequence Description
ncacn_ip_tcp NCA Connection over Internet Protocol: Transmission Control
Protocol
ncadg_ip_udp NCA Datagram over Internet Protocol: User Datagram Protocol
ncacn_nb_stream NCA Connection over NetBIOS
A server application can use a particular protocol sequence only if the
operating system software supports that protocol. A server chooses to accept
remote procedure calls over some or all of the supported protocol sequences.
Client and server applications can determine if a protocol sequence is
supported by the RPC runtime and the operating system. The applications
determine this by calling the following routines:
o rpc_network_inq_protseqs
o rpc_network_is_protseq_valid.
The following routines allow server applications to register protocol
sequences with the runtime:
o rpc_server_use_all_protseqs
o rpc_server_use_all_protseqs_if
o rpc_server_use_protseq
o rpc_server_use_protseq_ep
o rpc_server_use_protseq_if.
Those routines requiring a protocol sequence parameter show a data type of
unsigned_char_t *.
A client can use the protocol sequence strings to construct a string binding
using the rpc_string_binding_compose routine.
ΓòÉΓòÉΓòÉ 5.5.16. Protocol Sequence Vector ΓòÉΓòÉΓòÉ
The protocol sequence vector data structure contains a list of protocol
sequences over which the RPC runtime can send or receive remote procedure
calls. The protocol sequence vector contains a count member (count), followed
by an array of pointers to protocol sequence strings (protseq).
The C language representation of a protocol sequence vector is as follows:
typedef struct {
unsigned32 count;
unsigned_char_t *protseq[1];
} rpc_protseq_vector_t;
The protocol sequence vector is a read-only vector. To obtain a protocol
sequence vector, a server application calls the rpc_network_inq_protseqs
routine. RPC runtime allocates memory for the protocol sequence vector. The
server application calls the rpc_protseq_vector_free routine to free the
protocol sequence vector.
ΓòÉΓòÉΓòÉ 5.5.17. Statistics Vector ΓòÉΓòÉΓòÉ
The statistics vector data structure contains statistics from the RPC runtime
on a per address space basis. The statistics vector contains a count member
(count), followed by an array of statistics. Each array element contains an
unsigned32 value. The following list describes the statistics indexed by the
specified constant:
rpc_c_stats_calls_in The number of remote procedure calls received by the
runtime.
rpc_c_stats_calls_out The number of remote procedure calls initiated by the
runtime.
rpc_c_stats_pkts_in The number of network packets received by the runtime.
rpc_c_stats_pkts_out The number of network packets sent by the runtime.
The C language representation of a statistics vector is as follows:
typedef struct {
unsigned32 count;
unsigned32 stats[1];
} rpc_stats_vector_t;
To obtain runtime statistics, an application calls the rpc_mgmt_inq_stats
routine. The RPC runtime allocates memory for the statistics vector. The
application calls the rpc_mgmt_stats_vector_free routine to free the
statistics vector.
ΓòÉΓòÉΓòÉ 5.5.18. String Binding ΓòÉΓòÉΓòÉ
A string binding contains the character representation of a binding handle.
String bindings are a convenient way of representing portions of a binding
handle. However, you cannot use string bindings directly to make remote
procedure calls. You must first call the routine
rpc_binding_from_string_binding, which converts a string binding to a binding
handle.
A string binding does not contain all the information from a binding handle.
For example, a call to the rpc_binding_to_string_binding routine does not
translate the authentication information sometimes associated with a binding
handle into the resulting string binding.
You can begin the development of a distributed application by having its
servers communicate their binding information to clients by using string
bindings. This communication allows a server to establish a client-server
relationship without using the local endpoint map or the name service database.
In this case, the server calls none of the rpc_ep_register,
rpc_ep_register_no_replace, and rpc_ns_binding_export routines. Instead, the
server calls only the rpc_server_inq_bindings routine to obtain a vector of
binding handles. The server obtains binding handles one at a time from the
vector and calls the rpc_binding_to_string_binding routine to convert each
binding handle into a string binding. The resulting string binding is always
fully bound and may contain a non-nil object UUID. The server then makes some
or all of its string bindings available to clients. The server can place the
string bindings in a file to be read by clients or users or both. It can also
deliver the string bindings to clients or users by means of a file, mail, or
paper.
You can continue the distributed application's development by changing the
application so that servers use the local endpoint map and the name service
database to communicate their binding information.
To find the server, a client obtains a string binding containing a protocol
sequence that the client runtime supports and, optionally, an object UUID that
the client requires. The client then calls the rpc_binding_from_string_binding
routine to convert the string binding into a server binding handle.
Other useful routines for working with string bindings are:
rpc_string_binding_compose Creates a string binding from its component
parts.
rpc_string_binding_parse Separates a string binding into its component
parts.
Look at the two formats of a string binding that follow this paragraph. The
four fields represent the object UUID, RPC protocol sequence, network address,
and endpoint and network options of the binding. A delimiter character such as
@ (at sign) or : (colon) separates each field. A string binding does not
contain any white space.
object-uuid@rpc-protocol-sequence:nw-addr[endpoint,option...]
object-uuid@rpc-protocol-sequence:nw-addr[endpoint=endpoint,option...]
where:
object-uuid Specifies the UUID of the object operated on by the remote
procedure that is called with this string binding. The RPC
runtime, at the server, maps the object's type to a manager
entry point vector (EPV) to call the correct manager routine.
The explanation of the rpc_server_register_if routine discusses
mapping object UUIDs to manager EPVs. This field is optional. If
you do not provide a value, the RPC runtime assumes a nil UUID.
@ Delimiter character for the object UUID field. If you specify an
object UUID you must follow it with this symbol.
rpc-protocol-sequence Specifies the protocol sequence used for making remote
procedure calls. The valid protocol sequences are:
o ncacn_ip_tcp
o ncadg_ip_udp
o ncacn_nb_stream
More information about these valid protocol sequences is in a
list in Frequently Used RPC Routine Parameters.
This field is required.
: (colon) Delimiter character for the RPC protocol sequence field.
nw-addr Specifies the address (addr) of a host on a network (nw) that
receives remote procedure calls made with this string binding.
The format and content of the network address depends on the
value of rpc-protocol-sequence.
The ncadg_ip_udp and ncacn_ip_tcp protocol sequences specify an
Internet address using the common Internet address notation or
host name.
The ncacn_nb_stream protocol sequences specify a NetBIOS
address.
Two examples with common Internet address notation are
128.10.2.30 and #126.15.1.28. The second example shows the use
of the optional # (number sign) character.
An example with a host name is ko. If the specified host name is
multihomed, the binding handle returned from the
rpc_binding_from_string_binding routine contains a host address.
It is the first host address returned from the system library
call that translates a host name to a host address for the
network address format in the protocol sequence. To control the
host address used, specify the network address using the common
Internet address notation instead of a host name.
The network address field is optional. If you do not supply
this field, the string binding refers to your local host.
[ (left bracket) Delimiter character specifying that one endpoint and zero or
more options follow. If the string binding contains at least one
endpoint, this symbol is required.
endpoint Specifies the endpoint, or address of a specific server instance
on a host, to receive remote procedure calls made with this
string binding. Optionally, the keyword endpoint= can precede
the endpoint specifier.
The format and content of the endpoint depends on the specified
protocol sequence. The ncadg_ip_udp and ncacn_ip_tcp protocol
sequences specify an Internet port number.
The ncacn_nb_stream protocol sequences specify a NetBIOS
address.
An example of an Internet port number is 1025.
The endpoint field is optional. For more information about
endpoints, see the section on Binding Handle.
, (comma) Delimiter character specifying that option data follows. If an
option follows, this delimiter is required.
option Specifies any options. Each option is specified as option
name=option value.
There are no Internet options or options for ncadg_ip_udp,
ncacn_ip_tcp, and ncacn_nb_stream.
The option field is not required.
] (right bracket) Delimiter character specifying that one endpoint and zero or
more options precede. If the string binding contains at least
one endpoint, this symbol is required.
\ (backslash) Escape character for all string binding fields.
Look at the following examples of valid string bindings. In each example
obj-uuid represents a UUID in string form. In other words, the symbol obj-uuid
can represent the UUID 308fb580-1eb2-11ca-923b-08002b1075a7.
obj-uuid@ncacn_ip_tcp:16.20.16.27[2001]
obj-uuid@ncacn_ip_tcp:16.20.16.27[endpoint=2001]
Cleaning Up Stale Socket Files
When a well-written DCE server application exits under normal conditions, it
will unregister its endpoints from the RPC endpoint map, among other things,
before it exits. In the case of ip-based protocols, such as ncacn_ip_tcp and
ncadg_ip_udp, the ports that the DCE application was listening on are cleaned
up by the operating system, so no application action is required to free up
the ports.
ΓòÉΓòÉΓòÉ 5.5.19. String UUID ΓòÉΓòÉΓòÉ
A string UUID contains the character representation of a UUID. A string UUID
consists of multiple fields of hexadecimal characters. Each field has a fixed
length, and hyphens separate the fields. An example of a string UUID is:
989c6e5c-2cc1-11ca-a044-08002b1bb4f5
When you supply a string UUID as an input parameter to an RPC runtime routine,
you can enter the alphabetic hexadecimal characters in either uppercase or
lowercase. The RPC runtime routines that return a string UUID always return
the hexadecimal characters in lowercase letters.
The following routines require a string UUID:
rpc_string_binding_compose
uuid_from_string
The following routines return a string UUID:
rpc_string_binding_parse
uuid_to_string
ΓòÉΓòÉΓòÉ 5.5.20. Unsigned Character String ΓòÉΓòÉΓòÉ
DCE RPC treats all characters in strings as unsigned characters. Routines with
character string parameters show a data type of unsigned_char_t *.
ΓòÉΓòÉΓòÉ 5.5.21. UUID Vector ΓòÉΓòÉΓòÉ
The UUID vector data structure contains a list of UUIDs. The UUID vector
contains a count member (count), followed by an array of pointers to UUIDs.
The C language representation of a UUID vector is as follows:
typedef struct
{
unsigned32 count;
uuid_t *uuid[1];
} uuid_vector_t;
An application constructs a UUID vector to contain object UUIDs to be exported
or unexported from the name service database. The following routines require a
UUID vector and show a data type of uuid_vector_t:
rpc_ep_register
rpc_ep_register_no_replace
rpc_ep_unregister
rpc_ns_binding_export
rpc_ns_binding_unexport
rpc_ns_mgmt_binding_unexport.
ΓòÉΓòÉΓòÉ 5.6. Permissions Required for RPC ΓòÉΓòÉΓòÉ
To use the Name Service Interface (NSI) routines to access entries in a Cell
Directory Service (CDS) database, you need access control list (ACL)
permissions. Depending on the NSI operation, you need ACL permissions to the
parent directory or the CDS object entry (the name service entry) or both. The
ACL permissions are as follows:
o To create an entry, you need insert permission to the parent directory.
o To read an entry, you need read permission to the CDS object entry.
o To write to an entry, you need write permission to the CDS object entry.
o To delete an entry, you need delete permission either to the CDS object
entry or to the parent directory.
o To test an entry, you need either test permission or read permission to
the CDS object entry.
Note that write permission does not imply read permission.
To find the ACL permissions for the NSI routines (whose names begin with
rpc_ns), see the Permissions Required parts in the routines' reference
sections.
The non-NSI routines (whose names do not begin with rpc_ns) do not need ACL
permissions, so their reference sections have no "Permissions Required" parts.
ΓòÉΓòÉΓòÉ 5.7. Frequently Used RPC Routine Parameters ΓòÉΓòÉΓòÉ
A few parameters are common to many of the DCE RPC routines. These parameters
are described fully here and again briefly on the specific routine reference
pages.
binding Used as an input or output parameter. This parameter returns a
binding handle for making remote procedure calls to a server. A
client obtains a binding handle by calling one of the following
routines:
rpc_binding_copy
rpc_binding_from_string_binding
rpc_ns_binding_import_next
rpc_ns_binding_select.
Creating a binding handle establishes a relationship between a client and a
server. However, the relationship does not involve any communication between
the client and server. The communication occurs when a client makes a remote
procedure call.
As an input parameter to a remote procedure call, binding specifies a binding
handle that refers to binding information. The client's RPC runtime uses this
binding information to make a remote procedure call to a server.
Server manager routines can extract client information from a client binding
handle by using the following routines:
rpc_binding_inq_auth_caller
rpc_binding_inq_auth_client
rpc_binding_inq_object
rpc_binding_to_string_binding
rpc_string_binding_parse.
name Used as an input or output parameter.
When used as an input parameter, the value of this parameter
depends on the syntax selected in the name_syntax parameter. If
it is allowed by the called routine, the value NULL specifies
that the routine uses the name specified in the
RPC_DEFAULT_ENTRY environment variable. Specifying NULL also has
the called routine use the name syntax that the environment
variable RPC_DEFAULT_ENTRY_SYNTAX specifies.
For a name_syntax value of rpc_c_ns_syntax_dce, use the DCE
naming rules to specify the name parameter.
As an output parameter, name returns an entry in the name
service database in the form of a character string that includes
a terminating null character. The value of this parameter
depends on the syntax selected in name_syntax.
For a name_syntax value of rpc_c_ns_syntax_dce, name is returned
using the DCE naming syntax.
The DCE RPC runtime allocates memory for the returned string.
The application is responsible for calling the rpc_string_free
routine to deallocate the string.
If an application does not want a returned name string, the
application usually specifies NULL for this parameter. The one
exception is the rpc_ns_entry_expand_name routine. It always
returns a name string.
name_syntax Used only as an input parameter. It is an integer value that
specifies the syntax of an entry name. When allowed by the
called routine, a value of rpc_c_ns_syntax_default specifies
that the routine uses the syntax specified in the
RPC_DEFAULT_ENTRY_SYNTAX environment variable. The following
table lists the valid syntaxes that applications can use in DCE
RPC for entries in the name service database.
ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
Γöé Table 4. Valid Name Syntaxes Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé CONSTANT Γöé VALUE Γöé DESCRIPTION Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé rpc_c_ns_syntax_default Γöé 0 Γöé Default syntax Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé rpc_c_ns_syntax_dce Γöé 3 Γöé DCE Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
The name_syntax parameter tells routines how to parse the entry
name specified in an input name parameter or specifies the
syntax to use when returning an entry name as an output name
parameter.
If the RPC_DEFAULT_ENTRY_SYNTAX environment variable is not
defined, the RPC runtime uses the rpc_c_ns_syntax_dce name
syntax.
string Used as an input or output parameter.
It returns a character string, which always includes the
terminating NULL character \0. The DCE RPC runtime allocates
memory for the returned string. The application calls the
rpc_string_free routine to deallocate the memory occupied by the
string.
If there is no data for the requested string, the routine
returns the string \0. For example, if the string binding
passed to the rpc_string_binding_parse routine does not contain
an object UUID, the routine returns \0 as the value of the
object UUID string. The application must call the
rpc_string_free routine to deallocate the memory occupied by
this string.
If an application does not require a returned output string, the
application specifies NULL for this parameter.
status Each routine in the RPC API returns a DCE status code indicating
whether the routine completed successfully or, if not, why not.
A return value of rpc_s_ok indicates success. All other return
values signify routine failure. The status codes listed for
each RPC runtime routine are the most likely, but not
necessarily all, the status codes that the routine can return.
The status code parameter has a data type of unsigned32. To
translate a DCE status code to a text message, call the
dce_error_inq_text routine. Note that RPC exceptions are
equivalent to RPC status codes. To identify the status code that
corresponds to a given exception, replace the _x_ string of the
exception with the string _s_; for example, the exception
rpc_x_already_listening is equivalent to the status code
rpc_s_already_listening.
The documentation for each status code includes the message
text, the explanation, and the suggested user action. These can
be found in the online helps.
uuid Used as an input or output parameter. When you need to specify a
nil UUID to a uuid input parameter in any of the DCE RPC
routines, you can supply the value NULL.
ΓòÉΓòÉΓòÉ 5.8. RPC Related Information ΓòÉΓòÉΓòÉ
Books:
DCE for OS/2 Warp: Administration Command Reference
DCE for OS/2 Warp: Application Development Guide - Core Components
ΓòÉΓòÉΓòÉ 5.8.1. cs_byte_from_netcs ΓòÉΓòÉΓòÉ
Purpose
Converts international character data from a network code set to a
local code set. This routine is used by client and server
applications.
Format
#include <dce/codesets_stub.h>
void cs_byte_from_netcs(
rpc_binding_handle_t binding,
unsigned32 network_code_set_value,
idl_byte *network_data,
unsigned32 network_data_length,
unsigned32 local_buffer_size,
idl_byte *local_data,
unsigned32 *local_data_length,
error_status_t *status);
Parameters
Input
binding Specifies the target binding handle from which to
obtain code set conversion information. When called
from the client stub, this value is the binding handle
of a compatible server returned by the
rpc_ns_binding_import_next or rpc_ns_binding_select
routine. When called from the server stub, this value
is a pointer to binding information that the client
stub passed in the RPC call.
network_code_set_value The registered hexadecimal integer value that
represents the code set that was used to transmit
character data over the network. In general, the
network code set is the code set that the client
application's code sets evaluation routine has
determined to be compatible for this client and server.
When the caller is the client stub, this value is the
receiving tag. When the caller is the server stub, this
value is the sending tag.
network_data A pointer to the international character data that has
been received, in the network code set encoding.
network_data_length The number of idl_byte data elements to be
converted. For a conformant array, this value is the
local value of the size_is variable.
local_buffer_size A pointer to the buffer size to be allocated to
contain the converted data, in units of byte. The value
specified in this parameter is the local buffer size
returned from the cs_byte_local_size routine.
Output
local_data A pointer to the converted data, in idl_byte format.
local_data_length The length of the converted data, in units of
idl_byte.
status Returns the status code from this routine. On
successful completion, the routine returns rpc_s_ok.
Otherwise, it returns one of the following errors:
rpc_s_ss_incompatible_codesets The specified code
set does not match the code set
specified in the sending tag in the
binding handle. If this error occurs
in the server stub, an exception is
raised to the client application.
When running the host converter, the following errors
can occur:
rpc_s_ss_invalid_char_input
rpc_s_ss_short_conv_buffer
rpc_s_ss_iconv_error (HP-UX reference platform
only)
rpc_s_ss_no_memory (HP-UX reference platform only)
When called from the server stub, the routine calls the
dce_cs_loc_to_rgy routine and the host converter routines. If these
routines return an error, an exception is raised to the client
application.
Usage
The cs_byte_from_netcs routine belongs to a set of DCE RPC routines
for use by client and server applications that are transferring
international character data in a heterogeneous character set and
code sets environment.
The cs_byte_from_netcs routine is one of the DCE RPC stub code set
conversion routines that RPC stubs use before they marshall or
unmarshall data to convert international character data to and from
local and network code sets.
Client and server stubs call the cs_byte_xxx_netcs routines when the
cs_byte type has been specified as the local data type using the
cs_char attribute in the attribute configuration file for the
application (the cs_byte type is equivalent to the byte type.)
Client and server stubs call the cs_byte_from_netcs routine before
they unmarshall the international character data received from the
network. The routine takes a binding handle, a code set value that
identifies the code set used to transfer international character data
over the network, the address of the network data, in idl_byte
format, that may need to be converted, and the data length, in units
of idl_byte.
The routine compares the sending code set to the local code set
currently in use. If the routine finds that code set conversion is
necessary (because the local code set differs from the code set
specified to be used on the network), it determines which host code
set converter to call to convert the data and then calls that
converter.
The routine then returns the converted conformant data, in idl_byte
format. The routine also returns the length of the converted data, in
units of idl_byte.
Applications can specify local data types other than cs_byte (the
local data type for which DCE RPC supplies stub code set conversion
routines) with the cs_char ACF attribute. In this case, the
application must also supply local_type_to_netcs and
local_type_from_netcs stub conversion routines for this type.
Note
In this release, arrays of cs_char must be conformant. Subject to
additional restrictions, fixed and varying arrays may be used. See
the README file for details.
Related Information
Routines:
cs_byte_to_netcs
ΓòÉΓòÉΓòÉ 5.8.2. cs_byte_local_size ΓòÉΓòÉΓòÉ
Purpose
Calculates the necessary buffer size for code set conversion from a
network code set to a local code set. This routine is used by client
and server applications.
Format
#include <dce/codesets_stub.h>
void cs_byte_local_size(
rpc_binding_handle_t binding,
unsigned32 network_code_set_value,
unsigned32 network_buffer_size,
idl_cs_convert_t *conversion_type,
unsigned32 *local_buffer_size,
error_status_t *status);
Parameters
Input
binding Specifies the target binding handle from which to
obtain buffer size evaluation information. When called
from the client stub, this value is the binding handle
of a compatible server returned by the
rpc_ns_binding_import_next or rpc_ns_binding_select
routine. When called from the server stub, this value
is a pointer to binding information that the client
stub passed in the RPC call.
network_code_set_value The registered hexadecimal integer value that
represents the code set used to transmit character data
over the network. In general, the network code set is
the code set that the client application's code sets
evaluation routine has determined to be compatible for
this client and server. When the caller is the client
stub, this value is the receiving tag. When the caller
is the server stub, this value is the sending tag.
network_buffer_size The size, in units of idl_byte, of the buffer
that is allocated for the international character data.
For a conformant array, this value is the network value
of the size_is variable for the array; that is, the
value is the size of the unmarshalled string if no
conversion is done.
Output
conversion_type A pointer to the enumerated type defined in
dce/idlbase.h that indicates whether data conversion is
necessary and whether the existing buffer is sufficient
for storing the results of the conversion. The
conversion type can be one of the following values:
idl_cs_no_convert No code set conversion is
required.
idl_cs_new_buffer_convert The converted data must
be written to a new
buffer.
local_buffer_size A pointer to the buffer size that needs to be
allocated to contain the converted data, in units of
idl_byte. This value is to be used as the local value
of the size_is variable for the array, and is non-NULL
if a conformant array is to be unmarshalled.
status Returns the status code from this routine. On
successful completion, the routine returns rpc_s_ok.
Otherwise, it returns rpc_s_ss_incompatible_codesets,
which indicates that the specified code set does not
match the code set specified in the sending tag in the
binding handle. If this error occurs in the server
stub, an exception is raised to the client application.
When called from the server stub, this routine calls
the routines dce_cs_loc_to_rgy and
rpc_rgy_get_max_bytes. If either of these routines
returns an error, the cs_byte_local_size routine raises
an exception to the client application.
Usage
The cs_byte_local_size routine belongs to a set of DCE RPC routines
for use by client and server applications that are transferring
international character data in a heterogeneous character set and
code sets environment.
The cs_byte_local_size routine is one of the DCE RPC buffer sizing
routines that RPC stubs use before they marshall or unmarshall data
to determine whether the buffers allocated for code set conversion
need to be enlarged to hold the converted data. The buffer sizing
routines determine the type of conversion required and calculate the
size of the necessary buffer (if a new one is required); the RPC stub
then allocates a buffer of that size before it calls one of the code
set conversion routines.
Client and server stubs call the cs_byte_xxx_size routines when the
cs_byte type has been specified as the local data type using the
cs_char attribute in the attribute configuration file for the
application.
Applications do not call the cs_byte_local_size routine directly.
Client and server stubs call the routine before they unmarshall any
data. The stubs pass the routine a binding handle and a code set
value that identifies the code set that was used to transfer
international character data over the network. The stubs also specify
the network storage size of the data, in units of idl_byte, if a
conformant array is to be unmarshalled.
When called from a client stub, the cs_byte_local_size routine
determines the value of conversion_type from the client and server's
code set tag information stored in the binding handle by a code sets
evaluation routine or a tag-setting routine. If the conversion type
specified in the handle is idl_cs_new_buffer_convert, the routine
sets the conversion_type parameter to this value and, if a conformant
array is to be unmarshalled, calculates a new buffer size by
multiplying the value of local_buffer_size by the c_max_bytes value
and by an expansion factor for the code set specified in
network_code_set_value. The routine returns the new buffer size in
the local_buffer_size parameter. The size is specified in units of
cs_byte, which is the local representation used for international
character data (and is equivalent to the byte data type).
If the handle information specifies idl_cs_no_convert, the routine
assumes that no conversion is necessary and returns idl_cs_no_convert
in the conversion_type parameter. The routine also returns the value
of network_buffer_size in local_buffer_size if a conformant array is
to be marshalled.
In cases where the binding handle does not contain the results of
character and code sets evaluation, or where it is being called from
the server stub, the cs_byte_local_size routine determines the value
of conversion_type itself using the local code set value and the code
set value passed in the network_code_set_value parameter and returns
the appropriate conversion_type value. If a conformant array is to be
unmarshalled, and the routine finds that a new buffer is required to
hold the converted data, the routine calculates the size of this new
buffer (by multiplying the value of network_buffer_size by the local
code set c_max_bytes value and by an expansion factor) and returns
the results in units of cs_byte in local_buffer_size.
Note
In this release, arrays of cs_char must be conformant. Subject to
additional restrictions, fixed and varying arrays may be used. See
the README file for details.
Related Information
Routines:
cs_byte_net_size
ΓòÉΓòÉΓòÉ 5.8.3. cs_byte_net_size ΓòÉΓòÉΓòÉ
Purpose
Calculates the necessary buffer size for code set conversion from a
local code set to a network code set. This routine is used by client
and server applications.
Format
#include <dce/codesets_stub.h>
void cs_byte_net_size(
rpc_binding_handle_t binding,
unsigned32 network_code_set_value,
unsigned32 local_buffer_size,
idl_cs_convert_t *conversion_type,
unsigned32 *network_buffer_size,
error_status_t *status);
Parameters
Input
binding Specifies the target binding handle from which to
obtain buffer size evaluation information. When called
from the client stub, this value is the binding handle
of a compatible server returned by the
rpc_ns_binding_import_next or rpc_ns_binding_select
routine. When called from the server stub, this value
is a pointer to binding information that the client
stub passed in the RPC call.
network_code_set_value The registered hexadecimal integer value that
represents the code set to be used to transmit
character data over the network. In general, the
network code set is the code set that the client
application's code sets evaluation routine has
determined to be compatible for this client and server.
When the caller is the client stub, this value is the
sending tag. When the caller is the server stub, this
value is the receiving tag.
local_buffer_size The size, in units of idl_byte, of the buffer that
is allocated for the international character data. This
value is the local value of the size_is variable for
the array; that is, the value is the size of the
marshalled string if no conversion is done.
Output
conversion_type A pointer to the enumerated type defined in
dce/idlbase.h that indicates whether data conversion is
necessary and whether existing storage is sufficient
for storing the results of the conversion. The
conversion type can be one of the following values:
idl_cs_no_convert No code set conversion is
required.
idl_cs_new_buffer_convert The converted data must
be written to a new
buffer.
network_buffer_size A pointer to the buffer size that needs to be
allocated to contain the converted data, in units of
idl_byte. This value is to be used as the network value
of the size_is variable for the array, and is non-NULL
if a conformant array is to be marshalled.
status Returns the status code from this routine. On
successful completion, the routine returns rpc_s_ok.
Otherwise, it returns rpc_s_ss_incompatible_codesets,
which indicates that the specified code set does not
match the code set specified in the sending tag in the
binding handle. If this error occurs in the server
stub, an exception is raised to the client application.
When called from the server stub, this routine calls
the routines dcs_cs_loc_to_rgy and
rpc_rgy_get_max_bytes. If either of these routines
returns an error, the cs_byte_net_size routine raises
an exception to the client application.
Usage
The cs_byte_net_size routine belongs to a set of DCE RPC routines for
use by client and server applications that are transferring
international character data in a heterogeneous character set and
code sets environment.
The cs_byte_net_size routine is one of the DCE RPC buffer sizing
routines that RPC stubs use before they marshall or unmarshall data
to determine whether the buffers allocated for code set conversion
need to be enlarged to hold the converted data. The buffer sizing
routines determine the type of conversion required and calculate the
size of the necessary buffer (if a new one is required). The RPC stub
then allocates a buffer of that size before it calls one of the code
set conversion routines.
Client and server stubs call the cs_byte_xxx_size routines when the
cs_byte type (which is equivalent to byte) has been specified as the
local data type using the cs_char attribute in the attribute
configuration file for the application. Applications do not call the
cs_byte_net_size routine directly. Client and server stubs call the
routine before they marshall any data. The stubs pass the routine a
binding handle and a code set value that identifies the code set to
be used to transfer international character data over the network.
The stubs also specify the local storage size of the data, in units
of byte.
When called from a client stub, the cs_byte_net_size routine
determines the value of conversion_type from the client and server's
code set tag information and set up the binding handle by a code sets
evaluation routine or a tag-setting routine. If the conversion type
specified in the handle is idl_cs_new_buffer_convert, the routine
sets the conversion_type parameter to this value and, if a conformant
array is to be marshalled, calculates a new buffer size by
multiplying the value of local_buffer_size by the c_max_bytes value
for the code set specified in network_code_set_value (the sending tag
parameter) and by an expansion factor.
The routine returns the new buffer size in the network_buffer_size
parameter. The size is specified in units of cs_byte, which is the
network representation used for international character data (and is
equivalent to the byte type).
If the handle information specifies idl_cs_no_convert, the routine
assumes that no conversion is necessary and returns idl_cs_no_convert
in the conversion_type parameter. The routine also returns the value
of local_buffer_size in network_buffer_size if a conformant array is
to be marshalled.
In cases where the binding handle does not contain the results of
character and code sets evaluation, or where it is being called from
the server stub, the cs_byte_net_size routine determines the value of
conversion_type itself using the local code set value and the code
set value passed in the network_code_set_value parameter and returns
the appropriate conversion_type value. If a conformant array is to be
marshalled, and the routine finds that a new buffer is required to
hold the converted data, the routine calculates the size of this new
buffer (by multiplying the value of local_buffer_size by the network
code set c_max_bytes value and by an expansion factor) and returns
the results, in units of cs_byte, in network_buffer_size.
Note
In this release, arrays of cs_char must be conformant. Subject to
additional restrictions, fixed and varying arrays may be used. See
the README file for details.
Related Information
Routines:
cs_byte_local_size
ΓòÉΓòÉΓòÉ 5.8.4. cs_byte_to_netcs ΓòÉΓòÉΓòÉ
Purpose
Converts international character data from a local code set to a
network code set. This routine is used by client and server
applications.
Format
#include <dce/codesets_stub.h>
void cs_byte_to_netcs(
rpc_binding_handle_t binding,
unsigned32 network_code_set_value,
idl_byte *local_data,
unsigned32 local_data_length,
idl_byte *network_data,
unsigned32 *network_data_length,
error_status_t *status);
Parameters
Input
binding Specifies the target binding handle from which to
obtain code set conversion information. When called
from the client stub, this value is the binding handle
of a compatible server returned by the
rpc_ns_binding_import_next or rpc_ns_binding_select
routine. When called from the server stub, this value
is a pointer to binding information that the client
stub passed in the RPC call.
network_code_set_value The registered hexadecimal integer value that
represents the code set to be used to transmit
character data over the network. In general, the
network code set is the code set that the client
application's code sets evaluation routine has
determined to be compatible for this client and server.
When the caller is the client stub, this value is the
sending tag. When the caller is the server stub, this
value is the receiving tag.
local_data A pointer to the international character data to be
transmitted, in the local code set encoding.
local_data_length The number of idl_byte data elements to be
converted. For a conformant array, this value is the
local value of the size_is variable.
Output
network_data A pointer to the converted data, in units of idl_byte.
network_data_length A pointer to the length of the converted data, in
units of idl_byte.
status Returns the status code from this routine. On
successful completion, the routine returns rpc_s_ok.
Otherwise, it returns rpc_s_ss_incompatible_codesets,
which indicates that the specified code set does not
match the code set specified in the sending tag in the
binding handle. If this error occurs in the server
stub, an exception is raised to the client application.
When running the host converter, the following errors
can occur:
rpc_s_ss_invalid_char_input
rpc_s_ss_short_conv_buffer
rpc_s_ss_iconv_error (HP-UX reference platform
only)
rpc_s_ss_no_memory (HP-UX reference platform
only)
When called from the server stub, the routine calls the
dce_cs_loc_to_rgy routine and the host converter routines. If these
routines return an error, an exception is raised to the client
application.
Usage
The cs_byte_to_netcs routine belongs to a set of DCE RPC routines for
use by client and server applications that are transferring
international character data in a heterogeneous character set and
code sets environment.
The cs_byte_to_netcs routine is one of the DCE RPC stub code set
conversion routines that RPC stubs use before they marshall or
unmarshall data to convert international character data to and from
local and network code sets.
Client and server stubs call the cs_byte_xxx_netcs routines when the
cs_byte type has been specified as the local data type using the
cs_char attribute in the attribute configuration file for the
application. (The cs_byte type is equivalent to the byte type.)
Client and server stubs call the cs_byte_to_netcs routine before they
marshall any data. The routine takes a binding handle, a code set
value that identifies the code set to be used to transfer
international character data over the network, the address of the
data to be converted, and the length of the data to be converted, in
units of idl_byte.
The routine compares the code set specified as the network code set
to the local code set currently in use. If the routine finds that
code set conversion is necessary (because the local code set differs
from the code set specified to be used on the network), it determines
which host code set converter to call to convert the data and then
calls that converter.
The routine then returns the converted data, in idl_byte format. If
the data is a conformant array, the routine also returns the length
of the converted data, in units of idl_byte.
Applications can specify local data types other than cs_byte (the
local data type for which DCE RPC supplies stub code set conversion
routines) with the cs_char ACF attribute. In this case, the
application must also supply local_type_to_netcs and
local_type_from_netcs stub conversion routines for this type.
Note
In this release, arrays of cs_char must be conformant. Subject to
additional restrictions, fixed and varying arrays may be used. See
the README file for details.
Related Information
Routines:
cs_byte_from_netcs
ΓòÉΓòÉΓòÉ 5.8.5. dce_cs_loc_to_rgy ΓòÉΓòÉΓòÉ
Purpose
Maps a local name for a code set to a code set value in the code set
registry. This routine is used by client and server applications.
Format
#include <dce/rpc.h>
void dce_cs_loc_to_rgy(
idl_char *local_code_set_name,
unsigned32 *rgy_code_set_value,
unsigned16 *rgy_char_sets_number,
unsigned16 **rgy_char_sets_value,
error_status_t *status);
Parameters
Input
local_code_set_name A string that specifies the name that the local
host's locale environment uses to refer to the code
set. The string is a maximum of 32 bytes: 31 character
data bytes plus a terminating NULL character.
Output
rgy_code_set_value The registered integer value that uniquely
identifies the code set specified by
local_code_set_name.
rgy_char_sets_number The number of character sets that the specified
code set encodes. Specifying NULL prevents this routine
from returning this parameter.
rgy_char_sets_value A pointer to an array of registered integer
values that uniquely identify the character sets that
the specified code set encodes. Specifying NULL
prevents this routine from returning this parameter.
The routine dynamically allocates this value.
status Returns the status code from this routine. On
successful completion, the routine returns dce_cs_c_ok.
Otherwise, it returns one of the following errors:
dce_cs_c_cannot_allocate_memory
dce_cs_c_cannot_open_file
dce_cs_c_cannot_read_file
dce_cs_c_unknown
dce_cs_c_not_found
Usage
The dce_cs_loc_to_rgy routine is a DCE function that maps operating
system-specific names for character/code set encodings to their
unique identifiers in the code set registry.
The routine is currently used by the DCE RPC routines for character
and code set interoperability, which permit DCE RPC clients and
servers to transfer international character data in a heterogeneous
character set and code sets environment.
The dce_cs_loc_to_rgy routine takes as input a string that holds the
host-specific local name of a code set and returns the corresponding
integer value that uniquely identifies that code set, as registered
in the host's code set registry. If the integer value does not exist
in the registry, the routine returns the status dce_cs_c_unknown. The
routine also returns the number of character sets that the code set
encodes and the registered integer values that uniquely identify
those character sets. Specifying NULL in the rgy_char_sets_number and
rgy_char_sets_value parameters prevents the routine from performing
the additional search for these values. Applications that want only
to obtain a code set value from the code set registry can specify
NULL for these parameters in order to improve the routine's
performance. If the value is returned from the routine, application
developers should free the array after it is used, since the array is
dynamically allocated.
The DCE RPC stub support routines for code set conversion can use
this routine to obtain the registered code set value that corresponds
to the code set they are currently using; that is, the local code set
specified in their host's locale environment. The stub routines for
code set conversion then compare their local code set value to the
code set value specified in the sending tag for the call to determine
whether code set conversion is necessary.
In general, programmers who are developing RPC applications that
transfer international characters do not need to call this routine
directly; the DCE RPC routines provided for code sets evaluation and
the DCE RPC stub support routines for code set conversion call this
routine on the client or server application's behalf.
However, programmers who are developing their own stub support
routines for code set conversion may want to include this routine in
their conversion code to map their current locale information to a
code set value in order to perform local-to-sending tag code set
comparison.
Related Information
Routines:
cs_byte_from_netcs
cs_byte_local_size
cs_byte_net_size
cs_byte_to_netcs
dce_cf_get_csrgy_filename
dce_cs_rgy_to_loc
rpc_rgy_get_codesets
ΓòÉΓòÉΓòÉ 5.8.6. dce_cs_rgy_to_loc ΓòÉΓòÉΓòÉ
Purpose
Maps a code set value in the code set registry to the local name for
a code set. This routine is used by client and server applications.
Format
#include <dce/rpc.h>
void dce_cs_rgy_to_loc(
unsigned32 *rgy_code_set_value,
idl_char **local_code_set_name,
unsigned16 *rgy_char_sets_number,
unsigned16 **rgy_char_sets_value,
error_status_t *status);
Parameters
Input
rgy_code_set_value The registered hexadecimal value that uniquely
identifies the code set.
Output
local_code_set_name A string that specifies the name that the local
host's locale environment uses to refer to the code
set. The string is a maximum of 32 bytes: 31 character
data bytes and a terminating NULL character.
rgy_char_sets_number The number of character sets that the specified
code set encodes. Specifying NULL in this parameter
prevents the routine from returning this value.
rgy_char_sets_value A pointer to an array of registered integer
values that uniquely identify the character sets that
the specified code set encodes. Specifying NULL in this
parameter prevents the routine from returning this
value. The routine dynamically allocates this value.
status Returns the status code from this routine. On
successful completion, the routine returns dce_cs_c_ok.
Otherwise, it returns one of the following errors:
dce_cs_c_cannot_allocate_memory
dce_cs_c_cannot_open_file
dce_cs_c_cannot_read_file
dce_cs_c_unknown
dce_cs_c_not_found
Usage
The dce_cs_rgy_to_loc routine is a DCE function that maps a unique
identifier for a code set in the code set registry to the operating
system-specific name for the code set, if it exists in the code set
registry.
The routine is currently used by the DCE RPC routines for character
and code set interoperability, which permit DCE applications to
transfer international characters in a heterogeneous character and
code sets environment.
The dce_cs_rgy_to_loc routine takes as input a registered integer
value of a code set and returns a string that holds the operating
system-specific, or local name, of the code set.
If the local code set name does not exist in the registry, the
routine returns the status dce_cs_c_unknown and returns an undefined
string.
The routine also returns the number of character sets that the code
set encodes and the registered integer values that uniquely identify
those character sets. Specifying NULL in the rgy_char_sets_number and
rgy_char_sets_value parameters prevents the routine from performing
the additional search for these values. Applications that want only
to obtain a local code set name from the code set registry can
specify NULL for these parameters in order to improve the routine's
performance. If the value is returned from the routine, application
developers should free the rgy_char_sets_value array after it is
used.
In general, client and server applications that use the DCE RPC
character and code set interoperablity features do not need to call
this routine directly; the DCE RPC stub support routines provided for
code set conversion call this routine on the client or server
application's behalf to obtain the string name that matches the name
of the host code set converter that they will call to perform the
actual code set conversion.
However, application programmers who are developing their own RPC
stub support routines for code set conversion might want to include
this routine in their conversion code to map code set values sent in
code set tags into the local names for the code sets so that they can
locate the correct operating system code set converter.
Related Information
Routines:
dce_cf_get_csrgy_filename
dce_cs_loc_to_rgy
rpc_rgy_get_codesets
ΓòÉΓòÉΓòÉ 5.8.7. idl_es_decode_buffer ΓòÉΓòÉΓòÉ
Purpose
Returns a buffer decoding handle to the IDL encoding services.
Format
void idl_es_decode_buffer(
idl_byte *encoded_data_buffer,
idl_ulong_int buffer_size,
idl_es_handle_t *es_handle,
error_status_t *status);
Parameters
Input
encoded_data_buffer The address of the buffer that contains the data
to be decoded.
buffer_size The number of bytes of data in the buffer to be
decoded.
Output
es_handle Returns the address of an IDL encoding services handle
for use by a client or server decoding operation.
status Returns the status code from this routine. On
successful completion, the routine returns rpc_s_ok.
Otherwise, it returns one of the following errors:
rpc_s_ss_bad_buffer Bad buffer operation.
rpc_s_no_memory Insufficient memory is available
to complete the operation.
Usage
The IDL encoding services provide client and server RPC applications
with a method for encoding data types in input parameters into a byte
stream and decoding data types in output parameters from a byte
stream without calling the RPC runtime. Encoding and decoding
operations are analogous to marshalling and unmarshalling, except
that the data is stored locally, and is not transmitted over the
network. Client and server applications can use the IDL encoding
services to create persistent storage for their data. Encoding
flattens complex data types into a byte stream for storage on disk,
while decoding restores the flattened data to complex form.
The idl_es_decode_buffer routine belongs to a set of routines that
return handles to the IDL encoding services for use by client and
server encoding and decoding operations. The information in the
handle controls the way in which the IDL encoding services manage
memory when encoding or decoding data.
The idl_es_decode_buffer routine returns a buffer decoding handle,
which directs the IDL encoding services to decode data from a single
application-supplied buffer of encoded data.
Related Information
Routine:
idl_es_decode_incremental
ΓòÉΓòÉΓòÉ 5.8.8. idl_es_decode_incremental ΓòÉΓòÉΓòÉ
Purpose
Returns an incremental decoding handle to the IDL encoding services.
This routine is used by client and server applications.
Format
void idl_es_decode_incremental(
idl_void_p_t state,
idl_es_read_fn_t read_fn,
idl_es_handle_t *es_handle,
error_status_t *status);
Parameters
Input/Output
state Specifies the address of an application-provided data
structure that coordinates the actions of successive
calls to the routine specified in read_fn. The state
data structure acts as a communications channel between
the application and the read_fn routine.
Input
read_fn Specifies the address of a user-provided routine that
generates a buffer of encoded data for decoding by the
IDL encoding services. The IDL encoding services call
the routine in read_fn repeatedly until all of the data
has been decoded.
The following C definition for idl_es_read_fn_t
illustrates the prototype for the read_fn routine:
typedef void (*idl_es_read_fn_t)
(
idl_void_p_t state, /* in/out */
idl_byte **buffer, /* in */
idl_ulong_int *size, /* in */
);
The idl_es_decode_incremental routine passes the
specified state parameter value as input to the routine
in read_fn. The state data structure is the
communications path between the application and the
read_fn routine. For example, the application can use
the state parameter to pass in an open file pointer
from which the read_fn routine is to read encoded data.
The buffer parameter specifies the address of the data
to be decoded; this address must be 8-byte aligned. The
size parameter specifies the size of the buffer to be
decoded, and must be a multiple of 8 bytes unless it
represents the size of the last buffer to be decoded.
The read_fn routine should return an exception on
error.
Output
es_handle Returns the address of an IDL encoding services handle
for use by a client or server decoding operation.
status Returns the status code from this routine. On
successful completion, the routine returns rpc_s_ok.
Otherwise, it returns rpc_s_no_memory, which indicates
that insufficient memory is available to complete the
operation.
Usage
The IDL encoding services provide client and server RPC applications
with a method for encoding data types in input parameters into a byte
stream and decoding data types in output parameters from a byte
stream without calling the RPC runtime. Encoding and decoding
operations are analogous to marshalling and unmarshalling, except
that the data is stored locally and is not transmitted over the
network. Client and server applications can use the IDL encoding
services to create persistent storage for their data. Encoding
flattens complex data types into a byte stream for storage on disk,
while decoding restores the flattened data to complex form.
The idl_es_decode_incremental routine belongs to a set of routines
that return handles to the IDL encoding services for use by client
and server encoding and decoding operations. The information in the
handle controls the way in which the IDL encoding services manage
memory when encoding or decoding data.
The idl_es_decode_incremental routine returns an incremental decoding
handle, which directs the IDL encoding services to decode data by
calling the user-supplied read_fn routine, which generates a small
buffer of encoded data for the IDL encoding services to decode. The
routine passes the buffer address and size to the IDL encoding
services, which then decode the buffer. The IDL encoding services
call the read_fn routine repeatedly until there is no more data to
decode.
Related Information
Routines:
idl_es_decode_buffer
idl_es_encode_incremental
ΓòÉΓòÉΓòÉ 5.8.9. idl_es_encode_dyn_buffer ΓòÉΓòÉΓòÉ
Purpose
Returns a dynamic buffer encoding handle to the IDL encoding
services.
This routine is used by client and server applications.
Format
void idl_es_encode_dyn_buffer(
idl_byte **encoded_data_buffer,
idl_ulong_int *buffer_size,
idl_es_handle_t *es_handle,
error_status_t *status);
Parameters
Output
encoded_data_buffer The address to which the IDL encoding services
writes the address of the buffer that contains the
encoded data, when the encoding process is complete.
When the application no longer needs the buffer, it
should release the memory resource. See the DCE for
OS/2 Warp: Administration Guide for an explanation of
how to manage memory when using the IDL encoding
services.
buffer_size The address to which the IDL encoding services writes
the size of the buffer that contains the encoded data
when the encoding process is complete.
es_handle Returns the address of an IDL encoding services handle
for use by a client or server encoding operation.
status Returns the status code from this routine. On
successful completion, the routine returns rpc_s_ok.
Otherwise, it returns one of the following errors:
rpc_s_ss_bad_buffer Bad buffer operation.
rpc_s_no_memory Insufficient memory is available
to complete the operation.
Usage
The IDL encoding services provide client and server RPC applications
with a method for encoding data types in input parameters into a byte
stream and decoding data types in output parameters from a byte
stream without calling the RPC runtime. Encoding and decoding
operations are analogous to marshalling and unmarshalling, except
that the data is stored locally, and is not transmitted over the
network. Client and server applications can use the IDL encoding
services to create persistent storage for their data. Encoding
flattens complex data types into a byte stream for storage on disk,
while decoding restores the flattened data to complex form.
The idl_es_encode_dyn_buffer routine belongs to a set of routines
that return handles to the IDL encoding services for use by client
and server encoding and decoding operations. The information in the
handle controls the way in which the IDL encoding services manage
memory when encoding or decoding data.
The idl_es_encode_dyn_buffer routine returns a dynamic buffer
encoding handle, which directs the IDL encoding services to store the
encoded data in a chain of small buffers, build an additional single
buffer that contains the encoded data, and pass that buffer's address
to the application. Dynamic buffering is the most expensive style of
IDL encoding services buffering, since two copies of the encoded data
exist (one in the chain of buffers, and one in the single buffer).
Related Information
Routines:
idl_es_encode_fixed_buffer
idl_es_encode_incremental
ΓòÉΓòÉΓòÉ 5.8.10. idl_es_encode_fixed_buffer ΓòÉΓòÉΓòÉ
Purpose
Returns a fixed buffer encoding handle to the IDL encoding services.
Format
void idl_es_encode_fixed_buffer(
idl_byte *data_buffer,
idl_ulong_int data_buffer_size,
idl_ulong_int *encoded_buffer_size,
idl_es_handle_t *es_handle,
error_status_t *status);
Parameters
Input
data_buffer The address of the application-supplied buffer. This
address must be 8-byte aligned.
data_buffer_size The size of the application-supplied buffer. The
size must be a multiple of 8 bytes.
Output
encoded_buffer_size Returns the address to which the IDL encoding
services write the size of the encoded buffer when they
have completed encoding the data.
es_handle Returns the address of an IDL encoding services handle
for use by a client or server encoding operation.
status Returns the status code from this routine. On
successful completion, the routine returns rpc_s_ok.
Otherwise, it returns one of the following errors:
rpc_s_bad_buffer Bad buffer operation.
rpc_s_no_memory Insufficient memory is available
to complete the operation.
Usage
The IDL encoding services provide client and server RPC applications
with a method for encoding data types in input parameters into a byte
stream and decoding data types in output parameters from a byte
stream without calling the RPC runtime. Encoding and decoding
operations are analogous to marshalling and unmarshalling, except
that the data is stored locally, and is not transmitted over the
network. Client and server applications can use the IDL encoding
services to create persistent storage for their data. Encoding
flattens complex data types into a byte stream for storage on disk,
while decoding restores the flattened data to complex form.
The idl_es_encode_fixed_buffer routine belongs to a set of routines
that return handles to the IDL encoding services for use by client
and server encoding and decoding operations. The information in the
handle controls the way in which the IDL encoding services manage
memory when encoding or decoding data.
The idl_es_encode_fixed_buffer routine returns a fixed buffer
encoding handle, which directs the IDL encoding services to encode
data into a single buffer that the application has provided. The
fixed buffer encoding style is useful for applications that need only
one buffer for their encoding and decoding process. The buffer that
the application allocates must be large enough to hold all of the
encoded data, and must also allocate 56 bytes for each encoding
operation that the application has defined (this space is used to
hold per-operation header information.)
Related Information
Routines:
idl_es_encode_dyn_buffer
idl_es_encode_incremental
ΓòÉΓòÉΓòÉ 5.8.11. idl_es_encode_incremental ΓòÉΓòÉΓòÉ
Purpose
Returns an incremental encoding handle to the IDL encoding services.
This routine is used by client and server applications.
Format
void idl_es_encode_incremental(
idl_void_p_t state,
idl_es_allocate_fn_t allocate_fn,
idl_es_write_fn_t write_fn,
idl_es_handle_t *es_handle,
error_status_t *status);
Parameters
Input/Output
state Specifies the address of an application-provided data
structure that coordinates the actions of the routines
in allocate_fn and write_fn. The state data structure
acts as a communications channel between the
application and the allocate_fn and write_fn routines.
Input
allocate_fn Specifies the address of a user-provided routine that
allocates an empty buffer. The encoding stub uses the
allocated buffer to store encoded data.
The following C definition for idl_es_allocate_fn_t
illustrates the prototype for the buffer allocation
routine:
typedef void (*idl_es_allocate_fn_t)
(
idl_void_p_t state, /* in/out */
idl_byte **buffer, /* out */
idl_ulong_int *size, /* in/out */
);
The idl_es_encode_incremental routine passes the
specified state parameter value as input to the
allocate_fn buffer allocation routine. When the IDL
encoding services call the allocate_fn routine, the
value at the address indicated by size represents the
buffer size that the IDL encoding services have
requested the routine to allocate. When the allocate_fn
buffer allocation routine allocates the buffer, it
writes the actual size of the allocated buffer to this
parameter; the value must be a multiple of eight bytes.
The buffer parameter specifies the address of the
allocated buffer; this address must be 8-byte aligned.
The allocate_fn routine should return an exception on
error.
write_fn Specifies the address of a user-provided routine that
writes the contents of a buffer that contains data that
has been encoded by the IDL encoding services. The IDL
encoding services call this routine when the buffer
allocated by allocate_fn is full, or when all of the
application's encoding operation parameters have been
encoded.
The following C definition for idl_es_write_fn_t
illustrates the prototype for the write_fn routine:
typedef void (*idl_es_write_fn_t)
(
idl_void_p_t state, /* in/out */
idl_byte *buffer, /* in */
idl_ulong_int size, /* in */
);
The idl_es_encode_incremental routine passes the
specified state parameter value as input to the
write_fn routine. The buffer parameter value is the
address of the data that the IDL encoding services have
encoded. The size parameter value is the size, in
bytes, of the encoded data.
The write_fn routine should return an exception on
error.
Output
es_handle Returns the address of an IDL encoding services handle
for use by a client or server encoding operation.
status Returns the status code from this routine. On
successful completion, the routine returns rpc_s_ok.
Otherwise, it returns rpc_s_no_memory, which indicates
that insufficient memory is available to complete the
operation.
Usage
The IDL encoding services provide client and server RPC applications
with a method for encoding data types in input parameters into a byte
stream and decoding data types in output parameters from a byte
stream without calling the RPC runtime. Encoding and decoding
operations are analogous to marshalling and unmarshalling, except
that the data is stored locally, and is not transmitted over the
network. Client and server applications can use the IDL encoding
services to create persistent storage for their data. Encoding
flattens complex data types into a byte stream for storage on disk,
while decoding restores the flattened data to complex form.
The idl_es_encode_incremental routine belongs to a set of routines
that return handles to the IDL encoding services for use by client
and server encoding and decoding operations. The information in the
handle controls the way in which the IDL encoding services manage
memory when encoding or decoding data.
The idl_es_encode_incremental routine returns an incremental encoding
handle, which directs the IDL encoding services to encode data into a
chain of small buffers that the user-provided allocate_fn routine
manages. The user-provided write_fn routine writes the encoded data
in these buffers back for access by the application.
The state data structure is the communications path between the
application and the routines in allocate_fn and write_fn. For
example, the application can build a cache of pre-allocated memory to
store encoded data, and store pointers to that pre-allocated memory
in the state data structure. When called by the IDL encoding services
to allocate a buffer, the allocate_fn routine can search the state
data structure for a free memory location to use.
Related Information
Routines:
idl_es_decode_incremental
idl_es_encode_dyn_buffer
idl_es_encode_fixed_buffer
ΓòÉΓòÉΓòÉ 5.8.12. idl_es_handle_free ΓòÉΓòÉΓòÉ
Purpose
Frees an IDL encoding services handle.
Format
void idl_es_handle_free(
idl_es_handle_t *es_handle,
error_status_t *status);
Parameters
Input/Output
es_handle The address of the handle whose resources are to be
freed. The handle is made NULL by this operation.
Output
status Returns the status code from this routine. On
successful completion, the routine returns rpc_s_ok.
Otherwise, it returns an error.
Usage
The idl_es_handle_free routine frees an IDL encoding services handle
that has been allocated by one of the IDL encoding services
handle-returning routines.
Related Information
Routines:
idl_es_decode_buffer
idl_es_decode_incremental
idl_es_encode_dyn_buffer
idl_es_encode_fixed_buffer
idl_es_encode_incremental
ΓòÉΓòÉΓòÉ 5.8.13. idl_es_inq_attrs ΓòÉΓòÉΓòÉ
Purpose
Returns the flags from an IDL encoding services handle.
Format
void idl_es_inq_attrs(
idl_es_handle_t es_handle,
unsigned32 *flags,
error_status_t *status);
Parameters
Input
es_handle An encoding services handle returned by one of the IDL
encoding services routines.
Output
flags Returns the flags stored in the IDL encoding services
handle that is associated with the encoded data.
status Returns the status code from this routine. The possible
status code is rpc_s_ok, which indicates success.
Usage
The idl_es_inq_attrs routine returns the flags stored in the IDL
encoding services handle that is associated with the encoded data.
Applications can use the idl_es_set_attrs routine to set the flags.
Currently, the only valid flag that can be set is
IDL_ES_NO_ENCODING_CHECK, which tells the encoding services to not
check the interface ID so an interface that did not encode data can
decode parts of it, such as a common header.
Related Information
Routines:
idl_es_set_attrs
idl_es_set_transfer_syntax
ΓòÉΓòÉΓòÉ 5.8.14. idl_es_inq_encoding_id ΓòÉΓòÉΓòÉ
Purpose
Identifies an operation within an interface that has been called to
encode data using the IDL encoding services.
Format
void idl_es_inq_encoding_id(
idl_es_handle_t es_handle,
rpc_if_id_t *if_id,
idl_ulong_int *op_num,
error_status_t *status);
Parameters
Input
es_handle An encoding services handle returned by one of the IDL
encoding services handle-returning routines.
Output
if_id Returns the interface UUID and version number assigned
to the interface that defines the operation that
encoded the data. This information is stored in the IDL
encoding services handle that is associated with the
encoded data.
op_num Returns the operation number assigned to the operation
that encoded the data. Operations are numbered in the
order in which they appear in the interface definition,
starting with zero (0). The operation number for the
operation that encoded the data is stored in the IDL
encoding services handle that is associated with the
encoded data.
status Returns the status code from this routine. On
successful completion, the routine returns rpc_s_ok.
Otherwise, it returns rpc_s_unknown_if, which indicates
that the interface identifier and operation number are
unavailable.
Usage
The IDL encoding services provide client and server RPC applications
with a method for encoding data types in input parameters into a byte
stream and decoding data types in output parameters from a byte
stream without calling the RPC runtime. Encoding and decoding
operations are analogous to marshalling and unmarshalling, except
that the data is stored locally, and is not transmitted over the
network. Client and server applications can use the IDL encoding
services to create persistent storage for their data. Encoding
flattens complex data types into a byte stream for storage on disk,
while decoding restores the flattened data to complex form.
The idl_es_inq_encoding_id routine returns the identity of an
operation within an application that has been used to encode data
using the IDL encoding services. Applications can use this routine to
determine the identity of an encoding operation, for example, before
calling their decoding operations.
Related Information
Routines:
idl_es_decode_buffer
idl_es_decode_incremental
idl_es_encode_dyn_buffer
idl_es_encode_fixed_buffer
idl_es_encode_incremental
ΓòÉΓòÉΓòÉ 5.8.15. idl_es_set_attrs ΓòÉΓòÉΓòÉ
Purpose
Sets attribute flags in an IDL encoding services handle.
Format
void idl_es_set_attrs(
idl_es_handle_t es_handle,
unsigned32 *flags,
error_status_t *status);
Parameters
Input
es_handle An encoding services handle returned by one of the IDL
encoding services routines.
flags Specifies the flags to be stored in association with
the IDL encoding services handle.
Output
status Returns the status code from this routine. The possible
status code is rpc_s_ok, which indicates success.
Usage
The idl_es_set_attrs routine sets the attribute flags to be stored in
the IDL encoding services handle that is associated with the encoded
data. Applications can use the idl_es_inq_attrs routine to get the
flags set by this routine. Currently, the only valid flag that can be
set is IDL_ES_NO_ENCODING_CHECK.
Using idl_es_set_attrs with the IDL_ES_NO_ENCODING_CHECK flag causes
IDL, during decoding, to not check the validity of the interface
UUIDs and version numbers. This allows an interface that did not
encode the data to decode it or parts of it, such as a common header.
Related Information
Routines:
idl_es_inq_attrs
idl_es_set_transfer_syntax
ΓòÉΓòÉΓòÉ 5.8.16. idl_es_set_transfer_syntax ΓòÉΓòÉΓòÉ
Purpose
Sets a transfer syntax.
Format
void idl_es_set_transfer_syntax(
idl_es_handle_t es_handle,
idl_es_transfer_syntax_t es_transfer_syntax,
error_status_t *status);
Parameters
Input/Output
es_handle Specifies the user's encoding services handle.
Input
es_transfer_syntax Specifies the requested transfer syntax.
Output
status Returns the status code from this routine. On
successful completion, the routine returns rpc_s_ok.
Otherwise, it returns rpc_s_tsyntaxes_unsupported,
which indicates that the transfer syntaxes are
unsupported.
Usage
The idl_es_set_transfer_syntax routine is a machinery for platforms
that support encodings in more than one transfer syntax. You must
call this routine before encoding data if you want a transfer syntax
other than the default. If only one transfer syntax is supported by
the platform, this routine can be used to explicitly specify the
transfer syntax. Currently, the only valid syntax that can be set is
idl_es_transfer_syntax_ndr.
Related Information
Routines:
idl_es_inq_attrs
idl_es_set_attrs
ΓòÉΓòÉΓòÉ 5.8.17. rpc_binding_copy ΓòÉΓòÉΓòÉ
Purpose
Returns a copy of a binding handle. This routine is used by client or
server applications.
Format
#include <dce/rpc.h>
void rpc_binding_copy(
rpc_binding_handle_t source_binding,
rpc_binding_handle_t *destination_binding,
unsigned32 *status);
Parameters
Input
source_binding Specifies the server binding handle whose referenced
binding information is copied.
Output
destination_binding Returns the server binding handle that refers to
the copied binding information.
status Returns the status code from this routine. On
successful completion, the routine returns rpc_s_ok.
Otherwise, it returns one of the following errors:
rpc_s_invalid_binding The binding handle is not
valid.
rpc_s_wrong_kind_of_binding Wrong kind of binding
for the operation.
Usage
The rpc_binding_copy routine copies the server binding information
referenced by the binding handle specified in the source_binding
parameter. This routine returns a new server binding handle for the
copied binding information. The new server binding handle is returned
in the destination_binding parameter.
Use the rpc_binding_copy routine if you want a change (made to
binding information by one thread) not to affect the binding
information used by other threads. See Binding Handle for more
details about the use of the rpc_binding_copy routine.
After calling this routine, operations performed on the
source_binding binding handle do not affect the binding information
referenced by the destination_binding binding handle. Similarly,
operations performed on the destination_binding binding handle do not
affect the binding information referenced by the source_binding
binding handle.
If you want the changes made to binding information by one thread to
affect the binding information used by other threads, your program
must share a single binding handle across the threads. In this case
the application controls binding handle concurrency.
When an application is finished using the binding handle specified by
the destination_binding parameter, the application calls the
rpc_binding_free routine to release the memory used by the
destination_binding binding handle and its referenced binding
information.
Related Information
Routines:
rpc_binding_free
ΓòÉΓòÉΓòÉ 5.8.18. rpc_binding_free ΓòÉΓòÉΓòÉ
Purpose
Releases binding handle resources. This routine is used by client or
server applications.
Format
#include <dce/rpc.h>
void rpc_binding_free(
rpc_binding_handle_t *binding,
unsigned32 *status);
Parameters
Input/Output
binding Specifies the server binding handle to free.
Output
status Returns the status code from this routine. On
successful completion, the routine returns rpc_s_ok.
Otherwise, it returns one of the following errors:
rpc_s_invalid_binding The binding handle is not
valid.
rpc_s_wrong_kind_of_binding Wrong kind of binding
for the operation.
Usage
The rpc_binding_free routine frees the memory used by a server
binding handle and its referenced binding information. Use this
routine when your application is finished using a server binding
handle that was dynamically created during program execution.
If the free-binding operation succeeds, the binding parameter returns
the value NULL.
An application can dynamically create binding handles by calling any
of the following routines:
o rpc_binding_copy
o rpc_binding_from_string_binding
o rpc_ns_binding_import_next
o rpc_ns_binding_select
o rpc_server_inq_bindings.
Related Information
Routines:
rpc_binding_copy
rpc_binding_from_string_binding
rpc_binding_vector_free
rpc_ns_binding_import_next
rpc_ns_binding_lookup_next
rpc_ns_binding_select
rpc_server_inq_bindings
ΓòÉΓòÉΓòÉ 5.8.19. rpc_binding_from_string_binding ΓòÉΓòÉΓòÉ
Purpose
Returns a binding handle from a string representation of a binding
handle. This routine is used by client or management applications.
Format
#include <dce/rpc.h>
void rpc_binding_from_string_binding(
unsigned_char_t *string_binding,
rpc_binding_handle_t *binding,
unsigned32 *status);
Parameters
Input
string_binding Specifies a string representation of a binding handle.
Output
binding Returns the server binding handle.
status Returns the status code from this routine. On
successful completion, the routine returns rpc_s_ok.
Otherwise, it returns one of the following errors:
rpc_s_invalid_arg The argument is not valid.
rpc_s_invalid_endpoint_format The endpoint format
is not valid.
rpc_s_invalid_rpc_protseq The protocol sequence is
not valid.
rpc_s_invalid_string_binding The string binding is
not valid.
rpc_s_protseq_not_supported Protocol sequence not
supported on this host.
uuid_s_bad_version Bad UUID version.
uuid_s_invalid_string_uuid The string UUID format
is not valid.
Usage
The rpc_binding_from_string_binding routine creates a server binding
handle from a string representation of a binding handle.
The string_binding parameter does not need to contain an object UUID.
In this case, the returned binding contains a nil UUID.
If the provided string_binding parameter does not contain an endpoint
field, the returned binding parameter is a partially bound server
binding handle.
If the provided string_binding parameter does contain an endpoint
field, the returned binding parameter is a fully bound server binding
handle with a well-known endpoint.
If the provided string_binding parameter does not contain a host
address field, the returned binding parameter refers to the local
host.
To create a string binding, call the rpc_string_binding_compose
routine or call the rpc_binding_to_string_binding routine or provide
a character string constant.
When an application finishes using the binding parameter, the
application calls the rpc_binding_free routine to release the memory
used by the binding handle.
See Binding Handle for an explanation of partially and fully bound
binding handles.
Related Information
Routines:
rpc_binding_copy
rpc_binding_free
rpc_binding_to_string_binding
rpc_string_binding_compose
ΓòÉΓòÉΓòÉ 5.8.20. rpc_binding_inq_auth_caller ΓòÉΓòÉΓòÉ
Purpose
Returns authentication and authorization information from the binding
handle for an authenticated client. This routine is used by server
applications.
Format
#include <dce/rpc.h>
#include <dce/id_base.h>
void rpc_binding_inq_auth_caller(
rpc_binding_handle_t binding_handle,
rpc_authz_cred_handle_t *privs,
unsigned_char_p_t *server_princ_name,
unsigned32 *protect_level,
unsigned32 *authn_svc,
unsigned32 *authz_svc,
unsigned32 *status);
Parameters
Input
binding_handle Specifies the client binding handle from which to
return the authentication and authorization
information.
Output
privs Returns an opaque handle to the authorization
information for the client that made the remote
procedure call on binding_handle. The data referenced
by this parameter is read-only and should not be
modified by the server. If the server wants to preserve
any of the returned data, it must copy the data into
server-allocated memory.
server_princ_name Returns a pointer to the server principal name
specified by the client that made the remote procedure
call on binding_handle. The content of the returned
name and its syntax is defined by the authentication
service in use.
Specifying NULL prevents the routine from returning
this parameter. In this case, the caller does not have
to call the rpc_string_free routine.
protect_level Returns the protection level requested by the client
that made the remote procedure call on binding_handle.
The protection level determines the degree to which
authenticated communications between the client and the
server are protected. Specifying NULL prevents the
routine from returning this parameter.
The possible protection levels are:
rpc_c_protect_level_default Uses the default
protection level for the
specified authentication
service.
rpc_c_protect_level_none Performs no protection.
rpc_c_protect_level_connect Performs protection
only when the client
establishes a
relationship with the
server.
rpc_c_protect_level_call Performs protection only
at the beginning of each
remote procedure call
when the server receives
the request.
rpc_c_protect_level_pkt Ensures that all data
received is from the
expected client.
rpc_c_protect_level_pkt_integ Ensures and verifies
that none of the data
transferred between
client and server has
been modified.
rpc_c_protect_level_cdmf_priv Performs protection
as specified by all of
the previous levels and
also encrypts each remote
procedure call parameter
value. This protection
level provides a little
lower level of packet
privacy than
rpc_c_protect_level_pkt_privacy.
rpc_c_protect_level_pkt_privacy Performs
protection as specified
by all of the previous
levels and also encrypts
each remote procedure
call argument value.
authn_svc Returns the authentication service requested by the
client that made the remote procedure call on
binding_handle. Specifying NULL prevents the routine
from returning this parameter.
The possible authentication services are:
rpc_c_authn_none No authentication.
rpc_c_authn_dce_secret DCE shared-secret key
authentication.
rpc_c_authn_dce_public DCE public key
authentication (reserved
for future use).
rpc_c_authn_default DCE default
authentication service.
authz_svc Returns the authorization service requested by the
client that made the remote procedure call on
binding_handle. Specifying NULL prevents the routine
from returning this parameter.
The possible authorization services are:
rpc_c_authz_none The server performs no
authorization. This is
valid only if the
authn_svc parameter is
rpc_c_authn_none.
rpc_c_authz_name The server performs
authorization based on
the client principal
name.
rpc_c_authz_dce The server performs
authorization using the
client's DCE privilege
attribute certificate
(PAC) sent to the server
with each remote
procedure call made with
binding_handle.
Generally, access is
checked against DCE
access control lists
(ACLs).
status Returns the status code from this routine. On
successful completion, the routine returns rpc_s_ok.
Otherwise, it returns one of the following errors:
rpc_s_invalid_binding
rpc_s_wrong_kind_of_binding
rpc_s_binding_has_no_auth
sec_login_s_default_use
sec_login_s_context_invalid
Usage
The rpc_binding_inq_auth_caller routine returns authentication and
authorization information associated with the client identified by
binding_handle. The calling server manager routine can use the
returned data for authorization purposes.
If the client is part of a delegation chain, the routine returns the
authentication and authorization information for each member of the
chain, the initiator, and all subsequent delegates. You can use the
sec_cred_get_initiator routine or sec_cred_get_delegate routines to
obtain the authorization information for a specific member of the
chain.
The RPC runtime allocates memory for the returned server_princ_name
parameter. The server is responsible for calling the rpc_string_free
routine for the returned parameter string.
For applications in which the client side uses the IDL auto_handle or
implicit_handle attribute, the server side needs to be built with the
IDL explicit_handle attribute specified in the attribute
configuration file (ACF). Using explicit_handle provides
binding_handle as the first parameter to each server manager routine.
Related Information
Routines: dce_acl_is_unauthenticated
rpc_binding_inq_auth_info
rpc_binding_set_auth_info
rpc_string_free
sec_cred_get_initiator
sec_cred_get_delegate
sec_cred_inq_auth_service_info
ΓòÉΓòÉΓòÉ 5.8.21. rpc_binding_inq_auth_client ΓòÉΓòÉΓòÉ
Purpose
Returns authentication and authorization information from the client
binding handle for an authenticated client. This routine is used by
server applications.
Format
#include <dce/rpc.h>
#include <dce/id_base.h>
void rpc_binding_inq_auth_client(
rpc_binding_handle_t binding,
rpc_authz_handle_t *privs,
unsigned_char_t **server_princ_name,
unsigned32 *protect_level,
unsigned32 *authn_svc,
unsigned32 *authz_svc,
unsigned32 *status);
Parameters
Input
binding Specifies the client binding handle from which to
return the authentication and authorization
information.
Output
privs Returns a handle to the authorization information for
the client that made the remote procedure call on
binding.
The server must cast this handle to the data type
specified by authz_svc. The following table shows how
to cast the return value:
ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
Γöé Table 5. Casts for Authorization Information Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé For authz_svc value: Γöé privs contains this Γöé Use this cast: Γöé
Γöé Γöé data: Γöé Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé rpc_authz_none Γöé A NULL value. Γöé None Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé rpc_authz_name Γöé The calling client's Γöé (unsigned_char_t *) Γöé
Γöé Γöé principal name. Γöé Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé rpc_authz_dce Γöé The calling client's Γöé (sec_id_pac_pac_t *) Γöé
Γöé Γöé privilege attribute Γöé Γöé
Γöé Γöé certificate. Γöé Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
Note that rpc_c_authz_none is valid only if the
authn_svc parameter is rpc_c_authn_none.
The data referenced by this parameter is read-only and
should not be modified by the server. If the server
wants to preserve any of the returned data, it must
copy the data into server-allocated memory.
server_princ_name Returns a pointer to the server principal name
specified by the client that made the remote procedure
call on binding. The content of the returned name and
its syntax is defined by the authentication service in
use.
Specifying NULL prevents the routine from returning
this parameter. In this case, the caller does not have
to call the rpc_string_free routine.
protect_level Returns the protection level requested by the client
that made the remote procedure call on binding. The
protection level determines the degree to which
authenticated communications between the client and the
server are protected.
Specifying NULL prevents the routine from returning
this parameter.
The possible protection levels are:
rpc_c_protect_level_default Uses the default
protection level for the
specified authentication
service.
rpc_c_protect_level_none Performs no protection.
rpc_c_protect_level_connect Performs protection
only when the client
establishes a
relationship with the
server.
rpc_c_protect_level_call Performs protection only
at the beginning of each
remote procedure call
when the server receives
the request.
rpc_c_protect_level_pkt Ensures that all data
received is from the
expected client.
rpc_c_protect_level_pkt_integ Ensures and verifies
that none of the data
transferred between
client and server has
been modified.
rpc_c_protect_level_cdmf_priv Performs protection
as specified by all of
the previous levels and
also encrypts each remote
procedure call parameter
value. This protection
level provides a little
lower level of packet
privacy than
rpc_c_protect_level_pkt_privacy.
rpc_c_protect_level_pkt_privacy Performs
protection as specified
by all of the previous
levels and also encrypts
each remote procedure
call parameter value.
authn_svc Returns the authentication service requested by the
client that made the remote procedure call on binding.
Specifying NULL prevents the routine from returning
this parameter.
The possible authentication services are:
rpc_c_authn_none No authentication
rpc_c_authn_dce_secret DCE shared-secret key
authentication
rpc_c_authn_dce_public DCE public key
authentication (reserved for
future use)
rpc_c_authn_default DCE default authentication
service.
authz_svc Returns the authorization service requested by the
client that made the remote procedure call on binding.
Specifying NULL prevents the routine from returning
this parameter.
The possible authorization services are:
rpc_c_authz_none The server performs no
authorization. This is valid
only if the authn_svc
parameter is
rpc_c_authn_none.
rpc_c_authz_name The server performs
authorization based on the
client principal name.
rpc_c_authz_dce The server performs
authorization using the
client's DCE privilege
attribute certificate (PAC)
sent to the server with each
remote procedure call made
with binding. Generally,
access is checked against DCE
access control lists (ACLs).
status Returns the status code from this routine. On
successful completion, the routine returns rpc_s_ok.
Otherwise, it returns one of the following errors:
rpc_s_invalid_binding The binding handle is not
valid.
rpc_s_wrong_kind_of_binding Wrong kind of binding
for the operation.
rpc_s_binding_has_no_auth The binding has no
authentication information.
Usage
The rpc_binding_inq_auth_client routine returns authentication and
authorization information associated with the client identified by
binding. The calling server manager routine can use the returned data
for authorization purposes.
The RPC runtime allocates memory for the returned server_princ_name
parameter. The server is responsible for calling the rpc_string_free
routine for the returned parameter string.
For applications in which the client side uses the IDL auto_handle or
implicit_handle attribute, the server side needs to be built with the
IDL explicit_handle attribute specified in the Attribute
Configuration File (ACF). Using explicit_handle provides binding as
the first parameter to each server manager routine.
Related Information
Routines:
rpc_binding_inq_auth_info
rpc_binding_set_auth_info
rpc_string_free
ΓòÉΓòÉΓòÉ 5.8.22. rpc_binding_inq_auth_info ΓòÉΓòÉΓòÉ
Purpose
Returns authentication and authorization information from a server
binding handle. This routine is used by client applications.
Format
#include <dce/rpc.h>
#include <dce/sec_login.h>
void rpc_binding_inq_auth_info(
rpc_binding_handle_t binding,
unsigned_char_t **server_princ_name,
unsigned32 *protect_level,
unsigned32 *authn_svc,
rpc_auth_identity_handle_t *auth_identity,
unsigned32 *authz_svc,
unsigned32 *status);
Parameters
Input
binding Specifies the server binding handle from which to
return the authentication and authorization
information.
Output
server_princ_name Returns a pointer to the expected principal name of
the server referenced by binding. The content of the
returned name and its syntax is defined by the
authentication service in use.
Specifying NULL prevents the routine from returning
this parameter. In this case, the caller does not have
to call the rpc_string_free routine.
protect_level Returns the protection level used for remote procedure
calls made with binding. The protection level
determines the degree to which authenticated
communications between the client and the server are
protected.
Note that the returned level may be different from the
level specified for protect_level on the call to
rpc_binding_set_auth_info. If the RPC runtime or the
RPC protocol in the bound protocol sequence does not
support a specified level, the level is automatically
upgraded to the next higher supported level.
Specifying NULL prevents the routine from returning
this parameter.
The possible protection levels are:
rpc_c_protect_level_default Uses the default
protection level for the
specified authentication
service.
rpc_c_protect_level_none Performs no protection.
rpc_c_protect_level_connect Performs protection
only when the client
establishes a relationship
with the server.
rpc_c_protect_level_call Performs protection only
at the beginning of each
remote procedure call when
the server receives the
request.
rpc_c_protect_level_pkt Ensures that all data
received is from the expected
client.
rpc_c_protect_level_pkt_integ Ensures and verifies
that none of the data
transferred between client
and server has been modified.
rpc_c_protect_level_cdmf_priv Performs protection
as specified by all of the
previous levels and also
encrypts each remote
procedure call parameter
value. This protection level
provides a little lower level
of packet privacy than
rpc_c_protect_level_pkt_privacy.
rpc_c_protect_level_pkt_privacy Performs
protection as specified by
all of the previous levels
and also encrypts each remote
procedure call parameter
value.
authn_svc Returns the authentication service used for remote
procedure calls made with binding.
Specifying NULL prevents the routine from returning
this parameter.
The possible authentication services are:
rpc_c_authn_none No authentication
rpc_c_authn_dce_secret DCE shared-secret key
authentication
rpc_c_authn_dce_public DCE public key
authentication (reserved for
future use)
rpc_c_authn_default DCE default authentication
service
auth_identity Returns a handle for the data structure that contains
the client's authentication and authorization
credentials. This parameter must be cast as appropriate
for the authentication and authorization services
established using rpc_binding_set_auth_info.
When using the rpc_c_authn_dce_secret authentication
service and any authorization service, this value must
be a sec_login_handle_t obtained from one of the
following routines:
o sec_login_setup_identity
o sec_login_get_current_context
o sec_login_newgroups.
These routines are described in DCE Security Services
API.
Specifying NULL prevents the routine from returning
this parameter.
authz_svc Returns the authorization service used for remote
procedure calls made with binding.
Specifying NULL prevents the routine from returning
this parameter.
The possible authorization services are:
rpc_c_authz_none The server performs no
authorization. This is valid
only if the authn_svc
parameter is
rpc_c_authn_none.
rpc_c_authz_name The server performs
authorization based on the
client principal name.
rpc_c_authz_dce The server performs
authorization using the
client's DCE privilege
attribute certificate (PAC)
sent to the server with each
remote procedure call made
with binding. Generally,
access is checked against DCE
access control lists (ACLs).
status Returns the status code from this routine. On
successful completion, the routine returns rpc_s_ok.
Otherwise, it returns one of the following errors:
rpc_s_invalid_binding The binding handle is not
valid.
rpc_s_wrong_kind_of_binding Wrong kind of binding
for the operation.
rpc_s_binding_has_no_auth The binding has no
authentication information.
Usage
The rpc_binding_inq_auth_info routine returns authentication and
authorization information associated with the specified server
binding handle. The calling client associates the authentication and
authorization data with the server binding handle by a prior call to
the rpc_binding_set_auth_info routine.
The RPC runtime allocates memory for the returned server_princ_name
parameter. The caller is responsible for calling the rpc_string_free
routine for the returned parameter string.
Related Information
Routines:
rpc_binding_set_auth_info
rpc_string_free
ΓòÉΓòÉΓòÉ 5.8.23. rpc_binding_inq_object ΓòÉΓòÉΓòÉ
Purpose
Returns the object UUID from a binding handle. This routine is used
by client or server applications.
Format
#include <dce/rpc.h>
void rpc_binding_inq_object(
rpc_binding_handle_t binding,
uuid_t *object_uuid,
unsigned32 *status);
Parameters
Input
binding Specifies a client or server binding handle.
Output
object_uuid Returns the object UUID found in the binding parameter.
The object UUID is a unique identifier for an object
for which a remote procedure call can be made.
status Returns the status code from this routine. On
successful completion, the routine returns rpc_s_ok.
Otherwise, it returns the following error:
rpc_s_invalid_binding The binding handle is not
valid.
Usage
The rpc_binding_inq_object routine obtains the object UUID associated
with a client or server binding handle. If no object UUID has been
associated with the binding handle, this routine returns a nil UUID.
Related Information
Routines:
rpc_binding_set_object
ΓòÉΓòÉΓòÉ 5.8.24. rpc_binding_reset ΓòÉΓòÉΓòÉ
Purpose
Resets a server binding handle. This routine is used by client or
management applications.
Format
#include <dce/rpc.h>
void rpc_binding_reset(
rpc_binding_handle_t binding,
unsigned32 *status);
Parameters
Input
binding Specifies the server binding handle to reset.
Output
status Returns the status code from this routine. On
successful completion, the routine returns rpc_s_ok.
Otherwise, it returns one of the following errors:
rpc_s_invalid_binding The binding handle is not
valid.
rpc_s_wrong_kind_of_binding Wrong kind of binding
for the operation.
Usage
The rpc_binding_reset routine disassociates a server instance from
the server binding handle specified in the binding parameter. This
routine removes the endpoint portion of the server address in the
binding handle as well as any other server instance information in
the binding handle. The host portion of the server address remains
unchanged. The result is a partially bound server binding handle.
This binding handle can rebind to another server instance on the
previous host when it is later used to make a remote procedure call.
See Binding Handle for an explanation of partially and fully bound
binding handles.
This routine does not affect any authentication information for the
binding parameter.
Suppose that a client can be serviced by any compatible server
instance on the host specified in the binding handle. Then, the
client can call the rpc_binding_reset routine before making a remote
procedure call using the binding handle specified in binding.
When the client makes the next remote procedure call using the reset
server binding handle in binding, the client's RPC runtime uses a
well-known endpoint from the client's interface specification, if
any. Otherwise, the client's RPC runtime automatically communicates
with the DCE Host daemon (dced) on the specified remote host, to
obtain the endpoint of a compatible server from the local endpoint
map. If a compatible server is located, the RPC runtime updates
binding with a new endpoint.
However, if a compatible server is not located, the client's remote
procedure call fails. If the failed call uses a connection protocol
(ncacn), it receives the rpc_s_endpoint_not_found status code. If the
failed call uses a datagram protocol (ncadg), it receives the
rpc_s_comm_failure status code.
If a server application wants to be available to clients making a
remote procedure call on a reset binding handle, it registers all
binding handles by calling rpc_ep_register or
rpc_ep_register_no_replace. If however, the IDL-generated file
contains endpoint address information, the application does not have
to call either of these two routines.
Related Information
Routines:
rpc_ep_register
rpc_ep_register_no_replace
ΓòÉΓòÉΓòÉ 5.8.25. rpc_binding_server_from_client ΓòÉΓòÉΓòÉ
Purpose
Converts a client binding handle to a server binding handle. This
routine is used by server applications.
Format
#include <dce/rpc.h>
void rpc_binding_server_from_client(
rpc_binding_handle_t client_binding,
rpc_binding_handle_t *server_binding,
unsigned32 *status);
Parameters
Input
client_binding Specifies the client binding handle to convert to a
server binding handle.
Output
server_binding Returns a server binding handle.
status Returns the status code from this routine. On
successful completion, the routine returns rpc_s_ok.
Otherwise, it returns one of the following errors:
rpc_s_cant_getpeername Cannot get peer name.
rpc_s_connection_closed Connection closed.
rpc_s_invalid_binding The binding handle is not
valid.
rpc_s_wrong_kind_of_binding Wrong kind of binding.
Usage
When a remote procedure call arrives at a server, the RPC runtime
creates a client binding handle to refer to information about the
calling client (client binding information). The RPC runtime passes
the client binding handle to the called remote procedure as the first
input parameter (which uses the handle_t type).
The rpc_binding_server_from_client routine converts client binding
information into server binding information corresponding to the
client's system. When calling this routine, the called remote
procedure specifies the client binding handle, and the routine
returns a partially bound server binding handle (that is, the newly
constructed server binding information contains a network address for
the client's system but lacks an endpoint). The server binding
information also lacks authentication information, but the called
procedure can add it by calling rpc_binding_set_auth_info. The object
UUID from the client binding information remains.
The rpc_binding_server_from_client routine is relevant when a called
remote procedure (the first remote procedure) needs to make its own
remote procedure call (a nested procedure call) to a second remote
procedure offered by a server on the system of the client that called
the first remote procedure (that is, the original client). The
partially bound server binding handle returned by the
rpc_binding_server_from_client routine ensures that a nested call
requests the second remote procedure on the original client's system.
In a multithreaded RPC application, the second remote procedure can
belong to a server that shares the original client's address space
(that is, the server and client can operate jointly as a
server-client instance). If the original client belongs to a
server-client instance and the application requires the nested call
to run in that instance, the application must guarantee that the
nested remote procedure call uses the endpoints of one of the
instances.
An application can provide this guarantee by meeting any of the
following conditions:
o The interface possesses its own well-known endpoints, and the
server elects to use these interface-specific endpoints (by
calling rpc_server_use_protseq_if or
rpc_server_use_all_protseqs_if).
o The server uses server-specific endpoints, and the interface is
offered by only one server-client instance per system.
To use server-specific endpoints, a server either requests
dynamic endpoints (by calling rpc_server_use_protseq or
rpc_server_use_all_protseqs) or specifies its own well-known
endpoints (by calling rpc_server_use_protseq_ep). The server
must also register its server-specific endpoints in the local
endpoint map (by calling rpc_ep_register).
o The original client sets an object UUID into the server binding
information of the first call (by calling
rpc_binding_set_object); the object UUID identifies the
server-client instance.
The client can obtain the object UUID from the list of object
UUIDs used to register the endpoints of the server-client
instance. The client must select an object UUID that belongs
exclusively to its instance.
Server binding information containing an object UUID impacts the
selection of a manager for a remote procedure call. See the DCE
for OS/2 Warp: Application Development Guide - Core Components
for a description of manager selection. The object UUID can
either identify a particular resource offered by the companion
server or, used as an instance UUID, the object UUID can
identify the original client's server-client instance.
The object UUID is passed in the first remote procedure call as
part of the client binding information and is retained in the
server binding information. This server binding information is
newly constructed by the rpc_binding_server_from_client routine.
When the second remote procedure call arrives at the original
client's system, the DCE Host daemon uses the object UUID to
look for associated endpoints in the local endpoint map. To
ensure that the object UUID is associated with the endpoints of
original server-client instance, the server must complete the
following steps:
1. Obtain the UUID (for example, by calling uuid_create).
2. Specify the UUID as part of registering endpoints for the
interface of the second remote procedure (by calling
rpc_ep_register or rpc_ep_register_no_replace).
If the second remote procedure call is routed to a manager of
a non-nil type, then the server must also:
1. Specify the type for the manager that implements that
interface (by calling rpc_server_register_if).
2. Set the object UUID to the same type as the manager (by
calling rpc_object_set_type).
o The first remote procedure call contains a distinct call
parameter used by the original client to pass server information
that identifies its server-client instance.
The first remote procedure call uses this information to route
the second remote procedure call to the original server-client
instance. For example, server information can be:
- A fully bound string binding that identifies the client's
server-client instance.
If the first remote procedure receives this string binding,
calling rpc_binding_server_from_client is unnecessary.
Instead, the first remote procedure requests a server
binding handle for the string binding (by calling
rpc_binding_from_string_binding).
- An object UUID that is associated in the endpoint map with
one or more endpoints of the original server-client
instance.
The client can obtain the object UUID from the list of
object UUIDs used to register the endpoints of the
server-client instance. The client must select an object
UUID that belongs exclusively to its instance, and pass
that UUID as a call parameter.
After calling rpc_binding_server_from_client, add the
object UUID from the call parameter to the newly
constructed server binding information (by calling
rpc_binding_set_object).
Related Information
Routines:
rpc_binding_free
rpc_binding_set_object
rpc_ep_register
rpc_ep_register_no_replace
ΓòÉΓòÉΓòÉ 5.8.26. rpc_binding_set_auth_info ΓòÉΓòÉΓòÉ
Purpose
Sets authentication and authorization information for a server
binding handle. This routine is used by client applications.
Format
#include <dce/rpc.h>
#include <dce/sec_login.h>
void rpc_binding_set_auth_info(
rpc_binding_handle_t binding,
unsigned_char_t *server_princ_name,
unsigned32 protect_level,
unsigned32 authn_svc,
rpc_auth_identity_handle_t auth_identity,
unsigned32 authz_svc,
unsigned32 *status);
Parameters
Input
binding Specifies the server binding handle for which to set
the authentication and authorization information.
server_princ_name Specifies the principal name of the server
referenced by binding. The content of the name and its
syntax is defined by the authentication service in use.
A client that does not know the server principal name
can call the rpc_mgmt_inq_server_princ_name routine to
obtain the principal name of a server that is
registered for the required authentication service.
Using a principal name obtained in this way means that
the client is interested in one-way authentication. In
other words, it means that the client does not care
which server principal received the remote procedure
call request. The server, though, still verifies that
the client is who the client claims to be.
Note: Note that you can use a NULL server name only if
the binding handle is either fully bound or is
bound to a non-null object UUID. For related
information, refer to the RPC and NSI related
sections of the DCE for OS/2 Warp: Application
Development Guide - Core Components.
protect_level Specifies the protection level for remote procedure
calls made using binding. The protection level
determines the degree to which authenticated
communications between the client and the server are
protected by the authentication service specified by
authn_svc The possible protection levels are:
rpc_c_protect_level_default Uses the default
protection level for the
specified authentication
service.
The default protection level
for the DCE shared-secret
key authentication service
is
rpc_c_protect_level_pkt_integ.
rpc_c_protect_level_none Performs no
authentication: tickets are
not exchanged, session keys
are not established, client
PACS or names are not
certified, and transmissions
are in the clear. Note that
although uncertified PACs
should not be trusted, they
can be useful for debugging,
tracing, and measurement
purposes.
rpc_c_protect_level_connect Performs protection
only when the client
establishes a relationship
with the server.
rpc_c_protect_level_call Performs protection only
at the beginning of each
remote procedure call when
the server receives the
request.
This level does not apply to
remote procedure calls made
over a connection-based
protocol sequence (that is,
ncacn_ip_tcp). If this level
is specified and the binding
handle uses a
connection-based protocol
sequence, the routine uses
the rpc_c_protect_level_pkt
level instead.
rpc_c_protect_level_pkt Ensure that all data
received is from the
expected client.
rpc_c_protect_level_pkt_integ Ensures and verifies
that none of the data
transferred between client
and server has been
modified.
This is the highest
protection level that is
guaranteed to be present in
the RPC runtime.
rpc_c_protect_level_cdmf_priv Performs protection
as specified by all of the
previous levels and also
encrypts each remote
procedure call parameter
value. This protection level
provides a little lower
level of packet privacy than
rpc_c_protect_level_pkt_privacy.
rpc_c_protect_level_pkt_privacy Performs
protection as specified by
all of the previous levels
and also encrypts each
remote procedure call
parameter value.
This is the highest
protection level, but it may
not be available in the RPC
runtime.
authn_svc Specifies the authentication service to use. The exact
level of protection provided by the authentication
service is specified by the protect_level parameter.
The supported authentication services are:
rpc_c_authn_none No authentication: no tickets
are exchanged, no session
keys established, client PACS
or names are not transmitted,
and transmissions are in the
clear. Specify
rpc_c_authn_none to turn
authentication off for remote
procedure calls made using
binding.
rpc_c_authn_dce_secret DCE shared-secret key
authentication
rpc_c_authn_dce_public DCE public key
authentication ( reserved for
future use)
rpc_c_authn_default DCE default authentication
service.
Note: The current default authentication service is
SCE shared-secret key; therefore, specifying
rpc_c_authn_default is equivalent to specifying
rpc_c_authn_dce_secret.
auth_identity Specifies a handle for the data structure that contains
the client's authentication and authorization
credentials appropriate for the selected authentication
and authorization services.
When using the rpc_c_authn_dce_secret authentication
service and any authorization service, this value must
be a sec_login_handle_t obtained from one of the
following routines:
o sec_login_setup_identity
o sec_login_get_current_context
o sec_login_newgroups.
These routines are described in DCE Security Services
API.
Specify NULL to use the default security login context
for the current address space.
authz_svc Specifies the authorization service implemented by the
server for the interface of interest. The validity and
trustworthiness of authorization data, like any
application data, is dependent on the authentication
service and protection level specified. The supported
authorization services are:
rpc_c_authz_none Server performs no
authorization. This is valid
only if the authn_svc
parameter is
rpc_c_authn_none, specifying
that no authentication is
being performed.
rpc_c_authz_name Server performs authorization
based on the client principal
name.
This value cannot be used if
authn_svc is
rpc_c_authn_none.
rpc_c_authz_dce Server performs authorization
using the client's DCE
privilege attribute
certificate (PAC) sent to the
server with each remote
procedure call made with
binding. Generally, access is
checked against DCE access
control lists (ACLs).
This value cannot be used if
authn_svc is
rpc_c_authn_none.
Output
status Returns the status code from this routine. On
successful completion, the routine returns rpc_s_ok.
Otherwise, it returns one of the following errors:
rpc_s_invalid_binding The binding handle is not
valid.
rpc_s_wrong_kind_of_binding Wrong kind of binding
for the operation.
rpc_s_unknown_authn_service Unknown authentication
service.
Usage
The rpc_binding_set_auth_info routine sets up the specified server
binding handle so that it can be used to make authenticated remote
procedure calls, that include authorization information.
Unless a client calls this routine with the parameters set to
establish authentication and authorization methods, all remote
procedure calls made on the binding binding handle are
unauthenticated. A client is not required to call this routine.
Some authentication services (authn_svc) might need to communicate
with the Security service to perform this operation. Otherwise, they
might receive the rpc_s_comm_failure status.
The authn_svc parameter specifies the authentication service to use.
Since currently, there is only one available authentication service
(DCE shared-secret key), the parameter currently functions to specify
whether RPC calls will be authenticated and client PACs certified. If
authentication is chosen, the protect_level parameter can specify a
variety of protection levels, ranging from no authentication to the
highest level of authentication and encryption. If the protect_level
parameter is set to rpc_c_protect_level_none, no authentication is
performed, regardless of the authentication service chosen.
The authz_svc parameter specifies the authorization service to use.
If no authentication has been chosen (authn_svc of the
rpc_c_authn_none), then no authorization (authn_svc of the
rpc_c_authz_none), must be chosen as well. If authentication will be
performed, you have two choices for authorization: name-based
authorization and DCE authorization. The use of name based
authorization, which provides a server with a client's principal
name, is not recommended. DCE authorization uses PACs, a trusted
mechanism for conveying client authorization data to authenticated
servers. PACs are designed to be used with the DCE ACL facility.
Whether the call actually wakes up in the server manager code or is
rejected by the runtime depends on the following conditions:
o If the client specified no authentication, then none is
attempted by the RPC runtime. The call wakes up in the manager
code whether the server specified authentication or not. This
permits both authenticated and unauthenticated clients to call
authenticated servers. When the manager receives an
unauthenticated call, it needs to make a decision about how to
proceed.
o If the client specified DCE secret-key authentication and the
server specified no authentication, then the runtime fails the
call, and it never reaches the manager routine.
o If both client and server specified DCE secret-key
authentication, then authentication is carried out by the RPC
runtime transparently. Whether the call reaches the server
manager code or is rejected by the runtime depends on whether
the authentication succeeded.
Although the RPC runtime is responsible for any authentication that
is carried out, the fact that the runtime always permits
unauthenticated clients to reach the manager code means that a
manager access function typically does need to make an authentication
check. When the manager access routine calls
rpc_binding_inq_auth_client it needs to check for a status of
rpc_s_binding_has_no_auth. In this case, the client has specified no
authentication and the manager access function needs to make an
access decision based on this fact. Note that in such a case, no
meaningful authentication or authorization information is returned
from rpc_binding_inq_auth_client.
Notes
The DCE runtime library caches data structures from rpc activity and
authentication activity, in order to improve performance on repeated
RPC calls to the same server. This information is generally kept for
up to 10 minutes after the last call before it is freed. Under
certain circumstances, this caching can result in increased memory
usage.
If a client does repeated calls to the rpc_binding_set_auth_info
routine with different identities each time, new data structures are
created and cached for each new identity. Clients or intermediate
servers that make many repeated calls like this will show memory
growth proportional to the number of new identities created in a 10
minute interval. This memory is eventually reused for new
identities, but the steady state process size can be large in very
active scenarios.
Related Information
Routines:
rpc_binding_inq_auth_info
rpc_mgmt_inq_dflt_protect_level
rpc_mgmt_inq_server_princ_name
sec_login_get_current_context
sec_login_newgroups
sec_login_setup_identity
ΓòÉΓòÉΓòÉ 5.8.27. rpc_binding_set_object ΓòÉΓòÉΓòÉ
Purpose
Sets the object UUID value into a server binding handle. This routine
is used by client applications.
Format
#include <dce/rpc.h>
void rpc_binding_set_object(
rpc_binding_handle_t binding,
uuid_t *object_uuid,
unsigned32 *status);
Parameters
Input
binding Specifies the server binding into which parameter
object_uuid is set. Supply NULL to specify a nil UUID
for this parameter.
object_uuid Specifies the UUID of the object serviced by the server
specified in the binding parameter. The object UUID is
a unique identifier for an object for which a remote
procedure call can be made. Supply NULL to specify a
nil UUID for this parameter.
Output
status Returns the status code from this routine. On
successful completion, the routine returns rpc_s_ok.
Otherwise, it returns one of the following errors:
rpc_s_invalid_binding The binding handle is not
valid.
rpc_s_wrong_kind_of_binding Wrong kind of binding
for the operation.
Usage
The rpc_binding_set_object routine associates an object UUID with a
server binding handle. This operation replaces the previously
associated object UUID with the UUID in the object_uuid parameter.
To set the object UUID to the nil UUID, specify NULL or the nil UUID
for the object_uuid parameter.
Related Information
Routines:
rpc_binding_from_string_binding
rpc_binding_inq_object
ΓòÉΓòÉΓòÉ 5.8.28. rpc_binding_to_string_binding ΓòÉΓòÉΓòÉ
Purpose
Returns a string representation of a binding handle. This routine is
used by client, server, or management applications.
Format
#include <dce/rpc.h>
void rpc_binding_to_string_binding(
rpc_binding_handle_t binding,
unsigned_char_t **string_binding,
unsigned32 *status);
Parameters
Input
binding Specifies a client or server binding handle to convert
to a string representation of a binding handle.
Output
string_binding Returns a pointer to the string representation of the
binding handle specified in the binding parameter.
status Returns the status code from this routine. On
successful completion, the routine returns rpc_s_ok.
Otherwise, it returns one of the following errors:
rpc_s_cant_getpeername Cannot get peer name.
rpc_s_connection_closed Connection closed.
rpc_s_invalid_binding The binding handle is not
valid.
Usage
The rpc_binding_to_string_binding routine converts a client or server
binding handle to its string representation.
The RPC runtime allocates memory for the string returned in the
string_binding parameter. The application calls the rpc_string_free
routine to deallocate that memory.
If the binding handle in the binding parameter contains a nil object
UUID, the object UUID field is not included in the returned string.
To parse the returned string_binding parameter, call
rpc_string_binding_parse.
Related Information
Routines:
rpc_binding_from_string_binding
rpc_string_binding_parse
rpc_string_free
ΓòÉΓòÉΓòÉ 5.8.29. rpc_binding_vector_free ΓòÉΓòÉΓòÉ
Purpose
Frees the memory used to store a vector and binding handles. This
routine is used by client or server applications.
Format
#include <dce/rpc.h>
void rpc_binding_vector_free(
rpc_binding_vector_t **binding_vector,
unsigned32 *status);
Parameters
Input/Output
binding_vector Specifies the address of a pointer to a vector of
server binding handles. On return the pointer is set to
NULL.
Output
status Returns the status code from this routine. On
successful completion, the routine returns rpc_s_ok.
Otherwise, it returns one of the following errors:
rpc_s_invalid_arg The argument is not valid.
rpc_s_invalid_binding The binding handle is not
valid.
rpc_s_wrong_kind_of_binding Wrong kind of binding
for the operation.
Usage
The rpc_binding_vector_free routine frees the memory used to store a
vector of server binding handles. The freed memory includes both the
binding handles and the vector itself.
A server obtains a vector of binding handles by calling
rpc_server_inq_bindings. A client obtains a vector of binding handles
by calling rpc_ns_binding_lookup_next. Call rpc_binding_vector_free
if you have used either of these routines.
The rpc_binding_free routine frees individual elements of the vector.
If an element is freed with this routine, the NULL element entry
replaces it; rpc_binding_vector_free ignores such an entry.
Related Information
Routines:
rpc_binding_free
rpc_ns_binding_lookup_next
rpc_server_inq_bindings
ΓòÉΓòÉΓòÉ 5.8.30. rpc_cs_binding_set_tags ΓòÉΓòÉΓòÉ
Purpose
Places code set tags into a server binding handle. Used by client
applications.
Format
#include <dce/rpc.h>
void rpc_cs_binding_set_tags(
rpc_binding_handle_t *binding,
unsigned32 sending_tag,
unsigned32 desired_receiving_tag,
unsigned16 sending_tag_max_bytes,
error_status_t *status);
Parameters
Input/Output
binding On input, specifies the server binding handle to modify
with tag information. This handle is the binding handle
returned by the rpc_ns_binding_import_next or
rpc_ns_binding_select routine. On output, this
parameter returns the server binding handle modified
with code set tag information. The server stub
retrieves the tag information from the binding handle
and uses it to call the appropriate buffer sizing and
code set conversion routines.
Input
sending_tag Specifies the code set value for the code set in which
client data to be sent to the server is to be encoded.
If the client is not sending any data, set this value
to the client's current code set. This step prevents
the code set conversion routine from being called.
desired_receiving_tag Specifies the code set value for the code set
in which the client prefers data to be encoded when
sent back from the server. If the client is not
planning to receive any data from the server, set this
value to the server's current code set. This step
prevents the code set conversion routine from being
called.
sending_tag_max_bytes Specifies the maximum number of bytes that a
code set requires to encode one character. The value is
the c_max_bytes value associated with the code set
value (c_set) used as the sending_tag value.
Output
status Returns the status code from this routine. On
successful completion, the routine returns rpc_s_ok.
Otherwise, it returns rpc_s_no_memory.
The routine can also return status codes generated by
the rpc_rgy_get_codesets routine.
Usage
The rpc_cs_binding_set_tags routine belongs to a set of DCE RPC
routines for use by client and server applications that are
transferring international character data in a heterogeneous
character set and code sets environment. These routines are used to
enable automatic code set conversion between client and server for
character representations that are not part of the DCE Portable
Character Set.
Client applications use the rpc_cs_binding_set_tags routine to add
code sets tag information to the binding handle of a compatible
server. The tag information specified in the routine is usually
obtained from a character and code sets evaluation routine (which is
typically a user-written routine).
The sending_tag value identifies the code set encoding that the
client is using to send international character data to the server.
The desired_receiving_tag value indicates to the server the code set
that the client prefers the server to use when sending return
international character data. The sending_tag_max_bytes value is the
number of bytes the sending code set uses to encode one character.
Client applications that use the rpc_cs_eval_with_universal or
rpc_cs_eval_without_universal routines do not need to call this
routine because these routines set tag information in the server
binding handle as part of their operation. Application developers who
are writing their own character and code sets evaluation routines
need to include code that sets tags in a server binding handle. The
rpc_cs_binding_set_tags routine provides this function and can be
used in user-written evaluation routines, or alone if the application
does not need to perform evaluation. In this case, the routine
provides a short cut for application programmers whose applications
do not need to evaluate for character and code set compatibility.
Related Information
Routines:
rpc_cs_eval_with_universal
rpc_cs_eval_without_universal
rpc_cs_get_tags
ΓòÉΓòÉΓòÉ 5.8.31. rpc_cs_char_set_compat_check ΓòÉΓòÉΓòÉ
Purpose
Evaluates character set compatibility between a client and a server.
This routine is used by client applications.
Format
#include <dce/rpc.h>
void rpc_cs_char_set_compat_check(
rpc_codeset_mgmt_p_t client_code_sets_array,
rpc_codeset_mgmt_p_t server_code_sets_array,
error_status_t *status);
Parameters
Input
client_code_sets_array The list of character and code sets supported
by the client machine.
server_code_sets_array The list of character and code sets supported
by the server machine.
Output
status Returns the status code from this routine. On
successful completion, the routine returns rpc_s_ok.
Otherwise, it returns rpc_s_ss_no_compat_charsets.
Usage
The rpc_cs_char_set_compat_check routine belongs to a set of DCE RPC
routines for use by client and server applications that are
transferring international character data in a heterogeneous
character set and code sets environment.
The rpc_cs_char_set_compat_check routine provides a method for
determining character set compatibility between a client and a
server; if the server's character set is incompatible with that of
the client, then connecting to that server is most likely not
acceptable, since massive data loss would result from such a
connection.
The RPC routines that perform character and code sets evaluation use
the rpc_cs_char_set_compat_check routine in their character sets and
code sets compatibility checking procedure. Before calling this
routine, client applications must use the rpc_rgy_get_codesets
routine to get the client's supported character and code sets, and
use the rpc_ns_mgmt_read_codesets routine to retrieve the server's
supported character and code sets from the name service database in
order to do the character sets compatibility checking. If both client
and server support just one character set, the routine compares
client and server registered character set values to determine
whether the sets are compatible. If they are not, the routine returns
the status message rpc_s_ss_no_compat_charsets.
If the client and server support multiple character sets, the routine
determines whether at least two of the sets are compatible. If two or
more sets match, the routine considers the character sets compatible,
and returns a success status code to the caller.
Client and server applications that use the DCE RPC code sets
evaluation routines rpc_cs_eval_with_universal and
rpc_cs_eval_without_universal do not need to call this routine
explicitly because these DCE RPC routines call it on their behalf.
Client applications that do not use the DCE RPC code sets evaluation
routines can use the rpc_cs_char_set_compat_check routine in their
code sets evaluation code as part of their procedure for determining
character and code set compatibility with a server.
Related Information
Routines:
rpc_cs_eval_with_universal
rpc_cs_eval_without_universal
rpc_cs_get_tags
rpc_ns_mgmt_read_codesets
rpc_rgy_get_codesets
ΓòÉΓòÉΓòÉ 5.8.32. rpc_cs_eval_with_universal ΓòÉΓòÉΓòÉ
Purpose
Evaluates a server's supported character sets and code sets during
the server binding selection process. This routine is used indirectly
by client applications.
Format
#include <dce/rpc.h>
void rpc_cs_eval_with_universal(
rpc_ns_handle_t binding_handle,
idl_void_p_t eval_args,
idl_void_p_t *context);
Parameters
Input
binding_handle The server binding handle.
eval_args An opaque data type that contains matching criteria
that the routine uses to perform character and code
sets compatibility evaluation.
Input/Output
context An opaque data type that contains a search context to
perform character and code sets compatibility
evaluation. The routine returns the result of the
evaluation in a field within context.
Usage
The rpc_cs_eval_with_universal routine is a DCE RPC character and
code sets evaluation routine that can be added to an import context.
The routine provides a mechanism for a client application that is
passing character data in a heterogeneous character set and code sets
environment to evaluate a server's character and code sets
compatibility before establishing a connection with it.
Client applications do not call rpc_cs_eval_with_universal directly.
Instead, they add it to the import context created by the
rpc_ns_binding_import_begin routine by calling the routine
rpc_ns_import_ctx_add_eval and specifying the routine name and the
RPC server entry name to be evaluated. When the client application
calls the rpc_ns_binding_import_next routine to import compatible
binding handles for servers, this routine calls
rpc_cs_eval_with_universal, which applies client-server code sets
compatibility checking as another criterion for compatible binding
selection.
The rpc_cs_eval_with_universal routine directs the
rpc_ns_binding_import_next routine to reject servers with
incompatible character sets. If client and server character sets are
compatible but their supported code sets are not, the routine
establishes tags that direct the client and server stubs to convert
character data to the default intermediate code set, which is the
ISO10646 (or universal) code set (USC-2, Level 1).
Note: Application programmers can ignore the parameters of this
routine. They only need to use rpc_ns_import_ctx_add_eval to
set the routine, for example:
rpc_ns_import_ctx_add_eval(
&import_context,
rpc_c_eval_type_codesets,
(void *) nsi_entry_name,
rpc_cs_eval_with_universal,
NULL,
&status);
Related Information
Routines:
rpc_cs_eval_without_universal
rpc_cs_get_tags
rpc_ns_binding_import_begin
rpc_ns_binding_import_done
rpc_ns_binding_import_next
rpc_ns_import_ctx_add_eval
rpc_ns_mgmt_handle_set_exp_age
ΓòÉΓòÉΓòÉ 5.8.33. rpc_cs_eval_without_universal ΓòÉΓòÉΓòÉ
Purpose
Evaluates a server's supported character sets and code sets during
the server binding selection process. This routine is used indirectly
by client applications.
Format
#include <dce/rpc.h>
void rpc_cs_eval_without_universal(
rpc_ns_handle_t binding_handle,
idl_void_p_t eval_args,
idl_void_p_t *context);
Parameters
Input
binding_handle The server binding handle.
eval_args An opaque data type that contains matching criteria
that the routine uses to perform code sets
compatibility evaluation.
Input/Output
context An opaque data type that contains a search context to
perform character and code sets compatibility
evaluation. The routine returns the result of the
evaluation in a field within context.
Usage
The rpc_cs_eval_without_universal routine is a DCE RPC character and
code sets evaluation routine that can be added to an import context.
The routine provides a mechanism for a client application that is
passing character data in a heterogeneous character set and code sets
environment to evaluate a server's character and code sets
compatibility before establishing a connection with it.
Client applications do not call rpc_cs_eval_without_universal
directly. Instead, they add it to the import context created by the
rpc_ns_binding_import_begin routine by calling the routine
rpc_ns_import_ctx_add_eval and specifying the routine name and the
RPC server entry name to be evaluated. When the client application
calls the rpc_ns_binding_import_next routine to import compatible
binding handles for servers, this routine calls
rpc_cs_eval_without_universal, which applies client-server code sets
compatibility checking as another criterion for compatible binding
selection.
The rpc_cs_eval_without_universal routine directs the
rpc_ns_binding_import_next routine to reject servers with
incompatible character sets. The routine also directs the
rpc_ns_binding_import_next routine to reject servers whose supported
code sets are incompatible with the client's supported code sets;
that is, it does not resort to using an intermediate code set as a
last resort.
Note: Application programmers can ignore the arguments of this
routine. They only need to use rpc_ns_import_ctx_add_eval to
set the routine, for example:
rpc_ns_import_ctx_add_eval(
&import_context,
rpc_c_eval_type_codesets,
(void *) nsi_entry_name,
rpc_cs_eval_without_universal,
NULL,
&status);
Related Information
Routines:
rpc_cs_get_tags
rpc_ns_binding_import_begin
rpc_ns_binding_import_done
rpc_ns_binding_import_next
rpc_ns_import_ctx_add_eval
rpc_ns_mgmt_handle_set_exp_age
ΓòÉΓòÉΓòÉ 5.8.34. rpc_cs_get_tags ΓòÉΓòÉΓòÉ
Purpose
Retrieves code set tags from a binding handle. This routine is used
by client and server applications.
Format
#include <dce/codesets_stub.h>
void rpc_cs_get_tags(
rpc_binding_handle_t binding,
boolean32 server_side,
unsigned32 *sending_tag,
unsigned32 *desired_receiving_tag,
unsigned32 *receiving_tag,
error_status_t *status);
Parameters
Input
binding Specifies the target binding handle from which to
obtain the code set tag information. When called from
the client stub, this value is the binding handle of a
compatible server returned by the
rpc_ns_binding_import_next or rpc_ns_binding_select
routines. When called from the server stub, this value
is a pointer to the tag information that the client
stub passed in the RPC call.
server_side Indicates whether a client stub or a server stub is
calling the routine. If a server stub is doing the
calling, this parameter should contain TRUE.
desired_receiving_tag (Server stub only.) Specifies the code set
value for the code set in which the client prefers data
to be encoded when sent back from the server. The
client stub passes this value in the RPC call. If the
routine is retrieving code set tags for an operation
that does not specify a desired receiving tag parameter
(the cs_drtag ACF parameter attribute has not been
applied to one of the operation's parameters), this
value is NULL.
Output
sending_tag (Client stub only.) Specifies the code set value for
the code set in which client data to be sent to the
server is to be encoded. If the routine is retrieving
code set tags for an operation that does not specify a
sending tag parameter (the cs_stag ACF parameter
attribute has not been applied to one of the
operation's parameters), this value is NULL.
desired_receiving_tag (Client stub only.) Specifies the code set
value for the code set in which the client prefers to
receive data sent back to it from the server. If the
routine is retrieving code set tags for an operation
that does not specify a desired receiving tag parameter
(the cs_drtag ACF parameter attribute has not been
applied to one of the operation's parameters), this
value is NULL.
receiving_tag (Server stub only.) Specifies the code set value for
the code set in which the server is to encode data to
be sent back to the client. If the routine is
retrieving code set tags for an operation that does not
specify a receiving tag parameter (the cs_rtag ACF
parameter attribute has not been applied to one of the
operation's parameters), this value is NULL.
status Returns the status code from this routine. On
successful completion, the routine returns rpc_s_ok.
Otherwise, it returns one of the following errors:
rpc_s_ss_incompatible_codesets The server cannot
handle the data in the code set that
the client has specified. This
status code is returned if the
application performs code set
compatibility evaluation in the
server stub.
rpc_s_ss_invalid_codeset_tag The result if the
client-side evaluation used an
invalid code set tag.
If code set compatibility evaluation is performed,
error values can also be returned from
rpc_rgy_get_codesets, rpc_ns_binding_inq_entry_name,
and rpc_ns_mgmt_read_codesets.
Usage
The rpc_cs_get_tags routine belongs to a set of DCE RPC routines for
use by client and server applications that are transferring
international character data in a heterogeneous character set and
code sets environment.
The rpc_cs_get_tags routine is a DCE RPC routine that RPC stubs can
use to retrieve the code set values to be used to tag international
character data to be sent over the network. In general, the code set
values to be used as tags are determined by a character and code sets
evaluation routine, which is called from the client application code.
However, application programmers can use other methods to establish
values for code set tags.
RPC stubs call the rpc_cs_get_tags routine before they call the
buffer sizing routines xxx_net_size and the code set conversion
routines xxx_netcs. The rpc_cs_get_tags routine provides the stubs
with code set values to use as input to the buffer sizing routines
(to determine whether buffer storage needs to be allocated for
conversion) and as input to the code set conversion routines (to
determine whether conversion is necessary, and if so, which host code
set converter to use).
Client and server stubs call the rpc_cs_get_tags routine before they
marshall any data. When called from the client stub, the boolean
value server_side is set to FALSE to indicate that the client stub
has called the routine. The binding parameter is the handle to a
compatible server returned by the rpc_ns_binding_import_next or
rpc_ns_binding_select routines. If the client has added a code sets
evaluation routine to the binding import procedure (by calling the
routine rpc_ns_import_ctx_add_eval), the binding parameter contains
the conversion method and the code set values to set for the client's
sending tag and desired receiving tag. If binding does not contain
the results of an evaluation, the rpc_cs_get_tags routine performs
the character/code sets evaluation within the client stub and sets
the client code set tag values itself.
On the client side, the output of the routine is the code set value
that represents the client's sending tag and the code set value that
represents the client's desired receiving tag. If the conversion
method is "client makes it right" (CMIR), the sending tag and desired
receiving tags are set to the code set value of the server's local
code set. If the conversion method is "server makes it right" (SMIR),
the sending tag and desired receiving tag are set to the client's
local code set value. If the conversion method is "receiver makes it
right" (RMIR), the sending tag is the client's code set, and the
desired receiving tag is the server's code set.
When called from the server stub, the boolean value server_side is
set to TRUE to indicate that the server stub has called the routine.
The binding parameter is a pointer to the tag data sent by the client
stub.
The server stub specifies the code set value given in the client's
desired receiving tag as input to the routine. The rpc_cs_get_tags
routine sets the code set value in desired_receiving_tag to
receiving_tag and returns this value as output to the server stub.
The server stub then uses the code set value in receiving_tag as the
code set to use for data it sends back to the client.
Application programmers who want their applications to use the
rpc_cs_get_tags routine to retrieve code set tag information as part
of the automatic code set conversion process specify the routine name
as the argument to the ACF attribute cs_tag_rtn when developing their
internationalized RPC application.
Application programmers can also write their own code set tags
retrieval routine that RPC stubs can call; in this case, they specify
the name of this routine as the argument to the ACF attribute instead
of specifying the DCE RPC routine rpc_cs_get_tags. Application
programmers can also use the automatic code conversion mechanism, but
design their applications so that the code set tags are set
explicitly in the application instead of in the stubs.
Related Information
Routines:
cs_byte_from_netcs
cs_byte_local_size
cs_byte_net_size
cs_byte_to_netcs
ΓòÉΓòÉΓòÉ 5.8.35. rpc_ep_register ΓòÉΓòÉΓòÉ
Purpose
Adds to, or replaces, server address information in the local
endpoint map. This routine is used by server applications.
Format
#include <dce/rpc.h>
void rpc_ep_register(
rpc_if_handle_t if_handle,
rpc_binding_vector_t *binding_vec,
uuid_vector_t *object_uuid_vec,
unsigned_char_t *annotation,
unsigned32 *status);
Parameters
Input
if_handle Specifies an interface specification to register with
the local endpoint map.
binding_vec Specifies a vector of binding handles over which the
server can receive remote procedure calls.
Note: The vector must contain fully bound server
binding handles.
object_uuid_vec Specifies a vector of object UUIDs that the server
offers. The server application constructs this vector.
Supply the value NULL to indicate that there are no
object UUIDs to register.
annotation Defines a character string comment applied to each
cross product element added to the local endpoint map.
The string can contain up to 64 characters, including
the NULL terminating character. Specify NULL or the
string \0 if there is no annotation string.
The string is used by applications for informational
purposes only. The RPC runtime does not use this string
to determine the server instance that a client
communicates with or to enumerate endpoint map
elements.
Output
status Returns the status code from this routine. On
successful completion, the routine returns rpc_s_ok.
Otherwise, it returns one of the following errors:
ept_s_cant_access Error reading the
endpoint database.
ept_s_cant_create Error creating the
endpoint database.
ept_s_cant_perform_op Cannot perform
requested operation.
ept_s_database_invalid The endpoint map
database is not
valid.
ept_s_invalid_entry The database entry
is not valid.
ept_s_update_failed Update failed.
rpc_s_comm_failure Communications
failure.
rpc_s_invalid_binding The binding handle
is not valid.
rpc_s_no_bindings No bindings.
rpc_s_wrong_kind_of_binding Wrong kind of
binding for the
operation.
Usage
The rpc_ep_register routine adds elements to, or replaces elements
in, the local host's endpoint map.
Each element in the local endpoint map logically contains the
following:
o Interface ID, consisting of an interface UUID and versions
(major and minor)
o Binding information
o Object UUID (optional)
o Annotation (optional).
A server uses this routine, instead of rpc_ep_register_no_replace,
when only a single instance of the server runs on the server's host.
Use this routine if, at any time, no more than one server instance
offers the same interface UUID, object UUID, and protocol sequence.
When local endpoint map elements are not replaced, obsolete elements
accumulate each time a server instance stops running without calling
rpc_ep_unregister. Periodically the DCE Host daemon (dced) identifies
these obsolete elements and removes them. However, during the time
between these removals the obsolete elements increase the chance that
a client receives endpoints to nonexistent servers. The client then
wastes time trying to communicate with these servers before obtaining
another endpoint.
Using this routine to replace any existing local endpoint map
elements reduces the chance that a client receives the endpoint of a
nonexistent server instance.
If an existing element in the local endpoint map matches the
interface UUID, binding information exclusive of the endpoint, and
object UUID of an element this routine provides, the routine changes
the endpoint map according to the major and minor version numbers of
the element interface as shown in the following table:
ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
Γöé EXISTING ELEMENT Γöé RELATION- Γöé PROVIDED ELEMENT Γöé ROUTINE'S ACTION Γöé
Γöé Γöé SHIP Γöé Γöé Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé Major version Γöé Not equal Γöé Major version Γöé Ignores minor Γöé
Γöé number Γöé to Γöé number Γöé version number Γöé
Γöé Γöé Γöé Γöé relationship and Γöé
Γöé Γöé Γöé Γöé adds a new Γöé
Γöé Γöé Γöé Γöé endpoint map Γöé
Γöé Γöé Γöé Γöé element. The Γöé
Γöé Γöé Γöé Γöé existing element Γöé
Γöé Γöé Γöé Γöé remains Γöé
Γöé Γöé Γöé Γöé unchanged. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé Major version Γöé Equal to Γöé Major version Γöé Acts according Γöé
Γöé number Γöé Γöé number Γöé to the minor Γöé
Γöé Γöé Γöé Γöé version number Γöé
Γöé Γöé Γöé Γöé relationship. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé Minor version Γöé Equal to Γöé Minor version Γöé Replaces the Γöé
Γöé number Γöé Γöé number Γöé endpoint of the Γöé
Γöé Γöé Γöé Γöé existing element Γöé
Γöé Γöé Γöé Γöé based on the Γöé
Γöé Γöé Γöé Γöé provided infor- Γöé
Γöé Γöé Γöé Γöé mation. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé Minor version Γöé Less than Γöé Minor version Γöé Replaces the Γöé
Γöé number Γöé Γöé number Γöé existing element Γöé
Γöé Γöé Γöé Γöé based on the Γöé
Γöé Γöé Γöé Γöé provided infor- Γöé
Γöé Γöé Γöé Γöé mation. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé Minor version Γöé Greater Γöé Minor version Γöé Ignores the pro- Γöé
Γöé number Γöé than Γöé number Γöé vided informa- Γöé
Γöé Γöé Γöé Γöé tion. The Γöé
Γöé Γöé Γöé Γöé existing element Γöé
Γöé Γöé Γöé Γöé remains Γöé
Γöé Γöé Γöé Γöé unchanged. Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
For example, under these circumstances if the existing interface
version number is 1.3 (major.minor) and the provided version number
is 2.0, the routine adds a new endpoint map element with interface
version number 2.0 and does not change the element with version
number 1.3. However, if the existing interface version number is 1.5
and the provided version number is 1.4, the routine does not change
the endpoint map.
A server program that uses rpc_server_use_all_protseqs or
rpc_server_use_protseq has dynamically allocated endpoints. These
servers must call rpc_ep_register or rpc_ep_register_no_replace to
register itself with the local endpoint map.
A server that calls only rpc_server_use_all_protseqs_if or
rpc_server_use_protseq_if does not need to call this routine. In such
cases, the client's runtime uses an endpoint from the client's
interface specification to fill in a partially bound binding handle.
However, it is recommended that you also register well known
endpoints that the server specifies (registering endpoints from
interface definitions is unnecessary).
If the server also exports to the name service database, the server
calls this routine with the same if_handle, binding_vec and
object_uuid_vec parameters as the server uses when calling the
rpc_ns_binding_export routine.
For automatically started servers running over the
connection-oriented protocol sequence ncacn_ip_tcp, the RPC runtime
automatically generates a dynamic endpoint. In this case, the server
can call rpc_server_inq_bindings followed by rpc_ep_register in order
to make itself available to multiple clients. Otherwise, the
automatically started server is known only to the client for which
the server was started.
The rpc_ep_register routine communicates with the DCE Host daemon
(dced) which in turn communicates with the local endpoint map. The
routine communicates using one of the protocol sequences specified in
one of the binding handles in binding_vec. Attempting to register a
binding that specifies a protocol sequence that the DCE Host daemon
is not listening on results in the failure of the rpc_ep_register
routine. The routine indicates this failure by placing the value
rpc_s_comm_failure into status.
For information about how the endpoint map service selects an element
for an interface ID and an object UUID, see the DCE for OS/2
Warp:Application Development Guide - Core Components. This guide
explains how the endpoint map service searches for the endpoint of a
server that is compatible with a client. If the client supplies a
non-nil object UUID that is not in the endpoint map or the client
supplies a nil object UUID, the search can succeed - but only if the
server has registered a nil object UUID using rpc_ep_register or
rpc_ep_register_no_replace. The object_uuid_vec parameter can contain
both nil and non-nil object UUIDs for the routine to place into
endpoint map elements.
For an explanation of how a server can establish a client-server
relationship without using the local endpoint map, see String Binding
for an explanation.
This routine creates a cross-product from the if_handle, binding_vec
and object_uuid_vec parameters, and adds each element in the
cross-product as a separate registration in the local endpoint map.
If you supply NULL to the object_uuid_vec parameter, the
corresponding elements in the cross-product contain a nil object
UUID.
For example, suppose that if_handle has the value ifhand, binding_vec
has the values b1, b2, b3, and object_uuid_vec has the values u1, u2,
u3, u4. The resulting 12 elements in the cross-product are as
follows.
(ifhand,b1,u1) (ifhand,b1,u2) (ifhand,b1,u3) (ifhand,b1,u4)
(ifhand,b2,u1) (ifhand,b2,u2) (ifhand,b2,u3) (ifhand,b2,u4)
(ifhand,b3,u1) (ifhand,b3,u2) (ifhand,b3,u3) (ifhand,b3,u4)
(An annotation string is part of each of these 12 elements.)
Related Information
Routines:
rpc_ep_register_no_replace
rpc_ep_resolve_binding
rpc_ep_unregister
rpc_mgmt_ep_unregister
rpc_ns_binding_export
rpc_server_inq_bindings
rpc_server_use_all_protseqs
rpc_server_use_all_protseqs_if
rpc_server_use_protseq
rpc_server_use_protseq_ep
rpc_server_use_protseq_if
ΓòÉΓòÉΓòÉ 5.8.36. rpc_ep_register_no_replace ΓòÉΓòÉΓòÉ
Purpose
Adds to server address information in the local endpoint map. This
routine is used by server applications.
Format
#include <dce/rpc.h>
void rpc_ep_register_no_replace(
rpc_if_handle_t if_handle,
rpc_binding_vector_t *binding_vec,
uuid_vector_t *object_uuid_vec,
unsigned_char_t *annotation,
unsigned32 *status);
Parameters
Input
if_handle Specifies an interface specification to register with
the local endpoint map.
binding_vec Specifies a vector of binding handles over which the
server can receive remote procedure calls. Note that
the vector must contain fully bound server binding
handles.
object_uuid_vec Specifies a vector of object UUIDs that the server
offers. The server application constructs this vector.
Supply the value NULL to indicate there are no object
UUIDs to register.
annotation Defines a character string comment applied to each
cross-product added to the local endpoint map. The
string can contain up to 64 characters, including the
NULL terminating character. Specify NULL or the string
\0 if there is no annotation string.
The string is used by applications for informational
purposes only. The RPC runtime does not use this string
to determine which server instance a client
communicates with, or for enumerating endpoint map
elements.
Output
status Returns the status code from this routine. On
successful completion, the routine returns rpc_s_ok.
Otherwise, it returns one of the following errors:
ept_s_cant_access Error reading the endpoint
database.
ept_s_cant_create Error creating the endpoint
database.
ept_s_cant_perform_op Cannot perform the requested
operation.
ept_s_database_invalid The endpoint map database
is not valid.
ept_s_invalid_entry The database entry is not
valid.
ept_s_update_failed Update failed.
rpc_s_comm_failure Communications failure.
rpc_s_invalid_binding The binding handle is not
valid.
rpc_s_no_bindings No bindings.
rpc_s_wrong_kind_of_binding Wrong kind of binding
for the operation.
Usage
The rpc_ep_register_no_replace routine adds elements to the local
host's endpoint map. The routine does not replace existing elements.
Otherwise, this routine is identical to rpc_ep_register.
Each element in the local endpoint map logically contains the
following:
o Interface ID, consisting of an interface UUID and versions
(major and minor)
o Binding information
o Object UUID (optional)
o Annotation (optional)
A server uses this routine, instead of rpc_ep_register, when multiple
instances of the server run on the same host. Use this routine if, at
any time, more than one server instance offers the same interface
UUID, object UUID, and protocol sequence.
Since this routine does not replace elements, calling servers must
unregister (that is, remove) themselves before they stop running.
Otherwise, when local endpoint map elements are not replaced,
obsolete elements accumulate each time a server instance stops
running without calling rpc_ep_unregister. Periodically the DCE Host
daemon (dced) identifies obsolete elements and removes them from the
local endpoint map. However, during the time between these removals,
the obsolete elements increase the chance that a client receives
endpoints to nonexistent servers. The client then wastes time trying
to communicate with these servers before obtaining another endpoint.
A server program calls this routine to register endpoints that were
specified by calling any of the following routines:
o rpc_server_use_all_protseqs
o rpc_server_use_protseq
o rpc_server_use_protseq_ep.
A server program that uses rpc_server_use_all_protseqs or
rpc_server_use_protseq has dynamically allocated endpoints. These
servers must call rpc_ep_register or rpc_ep_register_no_replace to
register itself with the local endpoint map.
A server that calls only the rpc_server_use_all_protseqs_if or
rpc_server_use_protseq_if routines does not need to call this
routine. In such cases, the client's runtime uses an endpoint from
the client's interface specification to fill in a partially bound
binding handle. However, it is recommended that you also register
well-known endpoints that the server specifies (registering endpoints
from interface definitions is unnecessary).
If the server also exports to the name service database, the server
calls this routine with the same if_handle, binding_vec and
object_uuid_vec parameters as the server uses when calling
rpc_ns_binding_export.
For automatically started servers running over the
connection-oriented protocol sequence ncacn_ip_tcp, the RPC runtime
automatically generates a dynamic endpoint. In this case, the server
can call rpc_server_inq_bindings followed by
rpc_ep_register_no_replace in order to make itself available to
multiple clients. Otherwise, the automatically started server is
known only to the client for which the server was started.
The rpc_ep_register_no_replace routine communicates with the DCE Host
daemon (dced), which in turn communicates with the local endpoint
map. The routine communicates using one of the protocol sequences
specified in one of the binding handles in the binding_vec parameter.
Attempting to register a binding that specifies a protocol sequence
that the DCE Host daemon is not listening on results in the failure
of the rpc_ep_register_no_replace routine. The routine indicates this
failure by placing the value rpc_s_comm_failure into the status
parameter.
For information about how the endpoint map service selects an element
for an interface ID and an object UUID, see the DCE for OS/2
Warp:Application Development Guide - Core Components. This guide
explains how the endpoint map service searches for the endpoint of a
server that is compatible with a client. If the client supplies a
non-nil object UUID that is not in the endpoint map or the client
supplies a nil object UUID, the search can succeed, but only if the
server has registered a nil object UUID using
rpc_ep_register_no_replace or rpc_ep_register. The object_uuid_vec
parameter can contain both nil and non-nil object UUIDs for the
routine to place into endpoint map elements.
For an explanation of how a server can establish a client-server
relationship without using the local endpoint map, see String Binding
for an explanation.
This routine creates a cross-product from the if_handle, binding_vec
and object_uuid_vec parameters, and adds each element in the
cross-product as a separate registration in the local endpoint map.
If you supply NULL to parameter object_uuid_vec, the corresponding
elements in the cross-product contain a nil object UUID. The
description of rpc_ep_register summarizes the contents of an element
in the local endpoint map.
Related Information
Routines:
rpc_ep_register
rpc_ep_resolve_binding
rpc_ep_unregister
rpc_mgmt_ep_unregister
rpc_ns_binding_export
rpc_server_inq_bindings
rpc_server_use_all_protseqs
rpc_server_use_all_protseqs_if
rpc_server_use_protseq
rpc_server_use_protseq_ep
rpc_server_use_protseq_if
ΓòÉΓòÉΓòÉ 5.8.37. rpc_ep_resolve_binding ΓòÉΓòÉΓòÉ
Purpose
Resolves a partially bound server binding handle into a fully bound
server binding handle. This routine is used by client and management
applications.
Format
#include <dce/rpc.h>
void rpc_ep_resolve_binding(
rpc_binding_handle_t binding,
rpc_if_handle_t if_handle,
unsigned32 *status);
Parameters
Input/Output
binding Specifies a partially bound server binding handle to
resolve into a fully bound server binding handle.
if_handle Contains a stub-generated data structure that specifies
the interface of interest.
Output
status Returns the status code from this routine. On
successful completion, the routine returns rpc_s_ok.
Otherwise, it returns one of the following errors:
ept_s_not_registered No entries found.
rpc_s_invalid_binding The binding handle is not
valid.
rpc_s_wrong_kind_of_binding Wrong kind of binding
for the operation.
rpc_s_rpcd_comm_failure Communications failure
while trying to reach the
endpoint map
Usage
An application calls the rpc_ep_resolve_binding routine to resolve a
partially bound server binding handle into a fully bound server
binding handle.
Resolving binding handles requires an interface UUID and an object
UUID. The object UUID can be a nil UUID. The RPC runtime requests the
DCE Host daemon's Endpoint Mapper Service, on the host that the
binding parameter specifies, to look up an endpoint for a compatible
server instance. The Endpoint Mapper Service finds the endpoint by
looking in the local endpoint map for the interface UUID from the
if_handle parameter and for the object UUID in the binding parameter.
The rpc_ep_resolve_binding routine depends on whether the specified
binding handle is partially bound or fully bound. When the
application specifies a partially bound handle, the routine produces
the following results:
o If no compatible server instances are registered in the local
endpoint map, the routine returns the ept_s_not_registered
status code.
o If one compatible server instance is registered in the local
endpoint map, the routine returns a fully bound binding handle
in the binding parameter and the rpc_s_ok status code.
o If more than one compatible server instance is registered in the
local endpoint map, the routine randomly selects one. It then
returns the corresponding fully bound binding handle in
parameter binding and the rpc_s_ok status code.
When the application specifies a fully bound binding handle, the
routine returns the specified binding handle in binding and the
rpc_s_ok status code. The routine makes no request of the DCE Host
daemon.
In neither the partially bound case nor the fully bound case does the
routine contact a compatible server instance.
Using This Routine
For each server instance, the RPC runtime automatically provides
routines (the rpc_mgmt_xxx routines) that form an RPC management
interface. If a server instance registers any application-provided
interfaces, the RPC runtime automatically registers the RPC-provided
management interface with the local endpoint map for that server
instance.
An application can call rpc_ep_resolve_binding at any time with
either a partially bound or a fully bound handle. However,
applications typically call this routine to avoid calling a routine
in the management interface with a partially bound handle.
An application can have a partially bound binding handle after:
o Importing a binding handle
o Resetting a binding handle
o Converting a string binding without an endpoint to a binding
handle
If an application calls an application-provided remote procedure
using a partially bound handle, the RPC runtime automatically asks
the DCE Host daemon to resolve the binding handle into a fully bound
handle. This fully bound binding handle corresponds to the RPC
interface of the called remote procedure and the requested object, if
any. The application can then use this fully bound handle to make
remote management calls, so calling rpc_ep_resolve_binding is
unnecessary.
When a high proportion of all servers in an environment offers the
same interface, the interface is known as a pervasive one. The RPC
management interface is a pervasive interface in all environments
that use DCE RPC.
Using this routine to unambiguously locate compatible server
instances applies to application-pervasive interfaces as well as to
the RPC management interface.
For each server instance, the RPC runtime provides routines (the
rpc_mgmt_* routines) that form an RPC interface. This management
interface is automatically registered with the runtime. A server
typically does not register the management interface with the local
endpoint map. Even if it does, it would also be a pervasive
interface.
To unambiguously locate a compatible server instance, an application
needs to call rpc_ep_resove_binding before calling a routine in the
management or a pervasive interface.
Partially Bound Handles With a Non-nil Object UUID
If the application has a partially bound handle with a non-nil object
UUID, the application can decide not to call rpc_ep_resolve_binding
before calling a procedure in the management interface. In this case
the remote management call is sent to a server instance, registered
on the remote host, that offers that object UUID.
After completing the remote management call, the application has a
fully bound handle to that server instance. The server instance that
the handle specifies probably offers the non-management interfaces of
interest to the calling application. However, if you want to be
certain of obtaining a fully bound handle to a server instance that
offers the interfaces needed for later remote procedure calls, call
rpc_ep_resolve_binding.
Partially Bound Handles With a Nil Object UUID
When an application makes a remote procedure or management call using
a partially bound handle with a nil object UUID, the DCE Host daemon
searches for a compatible server instance. The search is based on the
nil object UUID and the UUID of the interface to which the call
belongs.
All server instances that register any RPC interface automatically
offer the RPC management interface. When an application makes a
remote management call using a partially bound handle with a nil
object UUID, the DCE Host daemon on the remote host cannot
distinguish among server instances registered in the local endpoint
map.
When the DCE Host daemon cannot distinguish among these instances it
selects any server instance. After completing the remote management
call the calling application has a fully bound handle. However, the
server instance that the handle represents probably does not offer
the non-management interfaces that interest the application.
The remote RPC management routines avoid this ambiguity. They do this
by returning the status rpc_s_binding_incomplete if the provided
binding handle is a partially bound one with a nil object UUID.
An application wanting to contact servers that have exported and
registered interfaces with a nil object UUID calls the
rpc_ep_resolve_binding routine. The application obtains a fully bound
binding handle for calling remote management procedures in a server
instance that also offers the remote procedures in the
application-specific interface. Note that an application that wants
to manage all the server instances on a host does not call
rpc_ep_resolve_binding. Instead, the application obtains fully bound
binding handles for each server instance by calling
rpc_mgmt_ep_elt_inq_begin, rpc_mgmt_ep_elt_inq_next, and
rpc_mgmt_ep_elt_inq_done.
Related Information
Routines:
rpc_ep_register
rpc_ep_register_no_replace
rpc_mgmt_ep_elt_inq_begin
rpc_mgmt_ep_elt_inq_done
rpc_mgmt_ep_elt_inq_next
rpc_binding_from_string_binding
rpc_binding_reset
ΓòÉΓòÉΓòÉ 5.8.38. rpc_ep_unregister ΓòÉΓòÉΓòÉ
Purpose
Removes server address information from the local endpoint map. This
routine is used by server applications.
Format
#include <dce/rpc.h>
void rpc_ep_unregister(
rpc_if_handle_t if_handle,
rpc_binding_vector_t *binding_vec,
uuid_vector_t *object_uuid_vec,
unsigned32 *status);
Parameters
Input
if_handle Specifies an interface specification to remove (that
is, unregister) from the local endpoint map.
binding_vec Specifies a vector of binding handles to remove.
object_uuid_vec Specifies a vector of object UUIDs to remove. The
server application constructs this vector. This routine
removes all local endpoint map elements that match the
specified if_handle parameter, binding_vec parameter,
and object UUIDs.
This is an optional parameter. The value NULL indicates
there are no object UUIDs to remove.
Output
status Returns the status code from this routine. On
successful completion, the routine returns rpc_s_ok.
Otherwise, it returns one of the following errors:
ept_s_cant_access Error reading the
endpoint database.
ept_s_cant_create Error creating the
endpoint database.
ept_s_cant_perform_op Cannot perform the
requested operation.
ept_s_database_invalid The endpoint map
database is not
valid.
ept_s_invalid_entry The database entry
is not valid.
ept_s_update_failed Update failed.
rpc_s_invalid_binding The binding handle
is not valid.
rpc_s_no_bindings No bindings.
rpc_s_wrong_kind_of_binding Wrong kind of
binding for the
operation.
Usage
The rpc_ep_unregister routine removes elements from the local host's
endpoint map. A server application calls this routine only if the
server has registered endpoints previously and the server wishes to
remove that address information from the local endpoint map.
A server program is able to remove its own local endpoint map
elements (server address information) based on either of the
following:
o The interface specification
o The interface specification and the object UUIDs of resources
offered
The server calls the rpc_server_inq_bindings routine to obtain the
required binding_vec parameter. To remove selected endpoints, the
server can remove individual elements from binding_vec before calling
this routine. See Binding Vector for more information about removing
a single element from a vector of binding handles.
This routine creates a cross-product from the if_handle, binding_vec
and object_uuid_vec parameters and removes each element in the
cross-product from the local endpoint map. The description of the
rpc_ep_register routine summarizes the contents of a cross-product in
the local endpoint map.
Servers must always call rpc_ep_unregister to remove their endpoints
from the local endpoint map before they exit. Otherwise, stale
information will be in the local endpoint map. However, if a server
prematurely removes endpoints (the server is not in the process of
exiting), clients that do not already have fully bound binding
handles to the server will not be able to send remote procedure calls
to the server.
Related Information
Routines:
rpc_ep_register
rpc_ep_register_no_replace
rpc_mgmt_ep_unregister
rpc_ns_binding_unexport
rpc_server_inq_bindings
ΓòÉΓòÉΓòÉ 5.8.39. rpc_if_id_vector_free ΓòÉΓòÉΓòÉ
Purpose
Frees a vector and the interface identifier structures it contains.
This routine is used by client, server, or management applications.
Format
#include <dce/rpc.h>
void rpc_if_id_vector_free(
rpc_if_id_vector_t **if_id_vector,
unsigned32 *status);
Parameters
Input/Output
if_id_vector Specifies the address of a pointer to a vector of
interface information. On return, the pointer is set to
NULL.
Output
status Returns the status code from this routine. On
successful completion, the routine returns rpc_s_ok.
Otherwise, it returns rpc_s_invalid_arg, which
indicates that the argument is not valid.
Usage
The rpc_if_id_vector_free routine frees the memory used to store a
vector of interface identifiers. This includes memory used by the
interface identifiers and the vector itself. On return this routine
sets the if_id_vector parameter to NULL.
To obtain a vector of interface identifiers, call the
rpc_ns_mgmt_entry_inq_if_ids or rpc_mgmt_inq_if_ids. Call
rpc_if_id_vector_free if you have used either of these routines.
Related Information
Routines:
rpc_if_inq_id
rpc_mgmt_inq_if_ids
rpc_ns_mgmt_entry_inq_if_ids
ΓòÉΓòÉΓòÉ 5.8.40. rpc_if_inq_id ΓòÉΓòÉΓòÉ
Purpose
Returns the interface identifier for an interface specification. This
routine is used by client or server applications.
Format
#include <dce/rpc.h>
void rpc_if_inq_id(
rpc_if_handle_t if_handle,
rpc_if_id_t *if_id,
unsigned32 *status);
Parameters
Input
if_handle Represents a stub-generated data structure that
specifies the interface specification to inquire about.
Output
if_id Returns the interface identifier. The application
provides memory for the returned data.
status Returns the status code from this routine. On
successful completion, the routine returns rpc_s_ok.
Otherwise, it returns an error.
Usage
An application calls the rpc_if_inq_id routine to obtain a copy of
the interface identifier from the provided interface specification.
The returned interface identifier consists of the interface UUID and
interface version numbers (major and minor) specified in the DCE IDL
file's interface specification.
Related Information
Routines:
rpc_if_id_vector_free
rpc_mgmt_inq_if_ids
rpc_ns_mgmt_entry_inq_if_ids
ΓòÉΓòÉΓòÉ 5.8.41. rpc_mgmt_ep_elt_inq_begin ΓòÉΓòÉΓòÉ
Purpose
Creates an inquiry context for viewing the elements in an endpoint
map. This routine is used by management applications.
Format
#include <dce/rpc.h>
void rpc_mgmt_ep_elt_inq_begin(
rpc_binding_handle_t ep_binding,
unsigned32 inquiry_type,
rpc_if_id_t *if_id,
unsigned32 vers_option,
uuid_t *object_uuid,
rpc_ep_inq_handle_t *inquiry_context,
unsigned32 *status);
Parameters
Input
ep_binding Specifies the host for the local endpoint map elements
you receive. To receive elements from the same host as
the calling application, specify NULL.
To receive local endpoint map elements from another
host, specify a server binding handle for that host.
You can specify the same binding handle you are using
to make other remote procedure calls. The object UUID
associated with this parameter must be a nil UUID. If
you specify a non-nil UUID, the routine fails with the
status code ept_s_cant_perform_op. Other than the host
information and object UUID, all information in this
parameter is ignored.
inquiry_type Specifies an integer value that indicates the type of
inquiry to perform on the local endpoint map. The list
shows the valid inquiry types:
Value Description
rpc_c_ep_all_elts Returns every element from the
local endpoint map.
The if_id, vers_option, and
object_uuid parameters are
ignored.
rpc_c_ep_match_by_if Searches the local endpoint
map for those elements that
contain the interface identifier
specified by the if_id and
vers_option values. The
object_uuid parameter is
ignored.
rpc_c_ep_match_by_obj Searches the local endpoint
map for those elements that
contain the object UUID
specified by the object_uuid
parameter. The if_id and
vers_option parameters are
ignored.
rpc_c_ep_match_by_both Searches the local endpoint
map for those elements that
contain the interface identifier
and object UUID specified by the
if_id, vers_option, and
object_uuid parameters.
if_id Specifies the interface identifier of the local
endpoint map elements to be returned by
rpc_mgmt_ep_elt_inq_next.
Use this parameter only when specifying a value of
rpc_c_ep_match_by_if or rpc_c_ep_match_by_both for the
inquiry_type parameter. Otherwise, this parameter is
ignored and the value NULL can be specified.
vers_option Specifies how the rpc_mgmt_ep_elt_inq_next routine uses
the if_id parameter. Use this parameter only when
specifying a value of rpc_c_ep_match_by_if or
rpc_c_ep_match_by_both for the inquiry_type parameter.
Otherwise, this parameter is ignored and a 0 (zero)
value can be specified.
The following list presents the valid values for this
parameter:
Value Description
rpc_c_vers_all Returns local endpoint map
elements that offer the specified
interface UUID, regardless of the
version numbers.
For this value, specify 0 (zero)
for both the major and minor
versions in if_id.
rpc_c_vers_compatible Returns local endpoint map
elements that offer the same
major version of the specified
interface UUID and a minor
version greater than or equal to
the minor version of the
specified interface UUID.
rpc_c_vers_exact Returns local endpoint map
elements that offer the specified
version of the specified
interface UUID.
rpc_c_vers_major_only Returns local endpoint map
elements that offer the same
major version of the specified
interface UUID (ignores the minor
version). For this value, specify
0 (zero) for the minor version in
if_id.
rpc_c_vers_upto Returns local endpoint map
elements that offer a version of
the specified interface UUID less
than or equal to the specified
major and minor version. (For
example, suppose if_id contains
V2.0 and the local endpoint map
contained elements with the
following versions: V1.3, V2.0,
and V2.1. The
rpc_mgmt_ep_elt_inq_next routine
returns the elements with V1.3
and V2.0.)
object_uuid Specifies the object UUID that rpc_mgmt_ep_elt_inq_next
looks for in local endpoint map elements.
This parameter is used only when you specify a value of
rpc_c_ep_match_by_obj or rpc_c_ep_match_by_both for the
inquiry_type parameter. Otherwise, this parameter is
ignored and you can supply NULL to specify a nil UUID.
Output
inquiry_context Returns an inquiry context for use with the
rpc_mgmt_ep_elt_inq_next and rpc_mgmt_ep_elt_inq_done
routines.
status Returns the status code from this routine. On
successful completion, the routine returns rpc_s_ok.
Otherwise, it returns one of the following errors:
rpc_s_invalid_inquiry_context The inquiry context
is not valid.
rpc_s_invalid_inquiry_type The inquiry type is not
valid.
rpc_s_invalid_vers_option The version option is
not valid.
rpc_s_wrong_kind_of_binding Wrong kind of binding
for the operation.
Usage
The rpc_mgmt_ep_elt_inq_begin routine creates an inquiry context for
viewing server address information stored in the local endpoint map.
Using the inquiry_type and vers_option parameters, an application
specifies which of the following local endpoint map elements are
returned from calls to rpc_mgmt_ep_elt_inq_next:
o All elements.
o Those elements with the specified interface identifier.
o Those elements with the specified object UUID.
o Those elements with both the specified interface identifier and
object UUID.
Before calling rpc_mgmt_ep_elt_inq_next, the application must first
call this routine to create an inquiry context.
After viewing the local endpoint map elements, the application calls
rpc_mgmt_ep_elt_inq_done to delete the inquiry context.
Related Information
Routines:
rpc_ep_register
rpc_ep_register_no_replace
rpc_ep_unregister
rpc_mgmt_ep_elt_inq_done
rpc_mgmt_ep_elt_inq_next
rpc_mgmt_ep_unregister
ΓòÉΓòÉΓòÉ 5.8.42. rpc_mgmt_ep_elt_inq_done ΓòÉΓòÉΓòÉ
Purpose
Deletes the inquiry context for viewing the elements in an endpoint
map. This routine is used by management applications.
Format
#include <dce/rpc.h>
void rpc_mgmt_ep_elt_inq_done(
rpc_ep_inq_handle_t *inquiry_context,
unsigned32 *status);
Parameters
Input/Output
inquiry_context Specifies the inquiry context to delete. (An inquiry
context is created by calling
rpc_mgmt_ep_elt_inq_begin.) Returns the value NULL.
Output
status Returns the status code from this routine. On
successful completion, the routine returns rpc_s_ok.
Otherwise, it returns the following error:
rpc_s_invalid_inquiry_context The inquiry context
is not valid.
Usage
The rpc_mgmt_ep_elt_inq_done routine deletes an inquiry context. The
rpc_mgmt_ep_elt_inq_begin routine created the inquiry context.
An application calls this routine after viewing local endpoint map
elements using the rpc_mgmt_ep_elt_inq_next routine.
Related Information
Routines:
rpc_mgmt_ep_elt_inq_begin
rpc_mgmt_ep_elt_inq_next
ΓòÉΓòÉΓòÉ 5.8.43. rpc_mgmt_ep_elt_inq_next ΓòÉΓòÉΓòÉ
Purpose
Returns one element from an endpoint map. This routine is used by
management applications.
Format
#include <dce/rpc.h>
void rpc_mgmt_ep_elt_inq_next(
rpc_ep_inq_handle_t inquiry_context,
rpc_if_id_t *if_id,
rpc_binding_handle_t *binding,
uuid_t *object_uuid,
unsigned_char_t **annotation,
unsigned32 *status);
Parameters
Input
inquiry_context Specifies an inquiry context. This inquiry context is
returned from the rpc_mgmt_ep_elt_inq_begin routine.
Output
if_id Returns the interface identifier of the local endpoint
map element.
binding Returns the binding handle from the local endpoint map
element.
Specify NULL to prevent the routine from returning this
parameter. In this case, the application does not call
rpc_binding_free.
object_uuid Returns the object UUID from the local endpoint map
element. Specify NULL to prevent the routine from
returning this parameter.
annotation Returns the annotation string for the local endpoint
map element. If there is no annotation string in the
local endpoint map element, the string \0 is returned.
Specify NULL to prevent the routine from returning this
parameter. In this case, the application does not call
rpc_string_free.
status Returns the status code from this routine. On
successful completion, the routine returns rpc_s_ok.
Otherwise, it returns one of the following errors:
ept_s_cant_perform_op Cannot perform requested
operation.
rpc_s_comm_failure Communications failure.
ept_s_database_invalid The endpoint map database
is not valid.
rpc_s_fault_context_mismatch Fault context
mismatch.
ept_s_invalid_context The inquiry type for this
context is not valid.
ept_s_invalid_entry The database entry is not
valid.
rpc_s_invalid_arg The argument is not valid.
rpc_s_invalid_inquiry_context The inquiry context
is not valid.
rpc_s_invalid_inquiry_type The inquiry type is not
valid.
rpc_s_no_more_elements No more elements.
Usage
The rpc_mgmt_ep_elt_inq_next routine returns one element from the
local endpoint map. Regardless of the selector value specified for
the inquiry_type parameter in rpc_mgmt_ep_elt_inq_begin, this routine
returns all the components of a selected local endpoint map element.
The description of rpc_ep_register summarizes the contents of an
element in the local endpoint map.
An application can view all the selected local endpoint map elements
by repeatedly calling rpc_mgmt_ep_elt_inq_next. When all the elements
have been viewed, this routine returns an rpc_s_no_more_elements
status. The returned elements are unordered.
If a remote endpoint map contains elements that include a protocol
sequence that your system does not support, this routine does not
return the elements. (A protocol sequence is part of the binding
information component of an endpoint map element.) To receive all
possible elements from a remote endpoint map, your application must
run on a system that supports the protocol sequences included in the
elements.
For example, if your system does not support protocol sequence
ncacn_ip_tcp and a remote endpoint map contains elements that include
this protocol sequence, this routine does not return these elements
to your application. If your application runs on a system that
supported protocol sequence ncacn_ip_tcp, this routine returns the
elements.
The RPC runtime allocates memory for the returned binding and the
annotation string on each call to this routine. The application calls
rpc_binding_free for each returned binding and rpc_string_free for
each returned annotation string.
After viewing the local endpoint map's elements, the application must
call rpc_mgmt_ep_elt_inq_done to delete the inquiry context.
Related Information
Routines:
rpc_binding_free
rpc_ep_register
rpc_ep_register_no_replace
rpc_mgmt_ep_elt_inq_begin
rpc_mgmt_ep_elt_inq_done
rpc_string_free
ΓòÉΓòÉΓòÉ 5.8.44. rpc_mgmt_ep_unregister ΓòÉΓòÉΓòÉ
Purpose
Removes server address information from an endpoint map. This routine
is used by management applications.
Format
#include <dce/rpc.h>
void rpc_mgmt_ep_unregister(
rpc_binding_handle_t ep_binding,
rpc_if_id_t *if_id,
rpc_binding_handle_t binding,
uuid_t *object_uuid,
unsigned32 *status);
Parameters
Input
ep_binding Specifies the host whose local endpoint map elements
you unregister (that is, remove). To remove elements
from the same host as the calling application, specify
NULL.
To remove local endpoint map elements from another
host, specify a server binding handle for that host.
You can specify the same binding handle you are using
to make other remote procedure calls. The object UUID
associated with this parameter must be a nil UUID. If
you specify a non-nil UUID, the routine fails with the
status code ept_s_cant_perform_op. Other than the host
information and object UUID, all information in this
parameter is ignored.
if_id Specifies the interface identifier to remove from the
local endpoint map.
binding Specifies the binding handle to remove.
object_uuid Specifies an optional object UUID to remove.
The value NULL indicates there is no object UUID to
consider in the removal.
Output
status Returns the status code from this routine. On
successful completion, the routine returns rpc_s_ok.
Otherwise, it returns one of the following errors:
ept_s_cant_access Error reading the endpoint
database.
ept_s_cant_perform_op Cannot perform the requested
operation.
rpc_s_comm_failure Communications failure.
ept_s_database_invalid Endpoint map database is
invalid.
ept_s_invalid_entry The database entry is not
valid.
ept_s_not_registered No entries found.
ept_s_update_failed Update failed.
rpc_s_invalid_binding The binding handle is not
valid.
rpc_s_no_interfaces No interfaces registered.
rpc_s_wrong_kind_of_binding Wrong kind of binding
for the operation.
Usage
The rpc_mgmt_ep_unregister routine unregisters (that is, removes) an
element from an endpoint map. A management program calls this routine
to remove addresses of servers that are no longer available, or to
remove addresses of servers that support objects that are no longer
offered.
Use this routine cautiously; removing elements from the local
endpoint map may make servers unavailable to client applications that
do not already have a fully bound binding handle to the server.
A management application calls the rpc_mgmt_ep_inq_next routine to
view local endpoint map elements. The application can then remove the
elements using rpc_mgmt_ep_unregister.
Related Information
Routines:
rpc_ep_register
rpc_ep_register_no_replace
rpc_ns_binding_unexport
rpc_mgmt_ep_elt_inq_begin
rpc_mgmt_ep_elt_inq_done
rpc_mgmt_ep_elt_inq_next
ΓòÉΓòÉΓòÉ 5.8.45. rpc_mgmt_inq_com_timeout ΓòÉΓòÉΓòÉ
Purpose
Returns the communication timeout value in a binding handle. This
routine is used by client applications.
Format
#include <dce/rpc.h>
void rpc_mgmt_inq_com_timeout(
rpc_binding_handle_t binding,
unsigned32 *timeout,
unsigned32 *status);
Parameters
Input
binding Specifies a server binding handle.
Output
timeout Returns the communication timeout value from the
binding parameter.
status Returns the status code from this routine. On
successful completion, the routine returns rpc_s_ok.
Otherwise, it returns one of the following errors:
rpc_s_invalid_binding The binding handle is not
valid.
rpc_s_wrong_kind_of_binding Wrong kind of binding
for the operation.
Usage
The rpc_mgmt_inq_com_timeout routine returns the communication
timeout value in a server binding handle. The timeout value specifies
the relative amount of time to spend trying to communicate with the
server. The time-out value has no effect on the normal processing of
a remote procedure. A remote procedure can run for as long as it
requires. Depending on the protocol sequence for the specified
binding handle, the value in the timeout parameter acts only as
advice to the RPC runtime.
The rpc_mgmt_set_com_timeout reference page explains the timeout
values returned in timeout.
To change the timeout value, a client calls rpc_mgmt_set_com_timeout.
Related Information
Routines:
rpc_mgmt_set_com_timeout
ΓòÉΓòÉΓòÉ 5.8.46. rpc_mgmt_inq_dflt_protect_level ΓòÉΓòÉΓòÉ
Purpose
Returns the default protection level for an authentication service.
This routine is used by client and server applications.
Format
#include <dce/rpc.h>
void rpc_mgmt_inq_dflt_protect_level(
unsigned32 authn_svc,
unsigned32 *protect_level,
unsigned32 *status);
Parameters
Input
authn_svc Specifies the authentication service for which to
return the default protection level.
The supported authentication services are:
rpc_c_authn_none No authentication.
rpc_c_authn_dce_secret DCE shared-secret key
authentication.
rpc_c_authn_dce_public DCE public key
authentication (reserved for
future use).
rpc_c_authn_default DCE default authentication
service.
Output
protect_level Returns the default protection level for the specified
authentication service. The protection level determines
the degree to which authenticated communications
between the client and the server are protected.
The possible protection levels are as follows:
rpc_c_protect_level_default Uses the default
protection level for the
specified authentication
service.
rpc_c_protect_level_none Performs no protection.
rpc_c_protect_level_connect Performs protection
only when the client
establishes a relationship
with the server.
rpc_c_protect_level_call Performs protection only
at the beginning of each
remote procedure call when
the server receives the
request.
rpc_c_protect_level_pkt Ensures that all data
received is from the
expected client.
rpc_c_protect_level_pkt_integ Ensures and verifies
that none of the data
transferred between client
and server has been
modified.
rpc_c_protect_level_cdmf_priv Performs protection
as specified by all of the
previous levels and also
encrypts each remote
procedure call parameter
value. This protection level
provides a lower level of
packet privacy than
rpc_c_protect_level_pkt_privacy.
rpc_c_protect_level_pkt_privacy Performs
protection as specified by
all of the previous levels
and also encrypts each
remote procedure call
parameter value.
status Returns the status code from this routine. On
successful completion, the routine returns rpc_s_ok.
Otherwise, it returns the following error:
rpc_s_unknown_authn_service Unknown authentication
service.
Usage
The rpc_mgmt_inq_dflt_protect_level routine returns the default
protection level for the specified authentication service.
A client can call this routine to learn the default protection level
before specifying rpc_c_protect_level_default for the protect_level
parameter in rpc_binding_set_auth_info. If the default level is
inappropriate, the client can specify a different, explicit level.
A called remote procedure within a server application can call this
routine to obtain the default protection level for a given
authentication service. By calling rpc_binding_inq_auth_client in the
remote procedure, the server can obtain the protection level set up
by the calling client. The server can then compare the
client-specified protection level with the default level to determine
whether to allow the remote procedure to run.
Alternatively, a remote procedure can compare the client's protection
level against a level other than the default level. In this case,
there is no need for the server's remote procedure to call this
routine.
Related Information
Routines:
rpc_binding_inq_auth_client
rpc_binding_set_auth_info
ΓòÉΓòÉΓòÉ 5.8.47. rpc_mgmt_inq_if_ids ΓòÉΓòÉΓòÉ
Purpose
Returns a vector of interface identifiers of the interfaces a server
offers. This routine is used by client, server, or management
applications.
Format
#include <dce/rpc.h>
void rpc_mgmt_inq_if_ids(
rpc_binding_handle_t binding,
rpc_if_id_vector_t **if_id_vector,
unsigned32 *status);
Parameters
Input
binding Specifies a binding handle. To receive interface
identifiers from a remote application, specify a server
binding handle for that application. To receive
interface information about your own (local)
application, specify NULL.
If the binding handle you supply refers to partially
bound binding information and the binding information
contains a nil object UUID, this routine returns the
rpc_s_binding_incomplete status code. In this case, the
DCE Host daemon (dced) does not know which server
instance to select from the local endpoint map because
the RPC management interface is automatically
registered with the runtime (by the runtime) for all
RPC servers.
You can avoid this situation by calling the
rpc_ep_resolve_binding routine to obtain a fully bound
server binding handle.
Output
if_id_vector Returns the address of an interface identifier vector.
status Returns the status code from this routine. On
successful completion, the routine returns rpc_s_ok.
Otherwise, it returns one of the following errors:
rpc_s_binding_incomplete Binding incomplete (no
object ID and no endpoint).
rpc_s_comm_failure Communications failure.
rpc_s_invalid_arg The argument is not valid.
rpc_s_invalid_binding The binding handle is not
valid.
rpc_s_no_interfaces No interfaces registered.
rpc_s_mgmt_op_disallowed The management operation
is disallowed.
rpc_s_wrong_kind_of_binding Wrong kind of binding
for the operation.
In addition to the preceding values, status can return the value of
the status parameter from the application-defined authorization
routine (rpc_mgmt_authorization_fn_t). The prototype for such a
routine is defined in the authorization_fn parameter in
rpc_mgmt_set_authorization_fn.
Usage
An application calls the rpc_mgmt_inq_if_ids routine to obtain a
vector of interface identifiers listing the interfaces registered by
a server with the RPC runtime.
If a server has not registered any interfaces with the runtime, this
routine returns a rpc_s_no_interfaces status code and an if_id_vector
parameter value of NULL.
The application calls the rpc_if_id_vector_free routine to release
the memory used by the vector.
By default, the RPC runtime allows all clients to remotely call this
routine. To restrict remote calls of this routine, a server
application supplies an authorization routine using
rpc_mgmt_set_authorization_fn.
Related Information
Routines:
rpc_ep_resolve_binding
rpc_if_id_vector_free
rpc_mgmt_set_authorization_fn
rpc_server_register_if
ΓòÉΓòÉΓòÉ 5.8.48. rpc_mgmt_inq_server_princ_name ΓòÉΓòÉΓòÉ
Purpose
Returns a server's principal name. This routine is used by client,
server, or management applications.
Format
#include <dce/rpc.h>
void rpc_mgmt_inq_server_princ_name(
rpc_binding_handle_t binding,
unsigned32 authn_svc,
unsigned_char_t **server_princ_name,
unsigned32 *status);
Parameters
Input
binding Specifies a binding handle. If a client application
wants the principal name from a server application,
supply a server binding handle for that server. To
enable a server application to receive its own
principal name, supply the value NULL.
If the binding handle you supply refers to partially
bound binding information and the binding information
contains a nil object UUID, this routine returns the
rpc_s_binding_incomplete status code. In this case, the
DCE Host daemon (dced) does not know which server
instance to select from the local endpoint map because
the RPC runtime automatically registers the RPC
management interface for all RPC servers.
You can avoid this situation by calling
rpc_ep_resolve_binding to obtain a fully bound server
binding handle.
authn_svc Specifies the authentication service for which a
principal name is returned. To obtain a list of
supported authentication services, see the description
of authn_svc in rpc_binding_set_auth_info.
Output
server_princ_name Returns a principal name. This name is registered
for the authentication service in the authn_svc
parameter by the server referenced in the binding
parameter. If the server registered multiple principal
names, only one of them is returned.
status Returns the status code from this routine. On
successful completion, the routine returns rpc_s_ok.
Otherwise, it returns one of the following errors:
rpc_s_binding_incomplete Binding incomplete (no
object ID and no
endpoint).
rpc_s_comm_failure Communications failure.
rpc_s_mgmt_op_disallowed The management operation
is disallowed.
rpc_s_unknown_authn_service Unknown authentication
service.
rpc_s_wrong_kind_of_binding Wrong kind of binding
for the operation.
sec_s_none_registered The server has not
registered the server
name.
In addition to the preceding values, status can return
the value of the status parameter from the
application-defined authorization routine
(rpc_mgmt_authorization_fn_t). The prototype for such a
routine is defined in the authorization_fn parameter in
the rpc_mgmt_set_authorization_fn routine.
Usage
An application calls rpc_mgmt_inq_server_princ_name to obtain the
principal name a server registered for a specified authentication
service.
A client (or management) application uses this routine when it wants
to allow one-way authentication with the server specified by binding.
This means that the client does not care which server principal
receives the remote procedure call request. However, the server
verifies that the client is who the client claims to be. For one-way
authentication, a client calls this routine before calling
rpc_binding_set_auth_info.
A server application uses this routine to obtain the principal name
it registered by calling rpc_server_register_auth_info.
The RPC runtime allocates memory for the string returned in the
server_princ_name parameter. The application calls rpc_string_free
to deallocate that memory.
By default, the RPC runtime allows all clients to call this routine
remotely. To restrict these calls, a server application supplies an
authorization routine by calling rpc_mgmt_set_authorization_fn.
Related Information
Routines:
rpc_binding_inq_object
rpc_binding_set_auth_info
rpc_ep_resolve_binding
rpc_mgmt_set_authorization_fn
rpc_server_register_auth_info
rpc_string_free
uuid_is_nil
ΓòÉΓòÉΓòÉ 5.8.49. rpc_mgmt_inq_stats ΓòÉΓòÉΓòÉ
Purpose
Returns RPC runtime statistics. This routine is used by client,
server, or management applications.
Format
#include <dce/rpc.h>
void rpc_mgmt_inq_stats(
rpc_binding_handle_t binding,
rpc_stats_vector_t **statistics,
unsigned32 *status);
Parameters
Input
binding Specifies a binding handle. To receive statistics about
a remote application, specify a server binding handle
for that application. To receive statistics about your
own (local) application, specify NULL.
If the binding handle you supply refers to partially
bound binding information and the binding information
contains a nil object UUID, this routine returns the
rpc_s_binding_incomplete status code. In this case, the
DCE Host daemon (dced) does not know which server
instance to select from the local endpoint map because
the RPC management interface is automatically
registered by the runtime for all RPC servers.
You can avoid this situation by calling
rpc_ep_resolve_binding to obtain a fully bound server
binding handle.
Output
statistics Returns the statistics vector for the server specified
by the binding parameter. Each statistic is a value of
the type unsigned32.
status Returns the status code from this routine. On
successful completion, the routine returns rpc_s_ok.
Otherwise, it returns one of the following errors:
rpc_s_binding_incomplete Binding incomplete (no
object ID and no endpoint).
rpc_s_comm_failure Communications failure.
rpc_s_invalid_binding The binding handle is not
valid.
rpc_s_mgmt_op_disallowed The management operation
is disallowed.
rpc_s_wrong_kind_of_binding Wrong kind of binding
for the operation.
In addition to the above values, status can return the
value of parameter status from the application-defined
authorization routine (rpc_mgmt_authorization_fn_t).
The prototype for such a routine is defined in the
authorization_fn parameter in
rpc_mgmt_set_authorization_fn.
Usage
The rpc_mgmt_inq_stats routine returns statistics from the RPC
runtime about a specified server. The RPC runtime allocates memory
for the statistics vector. The application calls
rpc_mgmt_stat_vector_free to release the memory that the statistics
vector used. See Statistics Vector, which lists the elements of the
vector.
By default, the RPC runtime allows all clients to remotely call this
routine. To restrict remote calls of this routine, a server
application supplies an authorization routine using
rpc_mgmt_set_authorization_fn.
Related Information
Routines:
rpc_ep_resolve_binding
rpc_mgmt_set_authorization_fn
rpc_mgmt_stats_vector_free
ΓòÉΓòÉΓòÉ 5.8.50. rpc_mgmt_is_server_listening ΓòÉΓòÉΓòÉ
Purpose
Tells whether a server is listening for remote procedure calls. This
routine is used by client, server, or management applications.
Format
#include <dce/rpc.h>
boolean32 rpc_mgmt_is_server_listening(
rpc_binding_handle_t binding,
unsigned32 *status);
Parameters
Input
binding Specifies a server binding handle. To determine if a
remote application is listening for remote procedure
calls, specify a server binding handle for that
application. To determine if your own (local)
application is listening for remote procedure calls,
specify NULL.
If the binding handle you supply refers to partially
bound binding information and the binding information
contains a nil object UUID, this routine returns the
rpc_s_binding_incomplete status code. In this case, the
DCE Host daemon (dced) does not know which server
instance to select from the local endpoint map because
the RPC management interface is automatically
registered by the runtime for all RPC servers.
You can avoid this situation by calling the
rpc_ep_resolve_binding routine to obtain a fully bound
server binding handle.
Output
status Returns the status code from this routine. On
successful completion, the routine returns rpc_s_ok.
Otherwise, it returns one of the following errors:
rpc_s_binding_incomplete Binding incomplete (no
object ID and no endpoint).
rpc_s_comm_failure Communications failure.
rpc_s_invalid_binding The binding handle is not
valid.
rpc_s_mgmt_op_disallowed The management operation
is disallowed.
rpc_s_wrong_kind_of_binding Wrong kind of binding
for the operation.
In addition to the above values, status can return the
value of the status parameter from the
application-defined authorization routine
(rpc_mgmt_authorization_fn_t). The prototype for such a
routine is defined in the authorization_fn parameter in
rpc_mgmt_set_authorization_fn.
Usage
The rpc_mgmt_is_server_listening routine determines whether the
server specified in the binding parameter is listening for remote
procedure calls.
This routine returns a value of TRUE if the server is blocked in the
rpc_server_listen routine.
By default, the RPC runtime allows all clients to remotely call this
routine. To restrict remote calls of this routine, a server
application supplies an authorization routine using
rpc_mgmt_set_authorization_fn.
Return Codes
Your program must examine the return value of the status parameter
and the return value of the routine to understand the meaning of the
routine value. The following table summarizes the values that this
routine can return:
ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
Γöé Table 6. Values Returned by the rpc_mgmt_is_server_listening Routine Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé VALUE Γöé STATUS CODE Γöé EXPLANATION Γöé
Γöé RETURNED Γöé Γöé Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé TRUE Γöé RPC_S_OK Γöé The specified server is Γöé
Γöé Γöé Γöé listening for remote pro- Γöé
Γöé Γöé Γöé cedure calls. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé FALSE Γöé ONE OF THE STATUS CODES Γöé The specified server is Γöé
Γöé Γöé LISTED FOR THE status Γöé not listening for remote Γöé
Γöé Γöé PARAMETER Γöé procedure calls, or the Γöé
Γöé Γöé Γöé server cannot be reached. Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
Related Information
Routines:
rpc_ep_resolve_binding
rpc_mgmt_set_authorization_fn
rpc_server_listen
ΓòÉΓòÉΓòÉ 5.8.51. rpc_mgmt_set_authorization_fn ΓòÉΓòÉΓòÉ
Purpose
Establishes an authorization routine for processing remote calls to a
server's management routines. This routine is used by server
applications.
Format
#include <dce/rpc.h>
void rpc_mgmt_set_authorization_fn(
rpc_mgmt_authorization_fn_t authorization_fn,
unsigned32 *status);
Parameters
Input
authorization_fn Specifies a pointer to an authorization routine. The
RPC server runtime automatically calls this routine
whenever the server runtime receives a client request
to run one of the RPC management routines.
Specify NULL to unregister a previously registered
authorization routine. In this case, the default
authorizations (as described later) are used.
The following C definition for
rpc_mgmt_authorization_fn_t illustrates the prototype
for the authorization routine:
typedef boolean32 (*rpc_mgmt_authorization_fn_t)
(
rpc_binding_handle_t client_binding, /* in */
unsigned32 requested_mgmt_operation, /* in */
unsigned32 *status /* out */
);
The following list shows the requested_mgmt_operation
values passed by the RPC runtime to the authorization
routine:
Called Remote Routine
requested_mgmt_operation
Value
rpc_mgmt_inq_if_ids
rpc_c_mgmt_inq_if_ids
rpc_mgmt_inq_server_princ_name
rpc_c_mgmt_inq_princ_name
rpc_mgmt_inq_stats
rpc_c_mgmt_inq_stats
rpc_mgmt_is_server_listening
rpc_c_mgmt_is_server_listen
rpc_mgmt_stop_server_listening
rpc_c_mgmt_stop_server_listen
Output
status Returns the status code from this routine. On
successful completion, the routine returns rpc_s_ok.
Otherwise, it returns an error.
Usage
The rpc_mgmt_set_authorization_fn routine sets up an authorization
routine to control remote access to the calling server's remote
management routines.
If a server does not provide an authorization routine, the RPC
runtime controls client application access to the server's remote
management routines as shown in the following table. In the table, an
enabled authorization allows all clients to run the remote routine
and a disabled authorization prevents all clients from running the
remote routine.
ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
Γöé Table 7. Default Controls for Remote Management Routines Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé REMOTE ROUTINE Γöé DEFAULT AUTHORIZATION Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé RPC_MGMT_INQ_IF_IDS Γöé enabled Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé RPC_MGMT_INQ_SERVER_PRINC_NAME Γöé enabled Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé RPC_MGMT_INQ_STATS Γöé enabled Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé RPC_MGMT_IS_SERVER_LISTENING Γöé enabled Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé RPC_MGMT_STOP_SERVER_LISTENING Γöé disabled Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
A server can modify the default authorizations by calling the
rpc_mgmt_set_authorization_fn routine to specify an authorization
routine. When an authorization routine is provided, the RPC runtime
automatically calls that routine to control the running of all remote
management routines called by clients.
The specified routine must provide access control for all of the
remote management routines.
If the authorization routine returns TRUE, the management routine is
allowed to run. If the authorization routine returns FALSE, the
management routine does not run and the called routine returns to the
client the status code returned from the rpc_mgmt_authorization_fn_t
routine. However, if the status code that the
rpc_mgmt_authorization_fn_t routine returns is 0 (zero) or rpc_s_ok,
then the status code rpc_s_mgmt_op_disallowed is returned to the
client.
The RPC runtime calls the server-provided authorization routine with
the following two input parameters:
o The binding handle of the calling client
o An integer value denoting which management routine the client
has called.
Using these parameters, the authorization routine determines whether
the calling client is allowed to run the requested management
routine. For example, the authorization routine can call
rpc_binding_inq_auth_client to obtain authentication and
authorization information about the calling client and determine if
that client is authorized to run the requested management routine.
Related Information
Routines:
rpc_mgmt_ep_unregister
rpc_mgmt_inq_if_ids
rpc_mgmt_inq_server_princ_name
rpc_mgmt_inq_stats
rpc_mgmt_is_server_listening
rpc_mgmt_stop_server_listening
ΓòÉΓòÉΓòÉ 5.8.52. rpc_mgmt_set_call_timeout ΓòÉΓòÉΓòÉ
Purpose
Sets the amount of time the RPC runtime is to wait for a server to
complete a call.
Note: This routine is not a documented API operation. Initially,
only the ncadg_xxx protocols support the use of this timeout.
It might not be supported by other DCE products due to
implementation changes.
Format
void rpc_mgmt_set_call_timeout(
rpc_binding_handle_t *binding,
unsigned32 seconds);
unsigned32 *status);
Parameters
Input
binding The binding handle to use.
seconds The number of seconds to wait for call completion.
Output
status Returns the status code from this routine. On
successful completion, the routine returns rpc_s_ok.
Otherwise, it returns one of the following errors:
rpc_s_no_memory
rpc_s_coding_error
rpc_s_invalid_binding
Usage
The rpc_mgmt_set_call_timeout routine is a local management routine
that sets the amount of time the RPC runtime is to wait for a server
to complete a call. A timeout of 0 (zero) means no maximum call
execution time is imposed (this is the default).
The value for the call timeout applies to all remote procedure calls
made using the specified binding handle.
Related Information
Routines:
rpc_mgmt_set_com_timeout
ΓòÉΓòÉΓòÉ 5.8.53. rpc_mgmt_set_cancel_timeout ΓòÉΓòÉΓòÉ
Purpose
Sets the lower bound on the time to wait before timing out after
forwarding a cancel. This routine is used by client applications.
Format
#include <dce/rpc.h>
void rpc_mgmt_set_cancel_timeout(
signed32 seconds,
unsigned32 *status);
Parameters
Input
seconds An integer specifying the number of seconds to wait for
a server to acknowledge a cancel. To specify that a
client waits an infinite amount of time, supply the
value rpc_c_cancel_infinite_timeout.
Output
status Returns the status code from this routine. On
successful completion, the routine returns rpc_s_ok.
Otherwise, it returns an error.
Usage
The rpc_mgmt_set_cancel_timeout routine resets the amount of time the
RPC runtime waits for a server to acknowledge a cancel before
orphaning the call.
The application specifies either to wait forever or to wait a length
of time specified in seconds. If the value of seconds is 0 (zero),
the remote procedure call is immediately orphaned when the RPC
runtime detects and forwards a pending cancel; control returns
immediately to the client application. The default value,
rpc_c_cancel_infinite_timeout, specifies waiting forever for the call
to complete.
The value for the cancel timeout applies to all remote procedure
calls made in the current thread. A multithreaded client that wishes
to change the timeout value must call this routine in each thread of
execution.
For more information about canceled threads and orphaned remote
procedure calls, see the DCE for OS/2 Warp: Application Development
Guide - Core Components.
Related Information
Routines:
pthread_cancel
pthread_setcancel
ΓòÉΓòÉΓòÉ 5.8.54. rpc_mgmt_set_com_timeout ΓòÉΓòÉΓòÉ
Purpose
Sets the communications timeout value in a binding handle. This
routine is used by client applications.
Format
#include <dce/rpc.h>
void rpc_mgmt_set_com_timeout(
rpc_binding_handle_t binding,
unsigned32 timeout,
unsigned32 *status);
Parameters
Input
binding Specifies the server binding handle whose timeout value
is set.
timeout Specifies a communications timeout value.
Output
status Returns the status code from this routine. On
successful completion, the routine returns rpc_s_ok.
Otherwise, it returns one of the following errors:
rpc_s_invalid_binding The binding handle is not
valid.
rpc_s_invalid_timeout The timeout value is not
valid.
rpc_s_wrong_kind_of_binding Wrong kind of binding
for the operation.
Usage
The rpc_mgmt_set_com_timeout routine resets the communication timeout
value in a server binding handle. The timeout value specifies the
relative amount of time to spend trying to communicate with the
server. Depending on the protocol sequence for the specified binding
handle, the timeout value acts only as advice to the RPC runtime.
After the initial relationship is established, subsequent
communications for the binding handle can revert to not less than the
default timeouts for the protocol service. This means that after
setting a short initial timeout establishing a connection, calls in
progress are not timed out any sooner than the default.
The timeout value can be any integer value from 0 (zero) to 10. Note
that these values do not represent seconds. They represent a relative
amount of time to spend to establish a client-server relationship (a
binding).
Constants are provided for certain values in the timeout range. The
following table of binding timeout values describes the DCE RPC
predefined values that an application can use for the timeout
parameter:
ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
Γöé Table 8. Predefined Timeout Values Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé NAME Γöé VALUEΓöé DESCRIPTION Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé RPC_C_BINDING_MIN_TIMEOUT Γöé 0 Γöé Attempts to communicate Γöé
Γöé Γöé Γöé for the minimum amount of Γöé
Γöé Γöé Γöé time for the network pro- Γöé
Γöé Γöé Γöé tocol being used. This Γöé
Γöé Γöé Γöé value favors response Γöé
Γöé Γöé Γöé time over correctness in Γöé
Γöé Γöé Γöé determining whether the Γöé
Γöé Γöé Γöé server is running. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé RPC_C_BINDING_DEFAULT_TIMEOUT Γöé 5 Γöé Attempts to communicate Γöé
Γöé Γöé Γöé for an average amount of Γöé
Γöé Γöé Γöé time for the network pro- Γöé
Γöé Γöé Γöé tocol being used. This Γöé
Γöé Γöé Γöé value gives equal consid- Γöé
Γöé Γöé Γöé eration to response time Γöé
Γöé Γöé Γöé and correctness in deter- Γöé
Γöé Γöé Γöé mining whether a server Γöé
Γöé Γöé Γöé is running. This is the Γöé
Γöé Γöé Γöé default value. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé RPC_C_BINDING_MAX_TIMEOUT Γöé 9 Γöé Attempts to communicate Γöé
Γöé Γöé Γöé for the longest finite Γöé
Γöé Γöé Γöé amount of time for the Γöé
Γöé Γöé Γöé network protocol being Γöé
Γöé Γöé Γöé used. This value favors Γöé
Γöé Γöé Γöé correctness in deter- Γöé
Γöé Γöé Γöé mining whether a server Γöé
Γöé Γöé Γöé is running over response Γöé
Γöé Γöé Γöé time. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé RPC_C_BINDING_INFINITE_TIMEOUT Γöé 10 Γöé Attempts to communicate Γöé
Γöé Γöé Γöé forever. Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
Note that connection-oriented RPC handles the time-out value
differently from Datagram RPC. Because connection-oriented RPC is
based on a reliable transport layer, communications time-outs are not
as significant as they are under datagram protocol. When
rpc_mgmt_set_com_timeout is called on a binding using
connection-oriented protocol, only the input parameter
rpc_c_binding_infinite_timeout changes binding behavior. All other
values are ignored.
Related Information
Routines:
rpc_mgmt_inq_com_timeout
ΓòÉΓòÉΓòÉ 5.8.55. rpc_mgmt_set_server_stack_size ΓòÉΓòÉΓòÉ
Purpose
Specifies the stack size for each server thread. This routine is used
by server applications.
Format
#include <dce/rpc.h>
void rpc_mgmt_set_server_stack_size(
unsigned32 thread_stack_size,
unsigned32 *status);
Parameters
Input
thread_stack_size Specifies, in bytes, the stack size allocated for
each thread created by rpc_server_listen. This value is
applied to all threads created for the server. Select
this value based on the stack requirements of the
remote procedures offered by the server.
Output
status Returns the status code from this routine. On
successful completion, the routine returns rpc_s_ok.
Otherwise, it returns one of the following errors:
rpc_s_invalid_arg The argument is not valid.
rpc_s_not_supported Not supported.
Usage
The rpc_mgmt_set_server_stack_size routine specifies the thread stack
size to use when the RPC runtime creates call threads for running
remote procedure calls. The max_calls_exec parameter in
rpc_server_listen specifies the number of call execution threads
created.
If a server knows the stack requirements of all the manager routines
in the interfaces it offers, it can call
rpc_mgmt_set_server_stack_size to ensure that each call thread has
the necessary stack size.
This routine is optional. When used, this routine must be called
before the server calls rpc_server_listen. If a server does not call
this routine, the default per thread stack size from the underlying
threads package is used.
Some thread packages do not support the specification or modification
of thread stack sizes. The packages cannot perform such operations or
the concept of a thread stack size is meaningless to them.
Related Information
Routines:
rpc_server_listen
ΓòÉΓòÉΓòÉ 5.8.56. rpc_mgmt_stats_vector_free ΓòÉΓòÉΓòÉ
Purpose
Frees a statistics vector. This routine is used by client, server, or
management applications.
Format
#include <dce/rpc.h>
void rpc_mgmt_stats_vector_free(
rpc_stats_vector_t **stats_vector,
unsigned32 *status);
Parameters
Input/Output
stats_vector Specifies the address of a pointer to a statistics
vector. On return, stats_vector contains the value
NULL.
Output
status Returns the status code from this routine. On
successful completion, the routine returns rpc_s_ok.
Otherwise, it returns an error.
Usage
An application calls rpc_mgmt_stats_vector_free to release the memory
used to store a vector of statistics.
An application calls rpc_mgmt_inq_stats to obtain a vector of
statistics. Follow a call to rpc_mgmt_inq_stats with a call to
rpc_mgmt_stats_vector_free.
Related Information
Routines:
rpc_mgmt_inq_stats
ΓòÉΓòÉΓòÉ 5.8.57. rpc_mgmt_stop_server_listening ΓòÉΓòÉΓòÉ
Purpose
Tells a server to stop listening for remote procedure calls. This
routine is used by client, server, or management applications.
Format
#include <dce/rpc.h>
void rpc_mgmt_stop_server_listening(
rpc_binding_handle_t binding,
unsigned32 *status);
Parameters
Input
binding Specifies a server binding handle. To direct a remote
server to stop listening for remote procedure calls,
specify a server binding handle to that server. To
direct your own (local) server to stop listening for
remote procedure calls, specify NULL.
If the binding handle you supply refers to partially
bound binding information and the binding information
contains a nil object UUID, this routine returns the
rpc_s_binding_incomplete status code. In this case, the
DCE Host daemon (dced) does not know which server
instance to select from the local endpoint map because
the RPC management interface is automatically
registered (by the RPC runtime) for all RPC servers.
To avoid this situation, you can obtain a fully bound
server binding handle by calling
rpc_ep_resolve_binding.
Output
status Returns the status code from this routine. On
successful completion, the routine returns rpc_s_ok.
Otherwise, it returns one of the following errors:
rpc_s_binding_incomplete Binding incomplete (no
object ID and no endpoint).
rpc_s_comm_failure Communications failure.
rpc_s_invalid_binding The binding handle is not
valid.
rpc_s_mgmt_op_disallowed The management operation
is disallowed.
rpc_s_unknown_if Unknown interface.
rpc_s_wrong_kind_of_binding Wrong kind of binding
for the operation.
In addition to the above values, status can return the
value of the status parameter from the
application-defined authorization routine
(rpc_mgmt_authorization_fn_t). The prototype for such a
routine is defined in the authorization_fn parameter in
rpc_mgmt_set_authorization_fn.
Usage
The rpc_mgmt_stop_server_listening routine directs a server to stop
listening for remote procedure calls.
On receiving such a request, the DCE RPC runtime stops accepting new
remote procedure calls. Running calls are allowed to complete.
After all calls complete, rpc_server_listen returns to the caller.
By default, the RPC runtime does not allow any client to remotely
call this routine. To allow clients to run this routine, a server
application supplies an authorization routine using
rpc_mgmt_set_authorization_fn.
Related Information
Routines:
rpc_ep_resolve_binding
rpc_mgmt_set_authorization_fn
rpc_server_listen
ΓòÉΓòÉΓòÉ 5.8.58. rpc_network_inq_protseqs ΓòÉΓòÉΓòÉ
Purpose
Returns all protocol sequences supported by both the RPC runtime and
the operating system. This routine is used by client and server
applications.
Format
#include <dce/rpc.h>
void rpc_network_inq_protseqs(
rpc_protseq_vector_t **protseq_vector,
unsigned32 *status);
Parameters
Output
protseq_vector Returns the address of a protocol sequence vector.
status Returns the status code from this routine. On
successful completion, the routine returns rpc_s_ok.
Otherwise, it returns one of the following errors:
rpc_s_no_protseqs No supported protocol sequences.
rpc_s_no_memory No memory.
Usage
The rpc_network_inq_protseqs routine obtains a vector containing the
protocol sequences supported by the RPC runtime and the operating
system. A server chooses to accept remote procedure calls over some
or all of the supported protocol sequences. If there are no supported
protocol sequences, this routine returns the rpc_s_no_protseqs status
code and the value NULL in its protseq_vector parameter.
The application calls rpc_protseq_vector_free to release the memory
used by the vector.
Related Information
Routines:
rpc_network_is_protseq_valid
rpc_protseq_vector_free
ΓòÉΓòÉΓòÉ 5.8.59. rpc_network_is_protseq_valid ΓòÉΓòÉΓòÉ
Purpose
Tells whether the specified protocol sequence is supported by both
the RPC runtime and the operating system. This routine is used by
client and server applications.
Format
#include <dce/rpc.h>
boolean32 rpc_network_is_protseq_valid(
unsigned_char_t *protseq,
unsigned32 *status);
Parameters
Input
protseq Specifies a string identifier for a protocol sequence.
See Protocol Sequence for a list of acceptable values.
The rpc_network_is_protseq_valid routine determines
whether this parameter contains a valid protocol
sequence. If not, the routine returns FALSE and the
status parameter contains the rpc_s_invalid_rpc_protseq
status code.
Output
status Returns the status code from this routine. On
successful completion, the routine returns rpc_s_ok.
Otherwise, it returns one of the following errors:
rpc_s_invalid_rpc_protseq The protocol sequence is
not valid.
rpc_s_protseq_not_supported Protocol sequence not
supported on this host.
Usage
The rpc_network_is_protseq_valid routine determines whether a
specified protocol sequence is available for making remote procedure
calls. A server chooses to accept remote procedure calls over some or
all of the supported protocol sequences.
A protocol sequence is valid if the RPC runtime and the operating
system support the protocol sequence. DCE RPC supports the protocol
sequences pointed to by the explanation of the protseq parameter.
An application calls rpc_network_inq_protseqs to obtain all the
supported protocol sequences.
Return Codes
This routine can return the following values:
TRUE The RPC runtime supports the protocol sequence specified in
the protseq parameter. The routine returns the status code
rpc_s_ok in the status parameter.
FALSE The RPC runtime does not support the protocol sequence
specified in the protseq parameter.
Related Information
Routines:
rpc_network_inq_protseqs
rpc_string_binding_parse
ΓòÉΓòÉΓòÉ 5.8.60. rpc_ns_binding_export ΓòÉΓòÉΓòÉ
Purpose
Establishes a name service database entry with binding handles or
object UUIDs for a server. This routine is used by server
applications.
Format
#include <dce/rpc.h>
void rpc_ns_binding_export(
unsigned32 entry_name_syntax,
unsigned_char_t *entry_name,
rpc_if_handle_t if_handle,
rpc_binding_vector_t *binding_vec,
uuid_vector_t *object_uuid_vec,
unsigned32 *status);
Parameters
Input
entry_name_syntax An integer value that specifies the syntax of the
entry_name parameter.
To use the syntax specified in the
RPC_DEFAULT_ENTRY_SYNTAX environment variable, provide
the value rpc_c_ns_syntax_default.
For more information, see the name_syntax section in
Frequently Used RPC Routine Parameters.
entry_name Specifies the entry name to which binding handles and
object UUIDs are exported. This can be either the
global or cell-relative name.
if_handle Specifies a stub-generated data structure that
identifies the interface to export. Specifying the
value NULL indicates there are no binding handles to
export (only object UUIDs are exported) and the
binding_vec parameter is ignored.
binding_vec Specifies a vector of server bindings to export.
Specify the value NULL for this parameter in cases
where there are no binding handles to export (only
object UUIDs are exported).
object_uuid_vec Identifies a vector of object UUIDs offered by the
server. The server application constructs this vector.
NULL indicates there are no object UUIDs to export
(only binding handles are exported).
Output
status Returns the status code from this routine. On
successful completion, the routine returns rpc_s_ok.
Otherwise, it returns one of the following errors:
rpc_s_incomplete_name Incomplete name.
rpc_s_invalid_binding The binding handle is not
valid.
rpc_s_invalid_name_syntax The name syntax is not
valid.
rpc_s_name_service_unavailable The name service is
unavailable.
rpc_s_no_ns_permission No permission for the name
service operation.
rpc_s_nothing_to_export Nothing to export.
rpc_s_unsupported_name_syntax Unsupported name
syntax.
rpc_s_wrong_kind_of_binding Wrong kind of binding
for the operation.
Usage
The rpc_ns_binding_export routine allows a server application to
publicly offer, in the name service database, an interface that any
client application can use. A server application can also use this
routine to publicly offer the object UUIDs of the application's
resources.
To export an interface, the server application calls the routine with
an interface and the server binding handles a client can use to
access the server.
A server can export interfaces and objects in a single call to this
routine, or it can export them separately.
If the entry in the name service database specified by the entry_name
parameter does not exist, rpc_ns_binding_export tries to create it.
In this case a server must have the correct permissions to create the
entry. Otherwise, a management application with the necessary
permissions creates the entry by calling rpc_ns_mgmt_entry_create
before the server runs.
A server is not required to export its interfaces to the name service
database. When a server does not export any interfaces, only clients
that privately know of that server's binding information can access
its interfaces. For example, a client that has the information needed
to construct a string binding can call
rpc_binding_from_string_binding to create a binding handle for making
remote procedure calls to a server.
Before calling rpc_ns_binding_export to export interfaces (but not to
export object UUIDs), a server must do the following:
o Register one or more protocol sequences with the local RPC
runtime by calling one of the following routines:
rpc_server_use_protseq
rpc_server_use_protseq_if
rpc_server_use_protseq_ep
rpc_server_use_all_protseq
rpc_server_use_all_protseqs_if
o Obtain a list of server bindings by calling
rpc_server_inq_bindings.
The vector returned from rpc_server_inq_bindings becomes the
binding_vec parameter for this routine. To prevent a binding
from being exported, set the selected vector element to the
value NULL. See RPC Data Types and Structures.
A server that uses the rpc_server_use_protseq or
rpc_server_use_all_protseq has dynamic endpoints. The bindings
exported to the name service database will automatically contain a
NULL endpoint. The servers must also register with the local endpoint
map by calling rpc_ep_register or rpc_ep_register_no_replace.
If a server exports an interface to the same entry in the name
service database more than once, the second and subsequent calls to
this routine add the binding information and object UUIDs only if
they differ from the ones in the server entry. Existing data is not
removed from the entry.
To remove binding handles and object UUIDs from the name service
database, a server application calls rpc_ns_binding_unexport and a
management application calls rpc_ns_mgmt_binding_unexport.
For an explanation of how a server can establish a client-server
relationship without using the name service database, see the
explanation of a String Binding.
In addition to calling this routine, a server that called either
rpc_server_use_all_protseq or rpc_server_use_protseq must also
register with the local endpoint map by calling rpc_ep_register or
rpc_ep_register_no_replace.
Permissions Required
You need both read permission and write permission to the CDS object
entry (the target name service entry). If the entry does not exist,
you also need insert permission to the parent directory.
Related Information
Routines:
rpc_ep_register
rpc_ep_register_no_replace
rpc_ns_binding_unexport
rpc_ns_mgmt_binding_unexport
rpc_ns_mgmt_entry_create
rpc_server_inq_bindings
rpc_server_use_all_protseqs
rpc_server_use_all_protseqs_if
rpc_server_use_protseq
rpc_server_use_protseq_ep
rpc_server_use_protseq_if
ΓòÉΓòÉΓòÉ 5.8.61. rpc_ns_binding_import_begin ΓòÉΓòÉΓòÉ
Purpose
Creates an import context for an interface and an object in the name
service database. This routine is used by client applications.
Format
#include <dce/rpc.h>
void rpc_ns_binding_import_begin(
unsigned32 entry_name_syntax,
unsigned_char_t *entry_name,
rpc_if_handle_t if_handle,
uuid_t *obj_uuid,
rpc_ns_handle_t *import_context,
unsigned32 *status);
Parameters
Input
entry_name_syntax An integer value that specifies the syntax of the
entry_name parameter.
To use the syntax specified in the
RPC_DEFAULT_ENTRY_SYNTAX environment variable, provide
the value rpc_c_ns_syntax_default.
For more information, see the name_syntax section in
Frequently Used RPC Routine Parameters.
entry_name Specifies the entry name where the search for
compatible binding handles begins. This can be either
the global or cell-relative name.
To use the entry name found in the RPC_DEFAULT_ENTRY
environment variable, supply NULL or a null string (\0)
for this parameter. When this entry name is used, the
RPC runtime automatically uses the default name syntax
specified in the RPC_DEFAULT_ENTRY_SYNTAX environment
variable.
if_handle A stub-generated data structure specifying the
interface to import. If the interface specification has
not been exported or is of no concern to the caller,
specify NULL for this parameter. In this case the
bindings returned are only guaranteed to be of a
compatible and supported protocol sequence and,
depending on the value of the obj_uuid parameter,
contain the specified object UUID. The desired
interface may not be supported by the contacted server.
obj_uuid Specifies an optional object UUID.
If you specify NULL or a nil UUID for this parameter,
the returned binding handles contain one of the object
UUIDs that the compatible server exported. If the
server did not export any object UUIDs, the returned
compatible binding handles contain a nil object UUID.
If you specify a non-nil UUID, compatible binding
handles are returned from an entry only if the server
has exported the specified object UUID. Each returned
binding handle contains the specified non-nil object
UUID.
Output
import_context Returns the name service handle for use with
rpc_ns_binding_import_next and
rpc_ns_binding_import_done.
status Returns the status code from this routine. On
successful completion, the routine returns rpc_s_ok.
Otherwise, it returns one of the following errors:
rpc_s_incomplete_name Incomplete name.
rpc_s_invalid_name_syntax The name syntax is not
valid.
rpc_s_invalid_object The object is not valid.
rpc_s_no_env_setup The environment variable was
not set up.
rpc_s_unsupported_name_syntax Unsupported name
syntax.
Usage
The rpc_ns_binding_import_begin routine creates an import context for
importing compatible server binding handles for servers. These
servers offer the specified interface and object UUID in the
respective if_handle and obj_uuid parameters.
Before calling rpc_ns_binding_import_next, the client must first call
this routine to create an import context. The parameters to this
routine control the operation of the rpc_ns_binding_import_next
routine.
After importing binding handles, the client calls the
rpc_ns_binding_import_done routine to delete the import context.
Related Information
Routines:
rpc_ns_binding_import_done
rpc_ns_binding_import_next
rpc_ns_mgmt_handle_set_exp_age
ΓòÉΓòÉΓòÉ 5.8.62. rpc_ns_binding_import_done ΓòÉΓòÉΓòÉ
Purpose
Deletes the import context for searching the name service database.
This routine is used by client applications.
Format
#include <dce/rpc.h>
void rpc_ns_binding_import_done(
rpc_ns_handle_t *import_context,
unsigned32 *status);
Parameters
Input/Output
import_context Specifies the name service handle to delete. (A name
service handle is created by calling
rpc_ns_binding_import_begin.) Returns the value NULL.
Output
status Returns the status code from this routine. On
successful completion, the routine returns rpc_s_ok.
Otherwise, it returns rpc_s_invalid_ns_handle, which
indicates that the name service handle is not valid.
Usage
The rpc_ns_binding_import_done routine deletes an import context
created by calling rpc_ns_binding_import_begin. This deletion does
not affect any previously imported bindings.
Typically, a client calls this routine after completing remote
procedure calls to a server using a binding handle returned from
rpc_ns_binding_import_next. A client program calls this routine for
each created import context, regardless of the status returned from
rpc_ns_binding_import_next, or the success in making remote procedure
calls.
Related Information
Routines:
rpc_ns_binding_import_begin
rpc_ns_binding_import_next
ΓòÉΓòÉΓòÉ 5.8.63. rpc_ns_binding_import_next ΓòÉΓòÉΓòÉ
Purpose
Returns a binding handle of a compatible server (if found) from the
name service database. This routine is used by client applications.
Format
#include <dce/rpc.h>
void rpc_ns_binding_import_next(
rpc_ns_handle_t import_context,
rpc_binding_handle_t *binding,
unsigned32 *status);
Parameters
Input
import_context Specifies a name service handle. This handle is
returned from the rpc_ns_binding_import_begin routine.
Output
binding Returns a compatible server binding handle.
status Returns the status code from this routine. On
successful completion, the routine returns rpc_s_ok.
Otherwise, it returns one of the following errors:
rpc_s_class_version_mismatch RPC class version
mismatch.
rpc_s_entry_not_found Name service entry not
found.
rpc_s_invalid_ns_handle The name service handle is
not valid.
rpc_s_name_service_unavailable The name service is
unavailable.
rpc_s_no_more_bindings No more bindings.
rpc_s_no_ns_permission No permission for the name
service operation.
rpc_s_not_rpc_entry Not an RPC entry.
Usage
The rpc_ns_binding_import_next routine returns one compatible (to the
client) server binding handle selected at random from the name
service database. The server offers the interface and object UUID
specified by the respective if_handle and obj_uuid parameters in
rpc_ns_binding_import_begin.
A similar routine is rpc_ns_binding_lookup_next, which returns a
vector of compatible server binding handles for one or more servers.
Note: rpc_ns_binding_import_next calls rpc_ns_binding_lookup_next,
which in turn obtains a vector of server binding handles from
the name service database. Next, rpc_binding_import_next
randomly selects one of the elements from the vector.
The rpc_ns_binding_import_next routine communicates only with the
name service database, not directly with servers.
This routine traverses entries in the name service database,
returning compatible server binding handles from each entry. The
routine can return multiple binding handles from each entry. Search
operations obey the following rules for traversing the entries:
o At each entry visited, the search operations randomly process
binding information, then group members, then profile members.
Profile members (but not group members) with different
priorities are returned according to their priorities, highest
priority first.
o The search operation returns members of a group in a random
order.
o The search operation returns members of a profile with the same
priority in a random order.
The returned compatible binding handle always contains an object
UUID. Its value depends on the value specified in the obj_uuid of
parameter rpc_ns_binding_import_begin as follows:
o If obj_uuid contains a non-nil object UUID, the returned binding
handle contains that object UUID.
o If obj_uuid contains a nil object UUID or NULL, the object UUID
returned in the binding handle depends on how the server
exported object UUIDs:
- If the server did not export any object UUIDs, the returned
binding handle contains a nil object UUID.
- If the server exported one object UUID, the returned
binding handle contains that object UUID.
- If the server exported multiple object UUIDs, the returned
binding handle contains one of the object UUIDs, selected
in an unspecified way.
Applications should not count on multiple calls to
rpc_ns_binding_import_next returning different object
UUIDs. In particular, note that each name service entry
stores server address information separately from exported
object UUIDs. Successive calls to
rpc_ns_binding_import_next using the same import context
will return exactly one binding for each compatible server
address, not the cross product of all compatible server
addresses with all exported UUIDs. Each returned binding
will contain one of the exported object UUIDs, but
applications should not count on any specific selection
mechanism for these object UUIDs.
The client application can use the returned binding handle to make a
remote procedure call to the server. If the client fails to
communicate with the server, it can call rpc_ns_binding_import_next
again.
Each time the client calls rpc_ns_binding_import_next, the routine
returns another server binding handle. The returned binding handles
are unordered. Multiple binding handles can refer to different
protocol sequences from the same server.
When the search finishes, the routine returns a status code of
rpc_s_no_more_bindings and returns the value NULL in the binding
parameter.
A client application calls rpc_ns_binding_inq_entry_name to obtain
the name of the entry in the name service database where the binding
handle came from.
The rpc_ns_binding_import_next routine allocates memory for the
returned binding parameter. When a client application finishes with
the binding handle, it must call rpc_binding_free to deallocate the
memory. Each call to rpc_ns_binding_import_next requires a
corresponding call to rpc_binding_free.
The client calls rpc_ns_binding_import_done after it has
satisfactorily used one or more returned server binding handles. The
rpc_ns_binding_import_done routine deletes the import context. The
client also calls rpc_ns_binding_import_done if the application wants
to start a new search for compatible servers (by calling
rpc_ns_binding_import_begin). The order of binding handles returned
can be different for each new search. This means that the order in
which binding handles are returned to an application can be different
each time the application is run.
Permissions Required
You need read permission to the specified CDS object entry (the
starting name service entry) and to any CDS object entry in the
resulting search path.
Related Information
Routines:
rpc_ns_binding_import_begin
rpc_ns_binding_import_done
rpc_ns_binding_inq_entry_name
rpc_ns_binding_lookup_begin
rpc_ns_binding_lookup_done
rpc_ns_binding_lookup_next
rpc_ns_binding_select
ΓòÉΓòÉΓòÉ 5.8.64. rpc_ns_binding_inq_entry_name ΓòÉΓòÉΓòÉ
Purpose
Returns the name of an entry in the name service database that the
server binding handle came from. This routine is used by client
applications.
Format
#include <dce/rpc.h>
void rpc_ns_binding_inq_entry_name(
rpc_binding_handle_t binding,
unsigned32 entry_name_syntax,
unsigned_char_t **entry_name,
unsigned32 *status);
Parameters
Input
binding Specifies a server binding handle whose entry name in
the name service database is returned.
entry_name_syntax An integer value that specifies the syntax of the
returned entry_name parameter.
To use the syntax specified in the
RPC_DEFAULT_ENTRY_SYNTAX environment variable, provide
the value rpc_c_ns_syntax_default.
Output
entry_name Returns the name of the entry in the name service
database in which binding was found. The returned name
is a global name.
Specify NULL to prevent the routine from returning this
parameter. When you specify this value, the client does
not need to call rpc_string_free.
status Returns the status code from this routine. On
successful completion, the routine returns rpc_s_ok.
Otherwise, it returns one of the following errors:
rpc_s_incomplete_name Incomplete name.
rpc_s_invalid_binding The binding handle is not
valid.
rpc_s_invalid_name_syntax The name syntax is not
valid.
rpc_s_no_entry_name No entry name for the
binding.
rpc_s_unsupported_name_syntax Unsupported name
syntax.
rpc_s_wrong_kind_of_binding Wrong kind of binding
for the operation.
rpc_s_no_env_setup RPC_DEFAULT_ENTRY not set
up.
Usage
The rpc_ns_binding_inq_entry_name routine returns the global name of
the entry in the name service database from which a binding handle
for a compatible server came.
The RPC runtime allocates memory for the string returned in the
entry_name parameter. Your application calls rpc_string_free to
deallocate that memory.
An entry name is associated only with binding handles returned from
the rpc_ns_binding_import_next, rpc_ns_binding_lookup_next, and
rpc_ns_binding_select routines.
If the binding handle specified in the binding parameter is not
returned from an entry in the name service database (for example, the
binding handle is created by calling
rpc_binding_from_string_binding), this routine returns the
rpc_s_no_entry_name status code.
Related Information
Routines:
rpc_binding_from_string_binding
rpc_ns_binding_import_next
rpc_ns_binding_lookup_next
rpc_ns_binding_select
rpc_string_free
ΓòÉΓòÉΓòÉ 5.8.65. rpc_ns_binding_lookup_begin ΓòÉΓòÉΓòÉ
Purpose
Creates a lookup context for an interface and an object in the name
service database. This routine is used by client applications.
Format
#include <dce/rpc.h>
void rpc_ns_binding_lookup_begin(
unsigned32 entry_name_syntax,
unsigned_char_t *entry_name,
rpc_if_handle_t if_handle,
uuid_t *object_uuid,
unsigned32 binding_max_count,
rpc_ns_handle_t *lookup_context,
unsigned32 *status);
Parameters
Input
entry_name_syntax An integer value that specifies the syntax of the
entry_name parameter.
To use the syntax specified in the
RPC_DEFAULT_ENTRY_SYNTAX environment variable, provide
the value rpc_c_ns_syntax_default.
entry_name Specifies the entry name at which the search for
compatible binding handles begins. This can be either
the global or cell-relative name.
To use the entry name found in the RPC_DEFAULT_ENTRY
environment variable, supply NULL or a null string (\0)
for this parameter. When this entry name is used, the
RPC runtime automatically uses the default name syntax
specified in the RPC_DEFAULT_ENTRY_SYNTAX environment
variable.
if_handle A stub-generated data structure specifying the
interface to look up. If the interface specification
has not been exported or is of no concern to the
caller, specify NULL for this parameter. In this case
the bindings returned are only guaranteed to be of a
compatible and supported protocol sequence and contain
the specified object UUID. The desired interface might
not be supported by the contacted server.
object_uuid Specifies an optional object UUID.
If you specify NULL or a nil UUID for this parameter,
the returned binding handles contain one of the object
UUIDs exported by the compatible server. If the server
did not export any object UUIDs, the returned
compatible binding handles contain a nil object UUID.
For a non-nil UUID, compatible binding handles are
returned from an entry only if the server has exported
the specified object UUID. Each returned binding handle
contains the specified non-nil object UUID.
binding_max_count Sets the maximum number of bindings to return in
the binding_vector parameter of
rpc_ns_binding_lookup_next. Specify
rpc_c_binding_max_count_default to use the default
count.
Output
lookup_context Returns the name service handle for use with the
rpc_ns_binding_lookup_next and
rpc_ns_binding_lookup_done routines.
status Returns the status code from this routine. On
successful completion, the routine returns rpc_s_ok.
Otherwise, it returns one of the following errors:
rpc_s_incomplete_name Incomplete name.
rpc_s_invalid_name_syntax The name syntax is not
valid.
rpc_s_invalid_object The object is not valid.
rpc_s_no_env_setup The environment variable is
not set up.
rpc_s_not_rpc_entry Not an RPC entry.
rpc_s_unsupported_name_syntax Unsupported name
syntax.
Usage
The rpc_ns_binding_lookup_begin routine creates a lookup context for
locating compatible server binding handles for servers. These servers
offer the specified interface and object UUID in the respective
if_handle and object_uuid parameters.
Before calling the rpc_ns_binding_lookup_next routine, the client
application must first create a lookup context by calling the
rpc_ns_binding_lookup_begin routine. The parameters to this routine
control the operation of the rpc_ns_binding_lookup_next routine.
When finished locating binding handles, the client application calls
the rpc_ns_binding_lookup_done routine to delete the lookup context.
Related Information
Routines:
rpc_ns_binding_lookup_done
rpc_ns_binding_lookup_next
rpc_ns_mgmt_handle_set_exp_age
ΓòÉΓòÉΓòÉ 5.8.66. rpc_ns_binding_lookup_done ΓòÉΓòÉΓòÉ
Purpose
Deletes the lookup context for searching the name service database.
This routine is used by client applications.
Format
#include <dce/rpc.h>
void rpc_ns_binding_lookup_done(
rpc_ns_handle_t *lookup_context,
unsigned32 *status);
Parameters
Input/Output
lookup_context Specifies the name service handle to delete. (A name
service handle is created by calling
rpc_ns_binding_lookup_begin.) Returns the value NULL.
Output
status Returns the status code from this routine. On
successful completion, the routine returns rpc_s_ok.
Otherwise, it returns the following error:
rpc_s_invalid_ns_handle The name service handle is
not valid.
Usage
The rpc_ns_binding_lookup_done routine deletes a lookup context
created by calling rpc_ns_binding_lookup_begin.
Typically, a client calls this routine after completing remote
procedure calls to a server using a binding handle returned from
rpc_ns_binding_lookup_next. A client program calls this routine for
each created lookup context, regardless of the status returned from
rpc_ns_binding_lookup_next, or success in making remote procedure
calls.
Related Information
Routines:
rpc_ns_binding_lookup_begin
rpc_ns_binding_lookup_next
ΓòÉΓòÉΓòÉ 5.8.67. rpc_ns_binding_lookup_next ΓòÉΓòÉΓòÉ
Purpose
Returns a list of binding handles of one or more compatible servers
(if found) from the name service database. This routine is used by
client applications.
Format
#include <dce/rpc.h>
void rpc_ns_binding_lookup_next(
rpc_ns_handle_t lookup_context,
rpc_binding_vector_t **binding_vec,
unsigned32 *status);
Parameters
Input
lookup_context Specifies a name service handle. This handle is
returned from rpc_ns_binding_lookup_begin.
Output
binding_vec Returns a vector of compatible server binding handles.
status Returns the status code from this routine. On
successful completion, the routine returns rpc_s_ok.
Otherwise, it returns one of the following errors:
rpc_s_class_version_mismatch RPC class version
mismatch.
rpc_s_entry_not_found The name service entry was
not found.
rpc_s_invalid_ns_handle The name service handle is
not valid.
rpc_s_name_service_unavailable The name service is
unavailable.
rpc_s_no_more_bindings No more bindings.
rpc_s_no_ns_permission No permission for name
service operation.
rpc_s_not_rpc_entry Not an RPC entry.
Usage
The rpc_ns_binding_lookup_next routine returns a vector of compatible
(to the client) server binding handles. The servers offer the
interface and object UUID specified by the respective if_handle and
object_uuid parameters in rpc_ns_binding_lookup_begin. The number of
binding handles that rpc_ns_binding_lookup_next attempts to return is
the value of the binding_max_count parameter in
rpc_ns_binding_lookup_begin.
A similar routine is rpc_ns_binding_import_next, which returns one
compatible server binding handle.
The rpc_ns_binding_lookup_next routine communicates only with the
name service database, not directly with servers.
This routine traverses entries in the name service database,
returning compatible server binding handles from each entry. Search
operations obey the following rules for traversing the entries:
o At each entry visited, the search operations randomly process
binding information, then group members, then profile members.
Profile members with different priorities are returned according
to their priorities, highest priority first.
o The search operation returns members of a group in random order.
o The search operation returns members of a profile with the same
priority in random order.
If the entry where the search begins (see entry_name in
rpc_ns_binding_lookup_begin) contains binding handles as well as an
RPC group and a profile, rpc_ns_binding_lookup_next returns the
binding handles from entry_name before searching the group or
profile. This means that rpc_ns_binding_lookup_next can return a
partially full vector before processing the members of the group or
profile.
Each binding handle in the returned vector always contains an object
UUID. Its value depends on the value specified in the object_uuid
parameter of rpc_ns_binding_lookup_begin as follows:
o If object_uuid contains a non-nil object UUID, each returned
binding handle contains that object UUID.
o If object_uuid contains a nil object UUID or NULL, the object
UUID returned in each binding handle depends on how the server
exported object UUIDs:
- If the server did not export any object UUIDs, each
returned binding handle contains a nil object UUID.
- If the server exported one object UUID, each returned
binding handle contains that object UUID.
- Applications should not count on the binding handles
returned from a given entry to contain different object
UUIDs. In particular, not that each name service entry
stores server address information separately from exported
object UUIDs. One or more calls to
rpc_ns_binding_lookup_next returns exactly one binding for
each compatible server address, not the cross product of
all compatible server addresses with all exported UUIDs.
Each returned binding contains one of the exported object
UUIDs, but applications should not count on any specific
selection mechanism for these object UUIDs.
From the returned vector of server binding handles, the client
application can employ its own criteria for selecting individual
binding handles, or the application can call rpc_ns_binding_select to
select a binding handle. The rpc_binding_to_string_binding and
rpc_string_binding_parse routines are useful for a client creating
its own selection criteria.
The client application can use the selected binding handle to attempt
a remote procedure call to the server. If the client fails to
communicate with the server, it can select another binding handle
from the vector. When all of the binding handles in the vector are
used, the client application calls rpc_ns_binding_lookup_next again.
Each time the client calls rpc_ns_binding_lookup_next, the routine
returns another vector of binding handles. The binding handles
returned in each vector are unordered, as is the order in which the
vectors are returned from multiple calls to this routine.
When looking up compatible binding handles from a profile, the
binding handles from entries of equal profile priority are unordered
in the returned vector. In addition, the vector returned from a call
to rpc_ns_binding_lookup_next contains only compatible binding
handles from entries of equal profile priority. This means the
returned vector may be partially full.
For example, if the binding_max_count parameter value in
rpc_ns_binding_lookup_begin was 5 and rpc_ns_binding_lookup_begin
finds only three compatible binding handles from profile entries of
priority 0 (zero), rpc_ns_binding_lookup_next returns a partially
full binding vector (with three binding handles). The next call to
rpc_ns_binding_lookup_next creates a new binding vector and begins
looking for compatible binding handles from profile entries of
priority 1.
When the search finishes, the routine returns a status code of
rpc_s_no_more_bindings and returns the value NULL in the binding_vec
parameter.
A client application calls rpc_ns_binding_inq_entry_name to obtain
the name of the entry in the name service database where the binding
handle came from.
The rpc_ns_binding_lookup_next routine allocates memory for the
returned binding_vec parameter. When a client application finishes
with the vector, it must call rpc_binding_vector_free to deallocate
the memory. Each call to rpc_ns_binding_lookup_next requires a
corresponding call to rpc_binding_vector_free.
The client calls rpc_ns_binding_lookup_done, which deletes the lookup
context. The client also calls rpc_ns_binding_lookup_done if the
application wants to start a new search for compatible servers (by
calling rpc_ns_binding_lookup_begin). The order of binding handles
returned can be different for each new search. This means that the
order in which binding handles are returned to an application can be
different each time the application is run.
Permissions Required
You need read permission to the specified CDS object entry (the
starting name service entry) and to any CDS object entry in the
resulting search path.
Related Information
Routines:
rpc_binding_to_string_binding
rpc_binding_vector_free
rpc_ns_binding_import_next
rpc_ns_binding_inq_entry_name
rpc_ns_binding_lookup_begin
rpc_ns_binding_lookup_done
rpc_ns_binding_select
rpc_string_binding_parse
ΓòÉΓòÉΓòÉ 5.8.68. rpc_ns_binding_select ΓòÉΓòÉΓòÉ
Purpose
Returns a binding handle from a list of compatible server binding
handles. This routine is used by client applications.
Format
#include <dce/rpc.h>
void rpc_ns_binding_select(
rpc_binding_vector_t *binding_vec,
rpc_binding_handle_t *binding,
unsigned32 *status);
Parameters
Input/Output
binding_vec Specifies the vector of compatible server binding
handles from which a binding handle is selected. The
returned binding vector no longer references the
selected binding handle (returned separately in the
binding parameter).
Output
binding Returns a selected server binding handle.
status Returns the status code from this routine. On
successful completion, the routine returns rpc_s_ok.
Otherwise, it returns rpc_s_no_more_bindings, which
indicates that there are no more bindings.
Usage
The rpc_ns_binding_select routine randomly chooses and returns a
server binding handle from a vector of server binding handles.
Each time the client calls rpc_ns_binding_select, the routine returns
another binding handle from the vector.
When all of the binding handles are returned from the vector, the
routine returns a status code of rpc_s_no_more_bindings and returns
the value NULL in the binding parameter.
The select operation allocates storage for the data referenced by the
returned binding parameter. When a client finishes with the binding
handle, it calls rpc_binding_free to deallocate the storage. Each
call to rpc_ns_binding_select requires a corresponding call to the
rpc_binding_free routine.
Instead of using this routine, client applications can select a
binding handle according to their specific needs. In this case
rpc_binding_to_string_binding and rpc_string_binding_parse are useful
to the applications since the routines work together to extract the
individual fields of a binding handle for examination.
Related Information
Routines:
rpc_binding_free
rpc_binding_to_string_binding
rpc_ns_binding_lookup_next
rpc_string_binding_parse
ΓòÉΓòÉΓòÉ 5.8.69. rpc_ns_binding_unexport ΓòÉΓòÉΓòÉ
Purpose
Removes the binding handles for an interface or object UUIDs from an
entry in the name service database. This routine is used by server
applications.
Format
#include <dce/rpc.h>
void rpc_ns_binding_unexport(
unsigned32 entry_name_syntax,
unsigned_char_t *entry_name,
rpc_if_handle_t if_handle,
uuid_vector_t *object_uuid_vec,
unsigned32 *status);
Parameters
Input
entry_name_syntax An integer value that specifies the syntax of the
entry_name parameter.
To use the syntax specified in the
RPC_DEFAULT_ENTRY_SYNTAX environment variable, provide
the value rpc_c_ns_syntax_default.
entry_name Specifies an entry name whose binding handles or object
UUIDs are removed. This can be either the global or
cell-relative name.
if_handle Specifies an interface specification for the binding
handles to be removed from the name service database.
The value NULL indicates that no binding handles are
removed (only object UUIDs are removed).
object_uuid_vec Specifies a vector of object UUIDs to be removed from
the name service database. The application constructs
this vector. The value NULL indicates that no object
UUIDs are removed (only binding handles are removed).
Output
status Returns the status code from this routine. On successful
completion, the routine returns rpc_s_ok. Otherwise, it
returns one of the following errors:
rpc_s_class_version_mismatch RPC class version
mismatch.
rpc_s_entry_not_found The name service entry was
not found.
rpc_s_incomplete_name Incomplete name.
rpc_s_interface_not_found The interface was not
found.
rpc_s_invalid_name_syntax The name syntax is not
valid.
rpc_s_invalid_vers_option The version option is not
valid.
rpc_s_name_service_unavailable The name service is
unavailable.
rpc_s_no_ns_permission No permission for the name
service operation.
rpc_s_not_all_objs_unexported Not all objects were
unexported.
rpc_s_nothing_to_unexport Nothing to unexport.
rpc_s_not_rpc_entry Not an RPC entry.
rpc_s_unsupported_name_syntax Unsupported name
syntax.
Usage
The rpc_ns_binding_unexport routine allows a server application to
unexport (that is, remove) one of the following from an entry in the
name service database:
o All the binding handles for an interface
o One or more object UUIDs for a resource or resources
o Both binding handles and object UUIDs
The rpc_ns_binding_unexport routine removes only those binding
handles that match the interface UUID and the major and minor
interface version numbers found in the if_handle parameter. To remove
multiple versions of an interface, use rpc_ns_mgmt_binding_unexport.
A server application can remove an interface and objects in a single
call to this routine, or it can remove them separately.
If rpc_ns_binding_unexport does not find any binding handles for the
specified interface, the routine returns an rpc_s_interface_not_found
status code and does not remove the object UUIDs, if any are
specified.
If one or more binding handles for the specified interface are found
and removed without error, rpc_ns_binding_unexport removes the
specified object UUIDs, if any.
If any of the specified object UUIDs are not found,
rpc_ns_binding_unexport returns the status code
rpc_s_not_all_objs_unexported.
A server application, in addition to calling this routine, also calls
rpc_ep_unregister to unregister any endpoints that the server
previously registered with the local endpoint map.
Use this routine with caution, only when you expect a server to be
unavailable for an extended time, for example, when it is permanently
removed from service.
Additionally, keep in mind that name service databases are designed
to be relatively stable. In replicated name service databases,
frequent use of rpc_ns_binding_export and rpc_ns_binding_unexport
causes the name service to repeatedly remove and replace the same
entry and can cause performance problems.
Permissions Required
You need both read permission and write permission to the CDS object
entry (the target name service entry).
Related Information
Routines:
rpc_ep_unregister
rpc_ns_binding_export
rpc_ns_mgmt_binding_unexport
ΓòÉΓòÉΓòÉ 5.8.70. rpc_ns_entry_expand_name ΓòÉΓòÉΓòÉ
Purpose
Expands the name of a name service entry. This routine is used by
client, server, or management applications.
Format
#include <dce/rpc.h>
void rpc_ns_entry_expand_name(
unsigned32 entry_name_syntax,
unsigned_char_t *entry_name,
unsigned_char_t **expanded_name,
unsigned32 *status);
Parameters
Input
entry_name_syntax An integer value that specifies the syntax of the
entry_name parameter.
To use the syntax specified in the
RPC_DEFAULT_ENTRY_SYNTAX environment variable, provide
a value of rpc_c_ns_syntax_default.
entry_name Specifies the entry name to expand. This can be either
the global or the cell-relative name.
Output
expanded_name Returns a pointer to the expanded version of
entry_name. Do not specify NULL since the routine
always returns a name string.
status Returns the status code from this routine. On
successful completion, the routine returns rpc_s_ok.
Otherwise, it returns rpc_s_incomplete_name, which
indicates that the name is incomplete.
Usage
An application calls rpc_ns_entry_expand_name to obtain a fully
expanded entry name.
The RPC runtime allocates memory for the returned expanded_name
parameter. The application is responsible for calling rpc_string_free
for that returned parameter string.
The returned and expanded entry name accounts for local name
translations and differences in locally defined naming schemas. For
example, suppose the entry in the name service is
/.:/subsys/PrintQ/server1
Upon return from rpc_ns_entry_expand_name, the expanded name could be
/.../abc.com/subsys/PrintQ/server1
For more information about local names and their expansions, see the
DCE for OS/2 Warp: Administration Guide.
Related Information
Routines:
rpc_string_free
ΓòÉΓòÉΓòÉ 5.8.71. rpc_ns_entry_inq_resolution ΓòÉΓòÉΓòÉ
Purpose
Resolves the cell name space components of a name and returns partial
results.
Format
#include <dce/rpc.h>
void rpc_ns_entry_inq_resolution(
unsigned32 entry_name_syntax,
unsigned_char_t *entry_name,
unsigned_char_t **resolved_name,
unsigned_char_t **unresolved_name,
unsigned32 *status);
Parameters
Input
entry_name_syntax An integer value that specifies the syntax of the
parameter entry_name.
To use the syntax specified in the
RPC_DEFAULT_ENTRY_SYNTAX environment variable, supply a
value of rpc_c_ns_syntax_default.
entry_name The entry name on which the attempted name resolution
is to be done. The name can be specified in either
cell-relative or global form.
Input/Output
resolved_name Returns a pointer to the resolved portion of the entry
name. The resolved_name string returned is null
terminated and does not contain trailing component
separators (that is, no trailing slash (/) characters).
If NULL is specified on input for this parameter,
nothing is returned.
unresolved_name Returns a pointer to the unresolved portion of the
entry name. The unresolved_name string returned is a
relative name containing no leading component
separators (that is, it contains no leading slash (/)
characters).
If NULL is specified on input for this parameter,
nothing is returned.
Output
status Returns the status code from this routine. On
successful completion, the routine returns rpc_s_ok.
Otherwise, it returns one of the following errors:
rpc_s_partial_results The entry name was only
partially resolved within the cell
name space and the value of
unresolved_name points to the
residual of the name.
rpc_s_invalid_name_syntax The requested name
syntax is invalid.
rpc_s_unsupported_name_syntax The requested name
syntax is not supported.
Usage
The rpc_ns_entry_inq_resolution routine attempts to read an entry in
the cell name space. If the entire entry name as specified is
successfully read, the full resolution of the entry name (that is,
the originally-specified entry_name) is returned in resolved_name and
the status is set to rpc_s_ok.
If the read was unsuccessful because the full entry was not found in
the cell name space, the status code is set to rpc_s_partial_results
and:
o The part of the name successfully read is returned in
resolved_name.
o The remaining (unresolved) part of the name is returned in
unresolved_name.
If the status code is rpc_s_partial_results and the (non-empty)
return parameter resolved_name specifies a leaf (not a directory)
entry, the contents of resolved_name can be used in subsequent calls
to the NSI interface to obtain a binding handle for the server that
exported to the entry. This behavior allows applications to implement
name space junctions to their own internally-implemented name spaces.
Using this routine, clients can attempt to bind to overqualified name
entries whose resolved_name part is the name of the server entry and
whose unresolved_name part is the path name (meaningful to the
server) of some object managed by the application. Calling
rpc_ns_entry_inq_resolution with the full name allows the client to
learn the part of the name that denotes the server entry it must
import bindings from; it can then bind to the server, and pass the
rest of the name, which the server interprets as appropriate. The
sec_acl_bind routine, for example, works this way.
The RPC runtime allocates memory for the returned resolved_name and
unresolved_name parameters. The application is responsible for
calling rpc_string_free to free the allocated memory.
Permissions Required
The application requires read permission for the name entries that
are resolved within the cell name space.
Related Information
Routines:
rpc_ns_binding_export
rpc_ns_binding_import_begin
rpc_ns_binding_import_done
rpc_ns_binding_import_next
rpc_ns_binding_inq_entry_name
rpc_ns_binding_lookup_begin
rpc_ns_binding_lookup_done
rpc_ns_binding_lookup_next
rpc_ns_binding_select
rpc_ns_binding_unexport
ΓòÉΓòÉΓòÉ 5.8.72. rpc_ns_entry_object_inq_begin ΓòÉΓòÉΓòÉ
Purpose
Creates an inquiry context for viewing the objects of an entry in the
name service database. This routine is used by client, server, or
management applications.
Format
#include <dce/rpc.h>
void rpc_ns_entry_object_inq_begin(
unsigned32 entry_name_syntax,
unsigned_char_t *entry_name,
rpc_ns_handle_t *inquiry_context,
unsigned32 *status);
Parameters
Input
entry_name_syntax An integer value that specifies the syntax of the
entry_name parameter. To use the syntax specified in
the RPC_DEFAULT_ENTRY_SYNTAX environment variable,
provide a value of rpc_c_ns_syntax_default.
entry_name Specifies the entry in the name service database for
which object UUIDs are viewed. This can be either the
global or the cell-relative name.
Output
inquiry_context Returns a name service handle for use with
rpc_ns_entry_object_inq_next and
rpc_ns_entry_object_inq_done.
status Returns the status code from this routine. On
successful completion, the routine returns rpc_s_ok.
Otherwise, it returns one of the following errors:
rpc_s_incomplete_name Incomplete name.
rpc_s_invalid_name_syntax The name syntax is not
valid.
rpc_s_unsupported_name_syntax Unsupported name
syntax.
Usage
The rpc_ns_entry_object_inq_begin routine creates an inquiry context
for viewing the object UUIDs exported to entry_name.
Before calling rpc_ns_entry_object_inq_next, the application must
first call this routine to create an inquiry context.
When finished viewing the object UUIDs, the application calls
rpc_ns_entry_object_inq_done to delete the inquiry context.
Related Information
Routines:
rpc_ns_binding_export
rpc_ns_entry_object_inq_done
rpc_ns_entry_object_inq_next
rpc_ns_mgmt_handle_set_exp_age
ΓòÉΓòÉΓòÉ 5.8.73. rpc_ns_entry_object_inq_done ΓòÉΓòÉΓòÉ
Purpose
Deletes the inquiry context for viewing the objects of an entry in
the name service database. This routine is used by client, server, or
management applications.
Format
#include <dce/rpc.h>
void rpc_ns_entry_object_inq_done(
rpc_ns_handle_t *inquiry_context,
unsigned32 *status);
Parameters
Input/Output
inquiry_context Specifies the name service handle to delete. (A name
service handle is created by calling
rpc_ns_entry_object_inq_begin.) Returns the value NULL.
Output
status Returns the status code from this routine. On
successful completion, the routine returns rpc_s_ok.
Otherwise, it returns rpc_s_invalid_ns_handle, which
indicates that the name service handle is not valid.
Usage
The rpc_ns_entry_object_inq_done routine deletes an inquiry context
created by calling rpc_ns_entry_object_inq_begin.
An application calls this routine after viewing exported object UUIDs
using the rpc_ns_entry_object_inq_next routine.
Related Information
Routines:
rpc_ns_entry_object_inq_begin
rpc_ns_entry_object_inq_next
ΓòÉΓòÉΓòÉ 5.8.74. rpc_ns_entry_object_inq_next ΓòÉΓòÉΓòÉ
Purpose
Returns one object at a time from an entry in the name service
database. This routine is used by client, server, or management
applications.
Format
#include <dce/rpc.h>
void rpc_ns_entry_object_inq_next(
rpc_ns_handle_t inquiry_context,
uuid_t *obj_uuid,
unsigned32 *status);
Parameters
Input
inquiry_context Specifies a name service handle. This handle is
returned from rpc_ns_entry_object_inq_begin.
Output
obj_uuid Returns an exported object UUID.
status Returns the status code from this routine. On
successful completion, the routine returns rpc_s_ok.
Otherwise, it returns one of the following errors:
rpc_s_class_version_mismatch RPC class version
mismatch.
rpc_s_entry_not_found The name service entry was
not found.
rpc_s_incomplete_name Incomplete name.
rpc_s_invalid_ns_handle The name service handle is
not valid.
rpc_s_name_service_unavailable The name service is
unavailable.
rpc_s_no_more_members No more members.
rpc_s_no_ns_permission There is no permission for
the name service operation.
rpc_s_not_rpc_entry Not an RPC entry.
Usage
The rpc_ns_entry_object_inq_next routine returns one of the object
UUIDs exported to an entry in the name service database. The
entry_name parameter in rpc_ns_entry_object_inq_begin specifies the
entry.
An application can view all of the exported object UUIDs by
repeatedly calling rpc_ns_entry_object_inq_next. When all the object
UUIDs are viewed, this routine returns rpc_s_no_more_members to the
status parameter. The returned object UUIDs are unordered.
The application supplies the memory for the object UUID returned in
the obj_uuid parameter.
After viewing the object UUIDs, the application must call
rpc_ns_entry_object_inq_done to delete the inquiry context.
The order that rpc_ns_entry_object_inq_next returns object UUIDs in
can be different for each viewing of an entry. This means that the
order that an application receives object UUIDs in can be different
each time the application runs.
Permissions Required
You need read permission to the CDS object entry (the target name
service entry).
Related Information
Routines:
rpc_ns_binding_export
rpc_ns_entry_object_inq_begin
rpc_ns_entry_object_inq_done
ΓòÉΓòÉΓòÉ 5.8.75. rpc_ns_group_delete ΓòÉΓòÉΓòÉ
Purpose
Deletes a group attribute. This routine is used by client, server, or
management applications.
Format
#include <dce/rpc.h>
void rpc_ns_group_delete(
unsigned32 group_name_syntax,
unsigned_char_t *group_name,
unsigned32 *status);
Parameters
Input
group_name_syntax An integer value that specifies the syntax of the
group_name parameter. To use the syntax specified in
the RPC_DEFAULT_ENTRY_SYNTAX environment variable,
provide the integer value rpc_c_ns_syntax_default.
group_name Specifies the RPC group to delete. This can be either
the global or the cell-relative name.
Output
status Returns the status code from this routine. On
successful completion, the routine returns rpc_s_ok.
Otherwise, it returns one of the following errors:
rpc_s_entry_not_found The name service entry was
not found.
rpc_s_incomplete_name Incomplete name.
rpc_s_invalid_name_syntax The name syntax is not
valid.
rpc_s_name_service_unavailable The name service is
unavailable.
rpc_s_no_ns_permission There is no permission for
the name service operation.
rpc_s_unsupported_name_syntax Unsupported name
syntax.
Usage
The rpc_ns_group_delete routine deletes the group attribute from the
specified entry in the name service database.
Neither the specified entry nor the entries represented by the group
members are deleted.
Permissions Required
You need write permission to the CDS object entry (the target group
entry).
Related Information
Routines:
rpc_ns_group_mbr_add
rpc_ns_group_mbr_remove
ΓòÉΓòÉΓòÉ 5.8.76. rpc_ns_group_mbr_add ΓòÉΓòÉΓòÉ
Purpose
Adds an entry name to a group. If necessary, this routine creates the
group entry. This routine is used by client, server, or management
applications.
Format
#include <dce/rpc.h>
void rpc_ns_group_mbr_add(
unsigned32 group_name_syntax,
unsigned_char_t *group_name,
unsigned32 member_name_syntax,
unsigned_char_t *member_name,
unsigned32 *status);
Parameters
Input
group_name_syntax An integer value that specifies the syntax of the
group_name parameter.
To use the syntax specified in the
RPC_DEFAULT_ENTRY_SYNTAX environment variable, provide
the rpc_c_ns_syntax_default.
group_name Specifies the RPC group that receives a new member.
This can be either the global or cell-relative name.
member_name_syntax An integer value that specifies the syntax of the
member_name parameter.
To use the syntax specified in the
RPC_DEFAULT_ENTRY_SYNTAX environment variable, provide
the rpc_c_ns_syntax_default.
member_name Name of the new RPC group member. This can be either
the global or cell-relative name.
Output
status Returns the status code from this routine. On
successful completion, the routine returns rpc_s_ok.
Otherwise, it returns one of the following errors:
rpc_s_class_version_mismatch RPC class version
mismatch.
rpc_s_incomplete_name Incomplete name.
rpc_s_invalid_name_syntax The name syntax is not
valid.
rpc_s_name_service_unavailable The name service is
unavailable.
rpc_s_no_ns_permission There is no permission for
the name service operation.
rpc_s_unsupported_name_syntax Unsupported name
syntax.
Usage
The rpc_ns_group_mbr_add routine adds, to the name service database,
an entry name as a member to the name service interface (NSI) group
attribute of an entry. The group_name parameter specifies the group
entry.
If the specified group_name entry does not exist, this routine
creates the entry with a group attribute and adds the group member
specified by the member_name parameter. In this case, the application
must have permission to create the entry. Otherwise, a management
application with the necessary permissions creates the entry by
calling rpc_ns_mgmt_entry_create before the application is run.
An application can add the entry in the member_name parameter to a
group before it creates the entry itself.
Permissions Required
You need both read permission and write permission to the CDS object
entry (the target group entry). If the entry does not exist, you also
need insert permission to the parent directory.
Related Information
Routines:
rpc_ns_group_mbr_remove
rpc_ns_mgmt_entry_create
ΓòÉΓòÉΓòÉ 5.8.77. rpc_ns_group_mbr_inq_begin ΓòÉΓòÉΓòÉ
Purpose
Creates an inquiry context for viewing group members. This routine is
used by client, server, or management applications.
Format
#include <dce/rpc.h>
void rpc_ns_group_mbr_inq_begin(
unsigned32 group_name_syntax,
unsigned_char_t *group_name,
unsigned32 member_name_syntax,
rpc_ns_handle_t *inquiry_context,
unsigned32 *status);
Parameters
Input
group_name_syntax An integer value that specifies the syntax of the
group_name parameter.
To use the syntax specified in the
RPC_DEFAULT_ENTRY_SYNTAX environment variable, provide
the rpc_c_ns_syntax_default.
group_name Specifies the name of the RPC group to view.
member_name_syntax An integer value that specifies the syntax of the
member_name parameter in the rpc_ns_group_mbr_inq_next
routine.
To use the syntax specified in the
RPC_DEFAULT_ENTRY_SYNTAX environment variable, provide
rpc_c_ns_syntax_default.
Output
inquiry_context Returns a name service handle for use with
rpc_ns_group_mbr_inq_next and
rpc_ns_group_mbr_inq_done.
status Returns the status code from this routine. On
successful completion, the routine returns rpc_s_ok.
Otherwise, it returns one of the following errors:
rpc_s_incomplete_name Incomplete name.
rpc_s_invalid_name_syntax The name syntax is not
valid.
rpc_s_unsupported_name_syntax Unsupported name
syntax.
Usage
The rpc_ns_group_mbr_inq_begin routine creates an inquiry context for
viewing the members of an RPC group.
Before calling rpc_ns_group_mbr_inq_next, the application must first
call this routine to create an inquiry context.
When the application finishes viewing the RPC group members, it calls
the rpc_ns_group_mbr_inq_done routine to delete the inquiry context.
Related Information
Routines:
rpc_ns_group_mbr_add
rpc_ns_group_mbr_inq_done
rpc_ns_group_mbr_inq_next
rpc_ns_mgmt_handle_set_exp_age
ΓòÉΓòÉΓòÉ 5.8.78. rpc_ns_group_mbr_inq_done ΓòÉΓòÉΓòÉ
Purpose
Deletes the inquiry context for a group. This routine is used by
client, server, or management applications.
Format
#include <dce/rpc.h>
void rpc_ns_group_mbr_inq_done(
rpc_ns_handle_t *inquiry_context,
unsigned32 *status);
Parameters
Input/Output
inquiry_context Specifies the name service handle to delete. (A name
service handle is created by calling
rpc_ns_group_mbr_inq_begin.) Returns the value NULL.
Output
status Returns the status code from this routine. On
successful completion, the routine returns rpc_s_ok.
Otherwise, it returns rpc_s_invalid_ns_handle, which
indicates that the name service handle is not valid.
Usage
The rpc_ns_group_mbr_inq_done routine deletes an inquiry context
created by calling rpc_ns_group_mbr_inq_begin.
An application calls this routine after viewing RPC group members
using rpc_ns_group_mbr_inq_next.
Related Information
Routines:
rpc_ns_group_mbr_inq_begin
rpc_ns_group_mbr_inq_next
ΓòÉΓòÉΓòÉ 5.8.79. rpc_ns_group_mbr_inq_next ΓòÉΓòÉΓòÉ
Purpose
Returns one member name at a time from a group. This routine is used
by client, server, or management applications.
Format
#include <dce/rpc.h>
void rpc_ns_group_mbr_inq_next(
rpc_ns_handle_t inquiry_context,
unsigned_char_t **member_name,
unsigned32 *status);
Parameters
Input
inquiry_context Specifies a name service handle. This handle is
returned from the rpc_ns_group_mbr_inq_begin routine.
Output
member_name Returns a pointer to an RPC group member name. The name
is a global name.
The syntax of the returned name is specified by the
member_name_syntax parameter in the
rpc_ns_group_mbr_inq_begin routine.
Specify NULL to prevent the routine from returning this
parameter. In this case, the application does not call
rpc_string_free.
status Returns the status code from this routine. On
successful completion, the routine returns rpc_s_ok.
Otherwise, it returns one of the following errors:
rpc_s_class_version_mismatch RPC class version
mismatch.
rpc_s_entry_not_found The name service entry was
not found.
rpc_s_invalid_ns_handle The name service handle is
not valid.
rpc_s_name_service_unavailable The name service is
unavailable.
rpc_s_no_more_members No more members.
rpc_s_no_ns_permission There is no permission for
the name service operation.
rpc_s_not_rpc_entry Not an RPC entry.
Usage
The rpc_ns_group_mbr_inq_next routine returns one member of the RPC
group specified by the group_name parameter in
rpc_ns_group_mbr_inq_begin.
An application can view all the members of an RPC group by repeatedly
calling rpc_ns_group_mbr_inq_next. When all the group members have
been viewed, this routine returns an rpc_s_no_more_members status.
The returned group members are unordered.
On each call to this routine that returns a member name (as a global
name), the RPC runtime allocates memory for the returned member_name.
The application calls rpc_string_free for each returned member_name
string.
After viewing the RPC group's members, the application must call
rpc_ns_group_mbr_inq_done to delete the inquiry context.
Permissions Required
You need read permission to the CDS object entry (the target group
entry).
Related Information
Routines:
rpc_ns_group_mbr_inq_begin
rpc_ns_group_mbr_inq_done
rpc_string_free
ΓòÉΓòÉΓòÉ 5.8.80. rpc_ns_group_mbr_remove ΓòÉΓòÉΓòÉ
Purpose
Removes an entry name from a group. This routine is used by client,
server, or management applications.
Format
#include <dce/rpc.h>
void rpc_ns_group_mbr_remove(
unsigned32 group_name_syntax,
unsigned_char_t *group_name,
unsigned32 member_name_syntax,
unsigned_char_t *member_name,
unsigned32 *status);
Parameters
Input
group_name_syntax An integer value that specifies the syntax of the
group_name parameter.
To use the syntax specified in the
RPC_DEFAULT_ENTRY_SYNTAX environment variable, provide
rpc_c_ns_syntax_default.
group_name Specifies the RPC group from which to remove
member_name. This can be either the global or
cell-relative name.
member_name_syntax An integer value that specifies the syntax of the
member_name parameter.
To use the syntax specified in the
RPC_DEFAULT_ENTRY_SYNTAX environment variable, provide
rpc_c_ns_syntax_default.
member_name Specifies the member to remove from the name service
interface (NSI) group attribute in the group_name
entry. This can be either the global or cell-relative
name.
Output
status Returns the status code from this routine. On
successful completion, the routine returns rpc_s_ok.
Otherwise, it returns one of the following errors:
rpc_s_entry_not_found The name service entry was
not found.
rpc_s_group_member_not_found The group member was
not found.
rpc_s_incomplete_name Incomplete name.
rpc_s_invalid_name_syntax The name syntax is not
valid.
rpc_s_name_service_unavailable The name service is
unavailable.
rpc_s_no_ns_permission There is no permission for
the name service operation.
rpc_s_unsupported_name_syntax Unsupported name
syntax.
Usage
The rpc_ns_group_mbr_remove routine removes a member from the NSI
group attribute in the group_name entry.
Permissions Required
You need both read permission and write permission to the CDS object
entry (the target group entry).
Related Information
Routines:
rpc_ns_group_mbr_add
ΓòÉΓòÉΓòÉ 5.8.81. rpc_ns_import_ctx_add_eval ΓòÉΓòÉΓòÉ
Purpose
Adds an evaluation routine to an import context.
This routine is used by client applications.
Format
#include <dce/rpc.h>
void rpc_ns_import_ctx_add_eval(
rpc_ns_handle_t *import_context,
unsigned32 function_type,
rpc_ns_handle_t *eval_args,
void *eval_func,
void *free_func,
error_status_t *status);
Parameters
Input
import_context The name service handle obtained from the
rpc_ns_binding_import_begin routine.
func_type The type of evaluation routine. This value currently
must be rpc_cs_code_eval_func.
eval_args An opaque data type that contains data used by the
evaluation routine.
Client applications adding a DCE RPC code sets
evaluation routine (rpc_cs_eval_with_universal or
rpc_cs_eval_without_universal) specify the server's NSI
entry name in this parameter.
eval_func A function pointer to the evaluation routine to be
called from the rpc_ns_binding_import_next routine. The
void declaration for eval_func means that the routine
does not return a value.
Client applications adding a DCE RPC code sets
evaluation routine (rpc_cs_eval_with_universal or
rpc_cs_eval_without_universal) specify the routine name
in this parameter.
free_func A function pointer to a routine that is called from
rpc_ns_binding_import_done and which performs
application-specific cleanup. Client applications
adding a DCE RPC code sets evaluation routine
(rpc_cs_eval_with_universal or
rpc_cs_eval_without_universal) specify NULL in this
parameter.
Output
import_context Returns the name service handle which contains the
rpc_ns_binding_import_next and
rpc_ns_binding_import_done routines.
status Returns the status code from this routine. On
successful completion, the routine returns rpc_s_ok.
Otherwise, it returns one of the following errors:
rpc_s_no_memory The RPC runtime could not allocate
heap storage.
rpc_s_invalid_ns_handle The import_context
parameter was not valid.
Usage
The rpc_ns_import_ctx_add_eval routine adds an evaluation routine to
an import context created by the rpc_ns_binding_import_begin routine.
The evaluation routine adds additional criteria to that used by
rpc_ns_binding_import_next (that is, protocol and interface
information) for importing compatible server binding handles. Client
applications call the rpc_ns_import_ctx_add_eval routine once for
each evaluation routine to be added to an import context (if there
are multiple evaluation routines to be set up.)
If the user-specified evaluation routine needs to perform special
cleanup routines, such as deleting a temporary file from a disk, use
the free_func parameter to specify the cleanup routine to be called
from rpc_ns_binding_import_done.
For DCE 1.1, client applications that transfer international
character data in a heterogeneous character set and code set
environment use the rpc_ns_import_ctx_add_eval routine to add one or
more code sets evaluation routines to the import context returned by
the rpc_ns_binding_import_begin routine. When the client application
calls the rpc_ns_binding_import_next routine to import compatible
binding handles for servers, this routine calls the code sets
evaluation routine, which applies client-server character set and
code sets compatibility checking as other criteria for compatible
binding selection.
The code sets compatibility evaluation routine specified can be one
of the following:
rpc_cs_eval_with_universal A DCE RPC code sets evaluation routine
that evaluates character set and code sets
compatibility between client and server. If client and
server character sets are compatible but their
supported code sets are not, the routine sets code set
tags that direct the client and server stubs to convert
character data to the DCE intermediate code set, which
is the ISO 10646 (or universal) code set (UCS-2, Level
1).
rpc_cs_eval_without_universal A DCE RPC code sets evaluation routine
that evaluates character set and code sets
compatibility between client and server. If client and
server character sets are compatible, but their
supported code sets are not, the routine attempts to
return the message rpc_s_no_compat_codesets to the
rpc_ns_binding_import_next routine.
application_supplied_routine A user-written code sets evaluation
routine. Application developers writing
internationalized DCE applications can develop their
own code sets evaluation routines for client-server
code sets evaluation if the DCE-supplied routines do
not meet their application's needs.
Restrictions
Client applications that add evaluation routines to the server
binding import context cannot use the automatic binding method to
bind to a server.
Related Information
Routines:
rpc_cs_eval_with_universal
rpc_cs_eval_without_universal
rpc_ns_binding_import_begin
rpc_ns_binding_import_done
rpc_ns_binding_import_next
rpc_ns_mgmt_handle_set_exp_age
ΓòÉΓòÉΓòÉ 5.8.82. rpc_ns_mgmt_binding_unexport ΓòÉΓòÉΓòÉ
Purpose
Removes multiple binding handles or object UUIDs from an entry in the
name service database. This routine is used by management
applications.
Format
#include <dce/rpc.h>
void rpc_ns_mgmt_binding_unexport(
unsigned32 entry_name_syntax,
unsigned_char_t *entry_name,
rpc_if_id_t *if_id,
unsigned32 vers_option,
uuid_vector_t *object_uuid_vec,
unsigned32 *status);
Parameters
Input
entry_name_syntax An integer value that specifies the syntax of the
entry_name parameter.
To use the syntax specified in the
RPC_DEFAULT_ENTRY_SYNTAX environment variable, provide
rpc_c_ns_syntax_default.
entry_name Specifies an entry name whose binding handles or object
UUIDs are removed. This can be either the global or
cell-relative name.
if_id Specifies an interface identifier for the binding
handles to be removed from the name service database.
The value NULL indicates that no binding handles are
removed (only object UUIDs are removed).
vers_option Specifies how the rpc_ns_mgmt_binding_unexport routine
uses the vers_major and the vers_minor fields of the
if_id parameter.
The following list presents the accepted values for
this parameter:
Value Description
rpc_c_vers_all Unexports (removes) all bindings
for the interface UUID in if_id,
regardless of the version
numbers. For this value, specify
0 (zero) for both the major and
minor versions in if_id.
rpc_c_vers_compatible Removes those bindings for
the interface UUID in if_id with
the same major version as in
if_id, and with a minor version
greater than or equal to the
minor version in if_id.
rpc_c_vers_exact Removes those bindings for the
interface UUID in if_id with the
same major and minor versions as
in if_id.
rpc_c_vers_major_only Removes those bindings for
the interface UUID in if_id with
the same major version as in
if_id (ignores the minor
version). For this value, specify
0 (zero) for the minor version in
if_id.
rpc_c_vers_upto Removes those bindings that offer
a version of the specified
interface UUID less than or equal
to the specified major and minor
version. (For example, if the
if_id parameter contains V2.0 and
the name service entry contains
binding handles with the versions
V1.3, V2.0, and V2.1,
rpc_ns_mgmt_binding_unexport
removes the binding handles with
V1.3 and V2.0.)
object_uuid_vec Specifies a vector of object UUIDs to be removed from
the name service database. The application constructs
this vector. The value NULL indicates that no object
UUIDs are removed (only binding handles are removed).
Output
status Returns the status code from this routine. On
successful completion, the routine returns rpc_s_ok.
Otherwise, it returns one of the following errors:
rpc_s_entry_not_found The name service entry was
not found.
rpc_s_incomplete_name Incomplete name.
rpc_s_interface_not_found The interface was not
found.
rpc_s_invalid_name_syntax The name syntax is not
valid.
rpc_s_invalid_vers_option The version option is
not valid.
rpc_s_name_service_unavailable The name service is
unavailable.
rpc_s_no_ns_permission There is no permission for
the name service operation.
rpc_s_not_all_objs_unexported Not all objects
unexported.
rpc_s_nothing_to_unexport Nothing to unexport.
rpc_s_not_rpc_entry Not an RPC entry.
rpc_s_unsupported_name_syntax Unsupported name
syntax.
Usage
The rpc_ns_mgmt_binding_unexport routine allows a management
application to unexport (that is, remove) any of the following from
an entry in the name service database:
o All the binding handles for a specified interface UUID,
qualified by the interface version numbers (major and minor)
o One or more object UUIDs of resources
o Both binding handles and object UUIDs of resources
A management application can remove an interface and objects in a
single call to this routine, or it can remove them separately.
If the rpc_ns_mgmt_binding_unexport routine does not find any binding
handles for the specified interface, the routine returns an
rpc_s_interface_not_found status code and does not remove the object
UUIDs, if any are specified.
If one or more binding handles for the specified interface are found
and removed without error, rpc_ns_mgmt_binding_unexport removes the
specified object UUIDs, if any.
If any of the specified object UUIDs are not found,
rpc_ns_mgmt_binding_unexport returns the rpc_not_all_objs_unexported
status code.
A management application, in addition to calling this routine, also
calls rpc_mgmt_ep_unregister to remove any servers that have
registered with the local endpoint map.
Use this routine with caution and only when you expect a server to be
unavailable for an extended time; for example, when it is permanently
removed from service.
Additionally, keep in mind that name service databases are designed
to be relatively stable. In replicated name service databases,
frequent use of rpc_ns_binding_export and
rpc_ns_mgmt_binding_unexport causes the name service to repeatedly
remove and replace the same entry, which can cause performance
problems.
Permissions Required
You need both read permission and write permission to the CDS object
entry (the target name service entry).
Related Information
Routines:
rpc_mgmt_ep_unregister
rpc_ns_binding_export
rpc_ns_binding_unexport
ΓòÉΓòÉΓòÉ 5.8.83. rpc_ns_mgmt_entry_create ΓòÉΓòÉΓòÉ
Purpose
Creates an entry in the name service database. This routine is used
by management applications.
Format
#include <dce/rpc.h>
void rpc_ns_mgmt_entry_create(
unsigned32 entry_name_syntax,
unsigned_char_t *entry_name,
unsigned32 *status);
Parameters
Input
entry_name_syntax An integer value that specifies the syntax of the
entry_name parameter. To use the syntax specified in
the RPC_DEFAULT_ENTRY_SYNTAX environment variable,
provide rpc_c_ns_syntax_default.
entry_name Specifies the name of the entry to create. This can be
either the global or cell-relative name.
Output
status Returns the status code from this routine. On
successful completion, the routine returns rpc_s_ok.
Otherwise, it returns one of the following errors:
rpc_s_entry_already_exists The name service entry
already exists.
rpc_s_incomplete_name Incomplete name.
rpc_s_invalid_name_syntax The name syntax is not
valid.
rpc_s_name_service_unavailable The name service is
unavailable.
rpc_s_no_ns_permission There is no permission for
the name service operation.
rpc_s_unsupported_name_syntax Unsupported name
syntax.
Usage
The rpc_ns_mgmt_entry_create routine creates an entry in the name
service database.
A management application can call rpc_ns_mgmt_entry_create to create
an entry in the name service database for use by another application
that does not itself have the necessary name service permissions to
create an entry.
Permissions Required
You need both read permission and write permission to the CDS object
entry (the target name service entry). You also need insert
permission to the parent directory.
Related Information
Routines:
rpc_ns_mgmt_entry_delete
ΓòÉΓòÉΓòÉ 5.8.84. rpc_ns_mgmt_entry_delete ΓòÉΓòÉΓòÉ
Purpose
Deletes an entry from the name service database. This routine is used
by management applications.
Format
#include <dce/rpc.h>
void rpc_ns_mgmt_entry_delete(
unsigned32 entry_name_syntax,
unsigned_char_t *entry_name,
unsigned32 *status);
Parameters
Input
entry_name_syntax An integer value that specifies the syntax of the
entry_name parameter. To use the syntax specified in
the RPC_DEFAULT_ENTRY_SYNTAX environment variable,
provide rpc_c_ns_syntax_default.
entry_name Specifies the name of the entry to delete. This can be
either the global or cell-relative name.
Output
status Returns the status code from this routine. On
successful completion, the routine returns rpc_s_ok.
Otherwise, it returns one of the following errors:
rpc_s_entry_not_found The name service entry was
not found.
rpc_s_incomplete_name Incomplete name.
rpc_s_invalid_name_syntax The name syntax is not
valid.
rpc_s_name_service_unavailable The name service is
unavailable.
rpc_s_no_ns_permission There is no permission for
the name service operation.
rpc_s_not_rpc_entry Not an RPC entry.
rpc_s_unsupported_name_syntax Unsupported name
syntax.
Usage
The rpc_ns_mgmt_entry_delete routine removes an RPC entry from the
name service database.
Management applications use this routine only when an entry is no
longer needed, such as when a server is permanently removed from
service. If the entry is a member of a group or profile, it must also
be deleted from the group or profile.
Use this routine cautiously. Since name service databases are
designed to be relatively stable, the frequent use of
rpc_ns_mgmt_entry_delete can result in the following difficulties:
o Performance problems - Creating and deleting entries in client
or server applications causes the name service to repeatedly
remove and replace the same entry in the name service database,
which can lead to performance problems.
o Lost entry updates - When multiple applications access a single
entry through different replicas of a name service database,
updates to the entry can be lost.
In this situation, if one application deletes the entry and
another application updates the entry before the replicas are
synchronized, the delete operation takes precedence over the
update operation. When the replicas are synchronized, the update
is lost because the entry is deleted from all replicas.
Permissions Required
You need read permission to the CDS object entry (the target name
service entry). You also need delete permission to the CDS object
entry or to the parent directory.
Related Information
Routines:
rpc_ns_mgmt_entry_create
ΓòÉΓòÉΓòÉ 5.8.85. rpc_ns_mgmt_entry_inq_if_ids ΓòÉΓòÉΓòÉ
Purpose
Returns the list of interfaces exported to an entry in the name
service database. This routine is used by client, server, or
management applications.
Format
#include <dce/rpc.h>
void rpc_ns_mgmt_entry_inq_if_ids(
unsigned32 entry_name_syntax,
unsigned_char_t *entry_name,
rpc_if_id_vector_t **if_id_vec,
unsigned32 *status);
Parameters
Input
entry_name_syntax An integer value that specifies the syntax of the
entry_name parameter. To use the syntax specified in
the RPC_DEFAULT_ENTRY_SYNTAX environment variable,
provide rpc_c_ns_syntax_default.
entry_name Specifies the entry in the name service database for
which an interface identifier vector is returned. This
can be either the global or cell-relative name.
Output
if_id_vec Returns the address of the interface identifier vector.
status Returns the status code from this routine. On
successful completion, the routine returns rpc_s_ok.
Otherwise, it returns one of the following errors:
rpc_s_entry_not_found The name service entry was
not found.
rpc_s_incomplete_name Incomplete name.
rpc_s_invalid_name_syntax The name syntax is not
valid.
pc_s_name_service_unavailable The name service is
unavailable.
rpc_s_no_interfaces_exported No interfaces were
exported to the entry.
rpc_s_no_ns_permission There is no permission for
the name service operation.
rpc_s_unsupported_name_syntax Unsupported name
syntax.
Usage
The rpc_ns_mgmt_entry_inq_if_ids routine returns an interface
identifier vector containing the interfaces of binding handles
exported to the entry_name parameter.
This routine uses an expiration age of 0 (zero) to cause an immediate
update of the local copy of name service data. The description of
rpc_ns_mgmt_inq_exp_age contains an explanation of the expiration
age.
The application calls rpc_if_id_vector_free to release memory used by
the returned vector.
Permissions Required
You need read permission to the CDS object entry (the target name
service entry).
Related Information
Routines:
rpc_if_id_vector_free
rpc_if_inq_id
rpc_ns_binding_export
ΓòÉΓòÉΓòÉ 5.8.86. rpc_ns_mgmt_free_codesets ΓòÉΓòÉΓòÉ
Purpose
Frees a code sets array that has been allocated by the RPC runtime.
This routine is used by client and server applications.
Format
#include <dce/rpc.h>
void rpc_ns_mgmt_free_codesets(
pc_codeset_mgmt_p_t *code_sets_array,
error_status_t *status);
Parameters
Input/Output
code_sets_array A pointer to a code sets array that has been
allocated by a call to the rpc_ns_mgmt_read_codesets
routine or the rpc_rgy_get_codesets routine.
Output
status Returns the status code from this routine. On
successful completion, the routine returns rpc_s_ok.
Otherwise, it returns an error.
Usage
The rpc_ns_mgmt_free_codesets routine belongs to a set of DCE RPC
routines for character and code set interoperability. These routines
permit client and server applications to transfer international
character data in a heterogeneous character set and code sets
environment.
The rpc_ns_mgmt_free_codesets routine frees from the client
application's memory a code sets array allocated by a client call to
the rpc_ns_mgmt_read_codesets or the rpc_rgy_get_codesets routines.
The routine frees from a server application's memory a code sets
array allocated by a server call to the rpc_rgy_get_codesets routine.
Client applications use the rpc_ns_mgmt_read_codesets routine to
retrieve a server's supported code sets from the name service
database in order to evaluate them against the code sets that the
client supports. Clients and servers use the rpc_rgy_get_codesets
routine to get their supported code sets from the code set registry.
Server applications then export them into the name service database
with the rpc_ns_mgmt_set_attribute routine. Clients and servers use
the rpc_ns_mgmt_free_codesets routine to free the memory allocated to
the code sets array as part of their cleanup procedures.
Related Information
Routines:
rpc_ns_mgmt_read_codesets
rpc_rgy_get_codesets
ΓòÉΓòÉΓòÉ 5.8.87. rpc_ns_mgmt_handle_set_exp_age ΓòÉΓòÉΓòÉ
Purpose
Sets a handle's expiration age for local copies of name service data.
This routine is used by client, server, or management applications.
Format
#include <dce/rpc.h>
void rpc_ns_mgmt_handle_set_exp_age(
rpc_ns_handle_t ns_handle,
unsigned32 expiration_age,
unsigned32 *status);
Parameters
Input
ns_handle Specifies the name service handle for which you supply
an expiration age. An RPC name service interface (NSI)
inquiry begin operation returns a name service handle.
An example is the operation that routine
rpc_ns_entry_object_inq_begin performs; it returns a
name service handle in its inquiry_context parameter.
expiration_age This integer value specifies the expiration age, in
seconds, of local name service data. This data is read
by all RPC NSI next routines that use the specified
ns_handle parameter. An example is the
rpc_ns_entry_object_inq_next routine; it accepts a name
service handle in its inquiry_context parameter.
An expiration age of 0 (zero) causes an immediate
update of the local name service data.
Output
status Returns the status code from this routine. On
successful completion, the routine returns rpc_s_ok.
Otherwise, it returns rpc_s_invalid_ns_handle, which
indicates that the name service handle is not valid.
Usage
The rpc_ns_mgmt_handle_set_exp_age routine sets an expiration age for
a specified name service handle (in ns_handle). The expiration age is
the amount of time, in seconds, that a local copy of data from a name
service attribute can exist before a request from the application for
the attribute requires updating the local copy. When an application
begins running, the RPC runtime specifies a random value of between 8
and 12 hours as the default expiration age. The default is global to
the application. An expiration age applies only to a specific name
service handle and temporarily overrides the current global
expiration age.
Normally, avoid using this routine; instead, rely on the
application's global expiration age.
A handle's expiration age is used exclusively by RPC NSI next
operations (which read data from name service attributes). A next
operation normally starts by looking for a local copy of the
attribute data being requested by an application. In the absence of a
local copy, the next operation creates one with fresh attribute data
from the name service database. If a local copy already exists, the
operation compares its actual age to the expiration age being used by
the application (which in this case is the expiration age set for the
name service handle). If the actual age exceeds the handle's
expiration age, the operation automatically tries to update the local
copy with fresh attribute data. If updating is impossible, the old
local data remains in place and the next operation fails, returning
the rpc_s_name_service_unavailable status code.
The scope of a handle's expiration age is a single series of RPC NSI
next operations. The rpc_ns_mgmt_handle_set_exp_age routine operates
as follows:
1. An RPC NSI begin operation, such as the one that
rpc_ns_group_mbr_inq_begin performs, creates a name service
handle.
2. A call to rpc_ns_mgmt_handle_set_exp_age creates an expiration
age for the handle.
3. A series of corresponding RPC NSI next operations for the name
service handle uses the handle's expiration age.
4. A corresponding RPC NSI done operation for the name service
handle deletes both the handle and its expiration age.
Cautions
Use this routine with extreme caution.
Setting the handle's expiration age to a small value causes the RPC
NSI next operations to frequently update local data for any name
service attribute requested by your application. For example, setting
the expiration age to 0 (zero) forces the next operation to update
local data for the name service attribute requested by your
application. Therefore, setting a small expiration age for a name
service handle can create performance problems for your application.
Also, if your application is using a remote server with the name
service database, a small expiration age can adversely affect network
performance for all applications.
Limit the use of this routine to the following types of situations:
o When you must always get accurate name service data.
For example, during management operations to update a profile,
you might need to always see the profile's current contents. In
this case, before beginning to inquire about a profile, your
application must call rpc_ns_mgmt_handle_set_exp_age and specify
0 (zero) for the expiration_age parameter.
o When a request using the default expiration age fails, and your
application needs to retry the operation.
For example, a client application using import must first try to
obtain bindings using the application's default expiration age.
However, sometimes the import-next operation returns either no
binding handles or an insufficient number of them. In this case,
the client can retry the import operation and, after
rpc_ns_binding_import_begin terminates, include a call to
rpc_ns_mgmt_handle_set_exp_age that specifies 0 (zero) for the
expiration_age parameter. When the client calls the import-next
routine again, the small expiration age for the name service
handle causes the import-next operation to update the local
attribute data.
Related Information
Routines:
rpc_ns_binding_import_begin
rpc_ns_binding_lookup_begin
rpc_ns_group_mbr_inq_begin
rpc_ns_mgmt_inq_exp_age
rpc_ns_mgmt_set_exp_age
rpc_ns_profile_elt_inq_begin
ΓòÉΓòÉΓòÉ 5.8.88. rpc_ns_mgmt_inq_exp_age ΓòÉΓòÉΓòÉ
Purpose
Returns the application's global expiration age for local copies of
name service data. This routine is used by client, server, or
management applications.
Format
#include <dce/rpc.h>
void rpc_ns_mgmt_inq_exp_age(
unsigned32 *expiration_age,
unsigned32 *status);
Parameters
Output
expiration_age Returns the default expiration age (in seconds). All
the RPC Name Service Interface (NSI) read operations
(all the next operations) use this value.
status Returns the status code from this routine. On
successful completion, the routine returns rpc_s_ok.
Otherwise, it returns an error.
Usage
The rpc_ns_mgmt_inq_exp_age routine returns the global expiration age
that the application is using. The expiration_age parameter
represents the amount of time, in seconds, that a local copy of data
from a name service attribute can exist before a request from the
application for the attribute requires updating the local copy. When
an application begins running, the RPC runtime specifies a random
value of between 8 and 12 hours as the default expiration age. The
default is global to the application.
The RPC NSI next operations, which read data from name service
attributes, use an expiration age. A next operation normally starts
by looking for a local copy of the attribute data that an application
requests. In the absence of a local copy, the next operation creates
one with fresh attribute data from the name service database. If a
local copy already exists, the operation compares its actual age to
the expiration age being used by the application. If the actual age
exceeds the expiration age, the operation automatically tries to
update the local copy with fresh attribute data from the name service
database. If updating is impossible, the old local data remains in
place and the next operation fails, returning the
rpc_s_name_service_unavailable status code.
Applications normally use only the default expiration age. For
special cases, an application can substitute a user-supplied global
expiration age for the default by calling rpc_ns_mgmt_set_exp_age.
The rpc_ns_mgmt_inq_exp_age routine returns the current global
expiration age, whether it is a default or a user-supplied value.
An application can also override the global expiration age
temporarily by calling rpc_ns_mgmt_handle_set_exp_age.
Related Information
Routines:
rpc_ns_mgmt_handle_set_exp_age
rpc_ns_mgmt_set_exp_age
ΓòÉΓòÉΓòÉ 5.8.89. rpc_ns_mgmt_read_codesets ΓòÉΓòÉΓòÉ
Purpose
Reads the code sets attribute associated with an RPC server entry in
the name service database. This routine is used by client
applications.
Format
#include <dce/rpc.h>
void rpc_ns_mgmt_read_codesets(
unsigned32 entry_name_syntax,
unsigned_char_t *entry_name,
rpc_codeset_mgmt_p_t *code_sets_array,
error_status_t *status);
Parameters
Input
entry_name_syntax An integer value that specifies the syntax of the
entry_name parameter.
To use the syntax specified in the
RPC_DEFAULT_ENTRY_SYNTAX environment variable, provide
rpc_c_ns_syntax_default.
entry_name Specifies the name of the RPC server entry in the name
service database from which to read the code sets
attribute. The name can be either the global or
cell-relative name.
Output
code_sets_array A code sets array that specifies the code sets that
the RPC server supports.
status Returns the status code from this routine. On
successful completion, the routine returns rpc_s_ok.
Otherwise, it returns one of the following errors:
rpc_s_invalid_name_syntax
rpc_s_mgmt_bad_type
rpc_s_name_service_unavailable
rpc_s_no_permission
rpc_s_incomplete_name
rpc_s_no_memory
Usage
The rpc_ns_mgmt_read_codesets routine belongs to a set of DCE RPC
routines for character and code set interoperability. These routines
permit client and server applications to transfer international
character data in a heterogeneous character set and code sets
environment.
The rpc_ns_mgmt_read_codesets routine reads the code sets attribute
associated with an RPC server entry in the name service database. The
routine takes the name of an RPC server entry and returns a code sets
array that corresponds to the code sets that this RPC server
supports.
Client applications use the rpc_ns_mgmt_read_codesets routine to
retrieve a server's supported code sets in order to evaluate them
against the code sets that the client supports. Client applications
that use the evaluation routines rpc_cs_eval_with_universal and
rpc_cs_eval_without_universal do not need to call this routine
explicitly, because these code sets evaluation routines call it on
the client's behalf. Application developers who are writing their own
character and code set evaluation routines may need to include
rpc_ns_mgmt_read_codesets in their user-written evaluation routines.
Permissions Required
You need read permission to the target RPC server entry (which is a
CDS object).
Related Information
Routines:
dce_cs_rgy_to_loc
dce_cs_loc_to_rgy
rpc_ns_mgmt_free_codesets
rpc_ns_mgmt_remove_attribute
rpc_ns_mgmt_set_attribute
rpc_rgy_get_codesets
rpc_rgy_get_max_bytes
ΓòÉΓòÉΓòÉ 5.8.90. rpc_ns_mgmt_remove_attribute ΓòÉΓòÉΓòÉ
Purpose
Removes an attribute from an RPC server entry in the name service
database. This routine is used mainly by server applications, but can
also be used by management applications.
Format
#include <dce/rpc.h>
#include <dce/nsattrid.h>
void rpc_ns_mgmt_remove_attribute(
unsigned32 entry_name_syntax,
unsigned_char_t *entry_name,
uuid_t *attr_type,
error_status_t *status);
Parameters
Input
entry_name_syntax An integer value that specifies the syntax of the
entry_name parameter.
To use the syntax specified in the
RPC_DEFAULT_ENTRY_SYNTAX environment variable, provide
rpc_c_ns_syntax_default.
entry_name Specifies the name of the RPC server entry in the name
service database from which the attribute will be
removed. The name can be either the global or
cell-relative name. If you are using this routine to
remove a code sets attribute from an RPC server entry
in the Cell Directory Service database, this parameter
specifies the CDS name of the server entry that
contains the code sets attribute to be removed.
attr_type A UUID that specifies the attribute type. For DCE 1.1,
this value must be rpc_c_attr_codesets.
Output
status Returns the status code from this routine. On
successful completion, the routine returns rpc_s_ok.
Otherwise, it returns one of the following errors:
rpc_s_entry_not_found The routine cannot find the
RPC server entry specified in the
routine in the name service
database.
rpc_s_incomplete_name The routine cannot expand
the RPC server entry name specified
in the routine.
rpc_s_invalid_name_syntax The name syntax
specified in the routine is not
valid.
rpc_s_mgmt_bad_type The attribute type specified
in the routine does not match that
of the attribute to be removed from
the name service database.
rpc_s_name_service_unavailable The routine was
unable to communicate with the name
service.
rpc_s_no_ns_permission The routine's caller does
not have the proper permission for
an NSI operation.
Usage
The rpc_ns_mgmt_remove_attribute routine belongs to a set of DCE RPC
routines for use by client and server applications that are
transferring international character data in a heterogeneous
character set and code sets environment.
The rpc_ns_mgmt_remove_attribute routine is designed to be a generic
routine for removing an attribute from an RPC server entry in the
name service database. The routine removes the attribute from the
specified RPC server entry in the name service database. The routine
does not remove the RPC server entry.
For DCE 1.1, you use rpc_ns_mgmt_remove_attribute in your application
server initialization routine or signal handling routine to remove a
code sets attribute from the server's entry in the Cell Directory
Service database as part of the server cleanup procedure carried out
prior to the server's termination.
A management application can call rpc_ns_mgmt_remove_attribute to
remove an attribute from an RPC server entry in the name service
database on behalf of an application that does not itself have the
necessary name service permissions to remove one.
Permissions Required
You need write permission to the target RPC server entry (which is a
CDS object).
Related Information
Routines:
rpc_ns_mgmt_read_codesets
rpc_ns_mgmt_set_attribute
rpc_rgy_get_codesets
ΓòÉΓòÉΓòÉ 5.8.91. rpc_ns_mgmt_set_attribute ΓòÉΓòÉΓòÉ
Purpose
Adds an attribute to an RPC server entry in the name service
database. This routine is used mainly by server applications, but can
also be used by management applications.
Format
#include <dce/rpc.h>
#include <dce/nsattrid.h>
void rpc_ns_mgmt_set_attribute(
unsigned32 entry_name_syntax,
unsigned_char_t *entry_name,
uuid_t *attr_type,
void *attr_value,
error_status_t *status);
Parameters
Input
entry_name_syntax An integer value that specifies the syntax of the
entry_name parameter.
To use the syntax specified in the
RPC_DEFAULT_ENTRY_SYNTAX environment variable, provide
rpc_c_ns_syntax_default.
entry_name Specifies the name of the RPC server entry in the name
service database with which the attribute is
associated. The name can be either the global or
cell-relative name. If you are using this routine to
add a code sets attribute to an RPC server entry in the
name service database, this parameter specifies the
name of the server entry with which the code sets
attribute is associated.
attr_type A UUID that specifies the attribute type. For DCE 1.1,
this value must be rpc_c_attr_codesets.
attr_val An opaque data structure that specifies the attribute
value to be stored in the name service database. If you
are using this routine to add a code sets attribute to
an RPC server entry, you must cast the representation
of the code set data from the data type
rpc_codeset_mgmt_p_t to the data type void*.
Output
status Returns the status code from this routine. On
successful completion, the routine returns rpc_s_ok.
Otherwise, it returns one of the following errors:
rpc_s_invalid_name_syntax The name syntax
specified in the routine is not
valid.
rpc_s_mgmt_bad_type The attribute type specified
in the routine does not match that
of the attribute to be added to the
name service database.
rpc_s_no_memory The routine was unable to allocate
memory to encode the value.
rpc_s_name_service_unavailable The routine was
unable to communicate with the name
service.
rpc_s_no_ns_permission The routine's caller does
not have the proper permission for
an NSI operation.
Usage
The rpc_ns_mgmt_set_attribute routine belongs to a set of DCE RPC
routines for use by client and server applications that are
transferring international character data in a heterogeneous
character set and code sets environment.
The rpc_ns_mgmt_set_attribute routine is designed to be a generic
routine for adding an attribute to an RPC server entry in the name
service database. The routine takes an attribute type and a pointer
to the value, and stores the attribute value in the name service
database.
For DCE 1.1, you use rpc_ns_mgmt_set_attribute in your application
server initialization routine to add a code sets attribute to the
server's entry in the Cell Directory Service database (which the
initialization routine has created with the rpc_ns_binding_export
routine). Because CDS stores integer values in little-endian format,
the rpc_ns_mgmt_set_attribute routine also encodes the code sets
attribute value into an endian-safe format before storing it in the
name service database.
A management application can call rpc_ns_mgmt_set_attribute to add an
attribute to an RPC server entry in the name service database on
behalf of an application that does not itself have the necessary name
service permissions to add one.
Permissions Required
You need both read permission and write permission to the target RPC
server entry (which is a CDS object). You also need insert permission
to the parent directory.
Related Information
Routines:
rpc_ns_mgmt_read_codesets
rpc_ns_mgmt_remove_attribute
rpc_rgy_get_codesets
ΓòÉΓòÉΓòÉ 5.8.92. rpc_ns_mgmt_set_exp_age ΓòÉΓòÉΓòÉ
Purpose
Modifies the application's global expiration age for local copies of
name service data. This routine is used by client, server, or
management applications.
Format
#include <dce/rpc.h>
void rpc_ns_mgmt_set_exp_age(
unsigned32 expiration_age,
unsigned32 *status);
Parameters
Input
expiration_age An integer value that specifies the default expiration
age, in seconds, for local name service data. This
expiration age applies to all RPC name service
interface (NSI) read operations (all the next
operations).
An expiration age of 0 (zero) causes an immediate
update of the local name service data.
To reset the expiration age to an RPC-assigned random
value between 8 and 12 hours, specify a value of
rpc_c_ns_default_exp_age.
Output
status Returns the status code from this routine. On
successful completion, the routine returns rpc_s_ok.
Otherwise, it returns an error.
Usage
The rpc_ns_mgmt_set_exp_age routine modifies the global expiration
age that the application is using. The expiration age parameter
represents the amount of time, in seconds, that a local copy of data
from a name service attribute can exist before a request from the
application for the attribute requires updating the local copy. When
an application begins running, the RPC runtime specifies a random
value of between 8 and 12 hours as the default expiration age. The
default is global to the application.
Normally, you should avoid using this routine; instead, rely on the
default expiration age.
The RPC NSI next operations, which read data from name service
attributes, use an expiration age. A next operation normally starts
by looking for a local copy of the attribute data that an application
requests. In the absence of a local copy, the next operation creates
one with fresh attribute data from the name service database. If a
local copy already exists, the operation compares its actual age to
the expiration age being used by the application. If the actual age
exceeds the expiration age, the operation automatically tries to
update the local copy with fresh attribute data from the name service
database. If updating is impossible, the old local data remains in
place and the next operation fails, returning the
rpc_s_name_service_unavailable status code.
Cautions
Use this routine with extreme caution.
Setting the expiration age to a small value causes the RPC NSI next
operations to frequently update local data for any name service
attribute that your application requests. For example, setting the
expiration age to 0 (zero) forces all next operations to update local
data for the name service attribute that your application has
requested. Therefore, setting small expiration ages can create
performance problems for your application. Also, if your application
is using a remote server with the name service database, a small
expiration age can adversely affect network performance for all
applications.
Related Information
Routines:
rpc_ns_mgmt_handle_set_exp_age
rpc_ns_mgmt_inq_exp_age
ΓòÉΓòÉΓòÉ 5.8.93. rpc_ns_profile_delete ΓòÉΓòÉΓòÉ
Purpose
Deletes a profile attribute. This routine is used by client, server,
or management applications.
Format
#include <dce/rpc.h>
void rpc_ns_profile_delete(
unsigned32 profile_name_syntax,
unsigned_char_t *profile_name,
unsigned32 *status);
Parameters
Input
profile_name_syntax An integer value that specifies the syntax of the
profile_name parameter.
To use the syntax specified in the
RPC_DEFAULT_ENTRY_SYNTAX environment variable, provide
rpc_c_ns_syntax_default.
profile_name Specifies the name of the profile to delete. This can
be either the global or the cell-relative name.
Output
status Returns the status code from this routine. On
successful completion, the routine returns rpc_s_ok.
Otherwise, it returns one of the following errors:
rpc_s_entry_not_found The name service entry was
not found.
rpc_s_incomplete_name Incomplete name.
rpc_s_invalid_name_syntax The name syntax is not
valid.
rpc_s_name_service_unavailable The name service is
unavailable.
rpc_s_no_ns_permission There is no permission for
the name service operation.
rpc_s_unsupported_name_syntax Unsupported name
syntax.
Usage
The rpc_ns_profile_delete routine deletes the profile attribute from
the specified entry in the name service database (the profile_name
parameter).
Neither the specified entry nor the entries included as members in
each profile element are deleted.
Use this routine cautiously; deleting a profile can break a hierarchy
of profiles.
Permissions Required
You need write permission to the CDS object entry (the target profile
entry).
Related Information
Routines:
rpc_ns_profile_elt_add
rpc_ns_profile_elt_remove
ΓòÉΓòÉΓòÉ 5.8.94. rpc_ns_profile_elt_add ΓòÉΓòÉΓòÉ
Purpose
Adds an element to a profile. If necessary, this routine creates the
profile entry. This routine is used by client, server, or management
applications.
Format
#include <dce/rpc.h>
void rpc_ns_profile_elt_add(
unsigned32 profile_name_syntax,
unsigned_char_t *profile_name,
rpc_if_id_t *if_id,
unsigned32 member_name_syntax,
unsigned_char_t *member_name,
unsigned32 priority,
unsigned_char_t *annotation,
unsigned32 *status);
Parameters
Input
profile_name_syntax An integer value that specifies the syntax of the
profile_name parameter.
To use the syntax specified in the
RPC_DEFAULT_ENTRY_SYNTAX environment variable, provide
rpc_c_ns_syntax_default.
profile_name Specifies the RPC profile that receives a new element.
This can be either the global or the cell-relative
name.
if_id Specifies the interface identifier of the new profile
element. To add or replace the default profile element,
specify NULL.
member_name_syntax An integer value that specifies the syntax of the
member_name parameter.
To use the syntax specified in the
RPC_DEFAULT_ENTRY_SYNTAX environment variable, provide
rpc_c_ns_syntax_default.
member_name Specifies the entry in the name service database to
include in the new profile element. This can be either
the global or the cell-relative name.
priority An integer value (from 0 to 7) that specifies the
relative priority for using the new profile element
during the import and lookup operations. A value of 0
(zero) is the highest priority. A value of 7 is the
lowest priority. Two or more elements can have the same
priority.
When adding the default profile member, use a value of
0 (zero).
annotation Specifies an annotation string that is stored as part
of the new profile element. The string can contain up
to 17 characters. Specify NULL or the string \0 if
there is no annotation string.
The string is used by applications for informational
purposes only. For example, an application can use this
string to store the interface name string (specified in
the IDL file).
DCE RPC does not use this string during lookup or
import operations, or for enumerating profile elements.
Output
status Returns the status code from this routine. On
successful completion, the routine returns rpc_s_ok.
Otherwise, it returns one of the following errors:
rpc_s_class_version_mismatch RPC class version
mismatch.
rpc_s_incomplete_name Incomplete name.
rpc_s_invalid_name_syntax The name syntax is not
valid.
rpc_s_invalid_priority The profile element
priority is not valid.
rpc_s_name_service_unavailable The name service is
unavailable.
rpc_s_no_ns_permission There is no permission for
the name service operation.
rpc_s_unsupported_name_syntax Unsupported name
syntax.
Usage
The rpc_ns_profile_elt_add routine adds an element to the profile
attribute of the entry in the name service database specified by the
profile_name parameter.
If the profile_name entry does not exist, this routine creates the
entry with a profile attribute and adds the profile element specified
by the if_id, member_name, priority, and annotation parameters. In
this case, the application must have permission to create the entry.
Otherwise, a management application with the necessary permissions
creates the entry by calling rpc_ns_mgmt_entry_create before the
application is run.
If an element with the specified member name and interface identifier
are already in the profile, this routine updates the element's
priority and annotation string using the values provided in the
priority and annotation parameters.
An application can add the entry in the member_name parameter to a
profile before it creates the entry itself.
Permissions Required
You need both read permission and write permission to the CDS object
entry (the target profile entry). If the entry does not exist, you
also need insert permission to the parent directory.
Related Information
Routines:
rpc_if_inq_id
rpc_ns_mgmt_entry_create
rpc_ns_profile_elt_remove
ΓòÉΓòÉΓòÉ 5.8.95. rpc_ns_profile_elt_inq_begin ΓòÉΓòÉΓòÉ
Purpose
Creates an inquiry context for viewing the elements in a profile.
This routine is used by client, server, or management applications.
Format
#include <dce/rpc.h>
void rpc_ns_profile_elt_inq_begin(
unsigned32 profile_name_syntax,
unsigned_char_t *profile_name,
unsigned32 inquiry_type,
rpc_if_id_t *if_id,
unsigned32 vers_option,
unsigned32 member_name_syntax,
unsigned_char_t *member_name,
rpc_ns_handle_t *inquiry_context,
unsigned32 *status);
Parameters
Input
profile_name_syntax An integer value that specifies the syntax of the
profile_name parameter.
To use the syntax specified in the
RPC_DEFAULT_ENTRY_SYNTAX environment variable, provide
rpc_c_ns_syntax_default.
profile_name Specifies the name of the profile to view. This can be
either the global or the cell-relative name.
inquiry_type An integer value that specifies the type of inquiry to
perform on the profile. The following list describes
the valid inquiry types:
Value Description
rpc_c_profile_default_elt Searches the profile for
the default profile element,
if any. The if_id,
vers_option, and member_name
parameters are ignored.
rpc_c_profile_all_elts Returns every element from
the profile. The if_id,
vers_option, and member_name
parameters are ignored.
rpc_c_profile_match_by_if Searches the profile for
those elements that contain
the interface identifier
specified by the if_id and
vers_option values. The
member_name parameter is
ignored.
rpc_c_profile_match_by_mbr Searches the profile
for those elements that
contain the member name
specified by the member_name
parameter. The if_id and
vers_option parameters are
ignored.
rpc_c_profile_match_by_both Searches the profile
for those elements that
contain the interface
identifier and member name
specified by the if_id,
vers_option, and member_name
parameters.
if_id Specifies the interface identifier of the profile
elements to be returned by rpc_ns_profile_elt_inq_next.
This parameter is used only when specifying a value of
rpc_c_profile_match_by_if or
rpc_c_profile_match_by_both for the inquiry_type
parameter. Otherwise, this parameter is ignored and you
can specify the value NULL.
vers_option Specifies how the rpc_ns_profile_elt_inq_next routine
uses the if_id parameter.
This parameter is used only when specifying a value of
either rpc_c_profile_match_by_if or
rpc_c_profile_match_by_both for the inquiry_type
parameter. Otherwise, this parameter is ignored and you
can specify the value 0 (zero).
The following are the valid values for this parameter:
Value Description
rpc_c_vers_all Returns profile elements that
offer the specified interface
UUID, regardless of the version
numbers. For this value, specify
0 (zero) for both the major and
minor versions in the if_id
parameter.
rpc_c_vers_compatible Returns profile elements
that offer the same major version
of the specified interface UUID
and a minor version greater than
or equal to the minor version of
the specified interface UUID.
rpc_c_vers_exact Returns profile elements that
offer the specified version of
the specified interface UUID.
rpc_c_vers_major_only Returns profile elements
that offer the same major version
of the specified interface UUID
(ignores the minor version). For
this value, specify 0 (zero) for
the minor version in the if_id
parameter.
rpc_c_vers_upto Returns profile elements that
offer a version of the specified
interface UUID less than or equal
to the specified major and minor
version. (For example, if the
if_id parameter contains V2.0 and
the profile contains elements
with the versions V1.3, V2.0, and
V2.1, rpc_ns_profile_elt_inq_next
returns the elements with V1.3
and V2.0.)
member_name_syntax An integer value that specifies the syntax of the
member_name parameter in this routine and the syntax of
the member_name parameter in
rpc_ns_profile_elt_inq_next.
To use the syntax specified in the
RPC_DEFAULT_ENTRY_SYNTAX environment variable, provide
rpc_c_ns_syntax_default.
member_name Specifies the member name that
rpc_ns_profile_elt_inq_next looks for in profile
elements. This can be either the global or the
cell-relative name.
This parameter is used only when specifying a value of
rpc_c_profile_match_by_mbr or
rpc_c_profile_match_by_both for the inquiry_type
parameter. Otherwise, this parameter is ignored and you
specify the value NULL.
Output
inquiry_context Returns a name service handle for use with
rpc_ns_profile_elt_inq_next and
rpc_ns_profile_elt_inq_done.
status Returns the status code from this routine. On
successful completion, the routine returns rpc_s_ok.
Otherwise, it returns one of the following errors:
rpc_s_incomplete_name Incomplete name.
rpc_s_invalid_inquiry_type The inquiry type is not
valid.
rpc_s_invalid_name_syntax The name syntax is not
valid.
rpc_s_invalid_vers_option The version option is
not valid.
rpc_s_unsupported_name_syntax Unsupported name
syntax.
Usage
The rpc_ns_profile_elt_inq_begin routine creates an inquiry context
for viewing the elements in a profile.
Using the inquiry_type and vers_option parameters, an application
specifies which of the following profile elements are returned from
calls to rpc_ns_profile_elt_inq_next:
o The default element
o All elements
o Those elements with the specified interface identifier
o Those elements with the specified member name
o Those elements with both the specified interface identifier and
member name.
Before calling rpc_ns_profile_elt_inq_next, the application must
first call this routine to create an inquiry context.
When the application finishes viewing the profile elements, it calls
rpc_ns_profile_elt_inq_done to delete the inquiry context.
Related Information
Routines:
rpc_if_inq_id
rpc_ns_mgmt_handle_set_exp_age
rpc_ns_profile_elt_inq_done
rpc_ns_profile_elt_inq_next
ΓòÉΓòÉΓòÉ 5.8.96. rpc_ns_profile_elt_inq_done ΓòÉΓòÉΓòÉ
Purpose
Deletes the inquiry context for a profile. This routine is used by
client, server, or management applications.
Format
#include <dce/rpc.h>
void rpc_ns_profile_elt_inq_done(
rpc_ns_handle_t *inquiry_context,
unsigned32 *status);
Parameters
Input/Output
inquiry_context Specifies the name service handle to delete. (A name
service handle is created by calling
rpc_ns_profile_elt_inq_begin.) Returns the value NULL.
Output
status Returns the status code from this routine. On
successful completion, the routine returns rpc_s_ok.
Otherwise, it returns rpc_s_invalid_ns_handle, which
indicates that the name service handle is not valid.
Usage
The rpc_ns_profile_elt_inq_done routine deletes an inquiry context
created by calling rpc_ns_profile_elt_inq_begin.
An application calls this routine after viewing profile elements
using rpc_ns_profile_elt_inq_next.
Related Information
Routines:
rpc_ns_profile_elt_inq_begin
rpc_ns_profile_elt_inq_next
ΓòÉΓòÉΓòÉ 5.8.97. rpc_ns_profile_elt_inq_next ΓòÉΓòÉΓòÉ
Purpose
Returns one element at a time from a profile. This routine is used by
client, server, or management applications.
Format
#include <dce/rpc.h>
void rpc_ns_profile_elt_inq_next(
rpc_ns_handle_t inquiry_context,
rpc_if_id_t *if_id,
unsigned_char_t **member_name,
unsigned32 *priority,
unsigned_char_t **annotation,
unsigned32 *status);
Parameters
Input
inquiry_context Specifies a name service handle. This handle is
returned from the rpc_ns_profile_elt_inq_begin routine.
Output
if_id Returns the interface identifier of the profile
element.
member_name Returns a pointer to the profile element's member name.
The name is a global name.
The syntax of the returned name is specified by the
member_name_syntax parameter in the
rpc_ns_profile_elt_inq_begin.
Specify NULL to prevent the routine from returning this
parameter. In this case the application does not call
rpc_string_free.
priority Returns the profile element priority.
annotation Returns the annotation string for the profile element.
If there is no annotation string in the profile
element, the string \0 is returned.
Specify NULL to prevent the routine from returning this
parameter. In this case the application does not need
to call rpc_string_free.
status Returns the status code from this routine. On
successful completion, the routine returns rpc_s_ok.
Otherwise, it returns one of the following errors:
rpc_s_class_version_mismatch RPC class version
mismatch.
rpc_s_entry_not_found The name service entry
was not found.
rpc_s_incomplete_name Incomplete name.
rpc_s_invalid_ns_handle The name service handle
is not valid.
rpc_s_name_service_unavailable The name service is
unavailable.
rpc_s_no_more_elements No more elements.
rpc_s_no_ns_permission There is no permission
for the name service
operation.
rpc_s_not_rpc_entry Not an RPC entry.
Usage
The rpc_ns_profile_elt_inq_next routine returns one element from the
profile specified by the profile_name parameter in
rpc_ns_profile_elt_inq_begin.
The selection criteria for the element returned are based on the
inquiry_type parameter in rpc_ns_profile_elt_inq_begin. The
rpc_ns_profile_elt_inq_next routine returns all the components
(interface identifier, member name, priority, annotation string) of a
profile element.
An application can view all the selected profile entries by
repeatedly calling rpc_ns_profile_elt_inq_next. When all the elements
have been viewed, this routine returns an rpc_s_no_more_elements
status code. The returned elements are unordered.
On each call to this routine that returns a profile element, the DCE
RPC runtime allocates memory for the returned member_name (which
points to a global name) and annotation strings. The application is
responsible for calling rpc_string_free for each returned member_name
and annotation string.
After viewing the profile elements, the application must call
rpc_ns_profile_elt_inq_done to delete the inquiry context.
Permissions Required
You need read permission to the CDS object entry (the target profile
entry).
Related Information
Routines:
rpc_ns_profile_elt_inq_begin
rpc_ns_profile_elt_inq_done
rpc_string_free
ΓòÉΓòÉΓòÉ 5.8.98. rpc_ns_profile_elt_remove ΓòÉΓòÉΓòÉ
Purpose
Removes an element from a profile. This routine is used by client,
server, or management applications.
Format
#include <dce/rpc.h>
void rpc_ns_profile_elt_remove(
unsigned32 profile_name_syntax,
unsigned_char_t *profile_name,
rpc_if_id_t *if_id,
unsigned32 member_name_syntax,
unsigned_char_t *member_name,
unsigned32 *status);
Parameters
Input
profile_name_syntax An integer value that specifies the syntax of the
profile_name parameter. To use the syntax specified in
the RPC_DEFAULT_ENTRY_SYNTAX environment variable,
provide rpc_c_ns_syntax_default.
profile_name Specifies the profile from which to remove an element.
This can be either the global or the cell-relative
name.
if_id Specifies the interface identifier of the profile
element to be removed.
Specify NULL to remove the default profile member.
member_name_syntax An integer value that specifies the syntax of the
member_name parameter. To use the syntax specified in
the RPC_DEFAULT_ENTRY_SYNTAX environment variable,
provide rpc_c_ns_syntax_default.
member_name Specifies the name service entry name in the profile
element to remove. This can be either the global or the
cell-relative name.
Output
status Returns the status code from this routine. On
successful completion, the routine returns rpc_s_ok.
Otherwise, it returns one of the following errors:
rpc_s_entry_not_found The name service entry was
not found.
rpc_s_incomplete_name Incomplete name.
rpc_s_invalid_name_syntax The name syntax is not
valid.
rpc_s_name_service_unavailable The name service is
unavailable.
rpc_s_no_ns_permission There is no permission for
the name service operation.
rpc_s_profile_element_not_found The profile
element was not found.
rpc_s_unsupported_name_syntax Unsupported name
syntax.
Usage
The rpc_ns_profile_elt_remove routine removes a profile element from
the profile specified by profile_name. Unless if_id is NULL, the
member_name parameter and the if_id parameter must match the
corresponding profile element attributes exactly for an element to be
removed. When if_id is NULL, the default profile element is removed,
and the member_name parameter is ignored.
The routine removes the reference to the entry specified by
(member_name) from the profile; it does not delete the entry itself.
Use this routine cautiously; removing elements from a profile can
break a hierarchy of profiles.
Permissions Required
You need both read permission and write permission to the CDS object
entry (the target profile entry).
Related Information
Routines:
rpc_ns_profile_delete
rpc_ns_profile_elt_add
ΓòÉΓòÉΓòÉ 5.8.99. rpc_object_inq_type ΓòÉΓòÉΓòÉ
Purpose
Returns the type of an object. This routine is used by server
applications.
Format
#include <dce/rpc.h>
void rpc_object_inq_type(
uuid_t *obj_uuid,
uuid_t *type_uuid,
unsigned32 *status);
Parameters
Input
obj_uuid Specifies the object UUID whose associated type UUID is
returned. Supply NULL to specify a nil UUID for this
parameter.
Output
type_uuid Returns the type UUID corresponding to the object UUID
supplied in the obj_uuid parameter.
Specifying NULL here prevents the return of a type
UUID. An application, by specifying NULL here, can
determine from the value returned in the status
parameter whether obj_uuid is registered. This
determination occurs without the application specifying
an output type UUID variable.
status Returns the status code from this routine. On
successful completion, the routine returns rpc_s_ok.
Otherwise, it returns one of the following errors:
rpc_s_object_not_found The object was not found.
uuid_s_bad_version The UUID version is not valid.
Usage
A server application calls rpc_object_inq_type to obtain the type
UUID of an object.
If the object is registered with the RPC runtime using
rpc_object_set_type, the registered type is returned.
Optionally, an application can privately maintain an object and type
registration. In this case, if the application provides an object
inquiry routine the RPC runtime uses that routine to determine the
object type.
The following table summarizes how rpc_object_inq_type obtains the
returned type UUID.
ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
Γöé Table 9. Rules for Returning an Object's Type Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé Was object UUID reg- Γöé Was an object inquiry Γöé Return Value Γöé
Γöé istered (using Γöé routine registered Γöé Γöé
Γöé rpc_object_set_type)? Γöé (using Γöé Γöé
Γöé Γöé rpc_object_set_inq_fn)Γöé Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé yes Γöé ignored Γöé Return the object's Γöé
Γöé Γöé Γöé registered type Γöé
Γöé Γöé Γöé UUID. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé no Γöé yes Γöé Return the type UUID Γöé
Γöé Γöé Γöé returned from Γöé
Γöé Γöé Γöé calling the inquiry Γöé
Γöé Γöé Γöé routine. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé no Γöé no Γöé Return the nil UUID. Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
Related Information
Routines:
rpc_object_set_inq_fn
rpc_object_set_type
ΓòÉΓòÉΓòÉ 5.8.100. rpc_object_set_inq_fn ΓòÉΓòÉΓòÉ
Purpose
Registers an object inquiry routine. This routine is used by server
applications.
Format
#include <dce/rpc.h>
void rpc_object_set_inq_fn(
rpc_object_inq_fn_t inquiry_fn,
unsigned32 *status);
Parameters
Input
inquiry_fn Specifies a pointer to an object type inquiry routine.
When an application calls rpc_object_inq_type and the
RPC runtime finds that the specified object is not
registered, the runtime automatically calls the
registered inquiry routine to determine the object's
type. Specify NULL to remove a previously set inquiry
routine.
The following C language definition for
rpc_object_inq_fn_t illustrates the prototype for this
routine:
typedef void (*rpc_object_inq_fn_t)
(
uuid_t *object_uuid, /* in */
uuid_t *type_uuid, /* out */
unsigned32 *status /* out */
);
The returned type_uuid and status values are returned
as the output parameters from rpc_object_inq_type.
If you specify NULL, rpc_object_set_inq_fn unregisters
(that is, removes) a previously registered object type
inquiry routine.
Output
status Returns the status code from this routine. On
successful completion, the routine returns rpc_s_ok.
Otherwise, it returns an error.
Usage
A server application calls rpc_object_set_inq_fn to specify a routine
to determine the object type. If an application privately maintains
object and type registrations, the specified inquiry routine returns
the type UUID of an object from that registration.
The RPC runtime automatically calls the inquiry routine when the
application calls rpc_object_inq_type and the object was not
previously registered by rpc_object_set_type. The RPC runtime also
automatically calls the inquiry routine for every remote procedure
call it receives if the object was not previously registered.
Cautions
Use this routine with caution. When the RPC runtime automatically
calls this routine in response to a received remote procedure call,
the inquiry routine can be called from the context of runtime
internal threads with runtime internal locks held. The inquiry
routine should not block or at least not block for long (for example,
the inquiry routine should not perform a remote procedure call).
Also, the inquiry routine must not unwind because of an exception. In
general, the inquiry routine should not call back into the RPC
runtime. It is legal to call rpc_object_set_type or any of the
uuid_xxx routines. Failure to comply with these restrictions will
result in undefined behavior.
Related Information
Routines:
rpc_object_inq_type
rpc_object_set_type
ΓòÉΓòÉΓòÉ 5.8.101. rpc_object_set_type ΓòÉΓòÉΓòÉ
Purpose
Registers the type of an object with the RPC runtime. This routine is
used by server applications.
Format
#include <dce/rpc.h>
void rpc_object_set_type(
uuid_t *obj_uuid,
uuid_t *type_uuid,
unsigned32 *status);
Parameters
Input
obj_uuid Specifies an object UUID to associate with the type
UUID in the type_uuid parameter. Do not specify NULL or
a nil UUID.
type_uuid Specifies the type UUID of the obj_uuid parameter.
Specify an parameter value of NULL or a nil UUID to
reset the object type to the default association of
object UUID/nil type UUID.
Output
status Returns the status code from this routine. On
successful completion, the routine returns rpc_s_ok.
Otherwise, it returns one of the following errors:
rpc_s_already_registered The object is already
registered.
rpc_s_invalid_object The object is not valid.
uuid_s_bad_version Bad UUID version.
Usage
The rpc_object_set_type routine assigns a type UUID to an object
UUID.
By default, the RPC runtime assumes that the type of all objects is
nil. A server program that contains one implementation of an
interface (one manager entry point vector) does not need to call this
routine, provided that the server registered the interface with the
nil type UUID. See the rpc_server_register_ifroutine.
A server program that contains multiple implementations of an
interface (multiple manager entry point vectors; that is, multiple
type UUIDs) calls this routine once for each object UUID the server
offers. Associating each object with a type UUID tells the RPC
runtime the manager entry point vector (interface implementation) to
use when the server receives a remote procedure call for a non-nil
object UUID.
The RPC runtime allows an application to set the type for an
unlimited number of objects.
To remove the association between an object UUID and its type UUID
(established by calling this routine), a server calls this routine
again and specifies the value NULL or a nil UUID for the type_uuid
parameter. This resets the association between an object UUID and
type UUID to the default.
A server cannot register a nil object UUID. The RPC runtime
automatically registers the nil object UUID with a nil type UUID.
Attempting to set the type of a nil object UUID results in the
routine's returning the status code rpc_s_invalid_object.
Servers that want to maintain their own object UUID to type UUID
mapping can use rpc_object_set_inq_fn in place of, or in addition to,
rpc_object_set_type.
Related Information
Routines:
rpc_object_set_inq_fn
rpc_server_register_if
ΓòÉΓòÉΓòÉ 5.8.102. rpc_protseq_vector_free ΓòÉΓòÉΓòÉ
Purpose
Frees the memory used by a vector and its protocol sequences. This
routine is used by client or server applications.
Format
#include <dce/rpc.h>
void rpc_protseq_vector_free(
rpc_protseq_vector_t **protseq_vector,
unsigned32 *status);
Parameters
Input/Output
protseq_vector Specifies the address of a pointer to a vector of
protocol sequences. On return the pointer is set to
NULL.
Output
status Returns the status code from this routine. On
successful completion, the routine returns rpc_s_ok.
Otherwise, it returns an error.
Usage
The rpc_protseq_vector_free routine frees the memory used to store a
vector of protocol sequences. The freed memory includes both the
protocol sequences and the vector itself.
Call rpc_network_inq_protseqs to obtain a vector of protocol
sequences. Follow a call to rpc_network_inq_protseqs with a call to
rpc_protseq_vector_free.
Related Information
Routines:
rpc_network_inq_protseqs
ΓòÉΓòÉΓòÉ 5.8.103. rpc_rgy_get_codesets ΓòÉΓòÉΓòÉ
Purpose
Gets supported code sets information from the local host. This
routine is used by client and server applications.
Format
#include <dce/rpc.h>
void rpc_rgy_get_codesets(
rpc_codeset_mgmt_p_t *code_sets_array,
error_status_t *status);
Parameters
Output
code_sets_array An integer array that specifies the code sets that
the client's or server's host environment supports.
Each array element is an integer value that uniquely
identifies one code set.
status Returns the status code from this routine. On
successful completion, the routine returns rpc_s_ok.
Otherwise, it returns one of the following errors:
dce_cs_c_cannot_open_file
dce_cs_c_cannot_read_file
rpc_s_no_memory
Usage
The rpc_rgy_get_codesets routine belongs to a set of DCE RPC routines
for use by client and server applications that are transferring
international character data in a heterogeneous character set and
code sets environment.
The rpc_rgy_get_codesets routine examines the locale environment of
the host on which the client or server process is running to
determine the local code set currently in use by the client or server
process and the set of supported code set conversion routines that
exist on the host into which the client or server process can convert
if necessary. It then reads the code sets registry on the local host
to retrieve the unique identifiers associated with these supported
code sets.
The routine returns a code sets array. The set of values returned in
this structure correspond to the process's local code set and the
code sets into which processes that run on this host can convert. The
array also contains, for each code set, the maximum number of bytes
that code set uses to encode one character (c_max_bytes).
Server applications use the rpc_rgy_get_codesets routine in their
initialization code to get their host's supported character and code
sets values in order to export them into the name service database
with rpc_ns_mgmt_set_attribute.
Client applications use the rpc_rgy_get_codesets routine during the
server binding selection process to retrieve the supported character
and code sets at their host in order to evaluate them against the
character and code sets that a server supports. Client applications
that use the evaluation routines rpc_cs_eval_with_universal and
rpc_cs_eval_without_universal do not need to call this routine
explicitly, because these code sets evaluation routines call it on
the client's behalf. Application developers who are writing their own
character and code set evaluation routines might need to include
rpc_rgy_get_codesets in their user-written evaluation routines.
Related Information
Commands:
csrc
Routines:
dce_cf_get_csrgy_filename
rpc_ns_mgmt_read_codesets
rpc_ns_mgmt_remove_attribute
rpc_ns_mgmt_set_attribute
ΓòÉΓòÉΓòÉ 5.8.104. rpc_rgy_get_max_bytes ΓòÉΓòÉΓòÉ
Purpose
Gets the maximum number of bytes that a code set uses to encode one
character from the code set registry on a host. This routine is used
by client and server applications.
Format
#include <dce/rpc.h>
void rpc_rgy_get_max_bytes(
unsigned32 rgy_code_set_value,
unsigned16 *rgy_max_bytes,
error_status_t *status);
Parameters
Input
rgy_code_set_value The registered hexadecimal value that uniquely
identifies the code set.
Output
rgy_max_bytes The registered decimal value that indicates the number
of bytes this code set uses to encode one character.
status Returns the status code from this routine. On
successful completion, the routine returns rpc_s_ok.
Otherwise, it returns one of the following errors:
dce_cs_c_cannot_open_file
dce_cs_c_cannot_read_file
dce_cs_c_notfound
dce_cs_c_unknown
Usage
The rpc_rgy_get_max_bytes routine belongs to a set of DCE RPC
routines for use by client and server applications that are
transferring international character data in a heterogeneous
character set and code sets environment.
The rpc_rgy_get_max_bytes routine reads the code set registry on the
local host. It takes the specified registered code set value, uses it
as an index into the registry, and returns the decimal value that
indicates the number of bytes that the code set uses to encode one
character.
The DCE RPC stub support routines for buffer sizing use the
rpc_rgy_get_max_bytes routine as part of their procedure to determine
whether additional storage needs to be allocated for conversion
between local and network code sets. The DCE RPC stub support
routines call the rpc_rgy_get_max_bytes routine once to get the
rgy_max_bytes value for the code set to be used to transfer the data
over the network (the network code set) then call the routine again
to get the rgy_max_bytes value of their local code set. The stubs
then compare the two values to determine whether additional buffers
are necessary or whether the conversion can be done in place.
Client and server applications that use the DCE RPC buffer sizing
routines byte_net_size and byte_local_size do not need to call this
routine explicitly because these DCE RPC stub support routines call
it on their behalf. Application programmers who are developing their
own stub support routines for buffer sizing can use the
rpc_rgy_get_max_bytes routine in their code to get code set max_byte
information for their user-written buffer sizing routines.
Related Information
Commands:
csrc
Routines:
dce_cs_loc_to_rgy
dce_cs_rgy_to_loc
rpc_ns_mgmt_read_codesets
rpc_rgy_get_codesets
ΓòÉΓòÉΓòÉ 5.8.105. rpc_server_inq_bindings ΓòÉΓòÉΓòÉ
Purpose
Returns binding handles for communication with a server. This routine
is used by server applications.
Format
#include <dce/rpc.h>
void rpc_server_inq_bindings(
rpc_binding_vector_t **binding_vector,
unsigned32 *status);
Parameters
Output
binding_vector Returns the address of a vector of server binding
handles.
status Returns the status code from this routine. On
successful completion, the routine returns rpc_s_ok.
Otherwise, it returns rpc_s_no_bindings, which
indicates that there are no bindings.
Usage
The rpc_server_inq_bindings routine obtains a vector of server
binding handles. Binding handles are created by the RPC runtime when
a server application calls any of the following routines to register
protocol sequences.
o rpc_server_use_all_protseqs
o rpc_server_use_all_protseqs_if
o rpc_server_use_protseq
o rpc_server_use_protseq_ep
o rpc_server_use_protseq_if
The returned binding vector can contain binding handles with dynamic
endpoints and binding handles with well known endpoints, depending on
which of the preceding routines the server application called. See
Binding Handle for an explanation of dynamic and well-known
endpoints.
A server uses the vector of binding handles for exporting to the name
service, for registering with the local endpoint map, or for
conversion to string bindings.
If there are no binding handles (no registered protocol sequences),
this routine returns the rpc_s_no_bindings status code and returns
the value NULL to the binding_vector parameter.
The server is responsible for calling rpc_binding_vector_free to
deallocate the memory used by the vector.
Related Information
Routines:
rpc_binding_vector_free
rpc_ep_register
rpc_ep_register_no_replace
rpc_ns_binding_export
rpc_server_use_all_protseqs
rpc_server_use_all_protseqs_if
rpc_server_use_protseq
rpc_server_use_protseq_ep
rpc_server_use_protseq_if
ΓòÉΓòÉΓòÉ 5.8.106. rpc_server_inq_if ΓòÉΓòÉΓòÉ
Purpose
Returns the manager entry point vector registered for an interface.
This routine is used by server applications.
Format
#include <dce/rpc.h>
void rpc_server_inq_if(
rpc_if_handle_t if_handle,
uuid_t *mgr_type_uuid,
rpc_mgr_epv_t *mgr_epv,
unsigned32 *status);
Parameters
Input
if_handle Specifies the interface specification whose manager
entry point vector (EPV) pointer is returned in the
mgr_epv parameter.
mgr_type_uuid Specifies a type UUID for the manager whose EPV pointer
is returned in the mgr_epv parameter.
Specifying the value NULL (or a nil UUID) has this
routine return a pointer to the manager EPV that is
registered with if_handle and the nil type UUID of the
manager.
Output
mgr_epv Returns a pointer to the manager EPV corresponding to
the if_handle and mgr_type_uuid parameters.
status Returns the status code from this routine. On
successful completion, the routine returns rpc_s_ok.
Otherwise, it returns one of the following errors:
rpc_s_unknown_if The interface is unknown.
rpc_s_unknown_mgr_type The manager type is
unknown.
Usage
A server application calls rpc_server_inq_if to determine the manager
EPV for a registered interface and type UUID of the manager.
Related Information
Routines:
rpc_server_register_if
ΓòÉΓòÉΓòÉ 5.8.107. rpc_server_listen ΓòÉΓòÉΓòÉ
Purpose
Tells the RPC runtime to listen for remote procedure calls. This
routine is used by server applications.
Format
#include <dce/rpc.h>
void rpc_server_listen(
unsigned32 max_calls_exec,
unsigned32 *status);
Parameters
Input
max_calls_exec Specifies the maximum number of concurrently running
remote procedure calls.
Use the value rpc_c_listen_max_calls_default to specify
the default value.
Also, the five rpc_server_use_xxx_protseq_xxx routines
limit (according to their max_call_requests parameter)
the number of concurrent remote procedure call requests
that a server can accept.
Output
status Returns the status code from this routine. On
successful completion, the routine returns rpc_s_ok.
Otherwise, it returns one of the following errors:
rpc_s_already_listening The server is already
listening.
rpc_s_max_calls_too_small The maximum calls value
is too small.
rpc_s_no_protseqs_registered No protocol sequences
are registered.
Usage
The rpc_server_listen routine makes a server listen for remote
procedure calls. DCE RPC allows a server to simultaneously process
multiple calls. The max_calls_exec parameter specifies the maximum
number of concurrent remote procedure calls the server runs. Each
remote procedure call runs in a call execution thread. The
implementation of the RPC architecture determines whether it reuses
call execution threads for the execution of subsequent remote
procedure calls or, instead, it creates a new thread for each use of
a subsequent remote procedure call.
The following conditions affect the number of concurrent remote
procedure calls that a server can process:
o Sufficient network resources must be available to accept
simultaneous call requests arriving over a particular protocol
sequence. The value of the max_call_requests parameter in the
five rpc_server_use_xxx_protseq_xxx routines advises the RPC
runtime about the runtime's request for network resources.
o Enough call threads must be available to run the simultaneous
call requests after they have been accepted. The value of the
max_calls_exec parameter in rpc_server_listen specifies the
number of call threads.
These conditions are independent of each other.
A server application that specifies a value for max_calls_exec
greater than 1 is responsible for concurrency control among the
remote procedures, because each runs in a separate thread.
If the server receives more remote procedure calls than it can run
(more calls than the value of max_calls_exec), the RPC runtime
accepts and queues additional remote procedure calls until a call
execution thread is available. From the client's perspective, a
queued remote procedure call looks the same as one that the server is
actively running. A client call remains blocked and in the queue
until any of the following events occurs:
o The remote procedure call is assigned to an available call
execution thread and the call runs to completion.
o The client can no longer communicate with the server.
o The client thread is canceled and the remote procedure call does
not complete within the cancel timeout limits.
The implementation of the RPC architecture determines the amount of
queuing it provides.
The RPC runtime continues listening for remote procedure calls (that
is, the routine does not return to the server) until one of the
following events occurs:
o One of the server application's manager routines calls
rpc_mgmt_stop_server_listening.
o A client is allowed to, and makes, a remote
rpc_mgmt_stop_server_listening call to the server.
o The communication function supporting datagram services has an
unrecoverable error.
On receiving a request to stop listening, the RPC runtime stops
accepting new remote procedure calls for all registered interfaces.
Running calls and existing queued calls are allowed to complete.
After all calls complete, rpc_server_listen returns to the caller,
which is a server application.
For more information about a server's listening for and handling
incoming remote procedure calls, see DCE for OS/2 Warp: Application
Development Guide - Core Components. This guide also contains
information about canceled threads.
Related Information
Routines: rpc_mgmt_stop_server_listening
rpc_server_register_if
rpc_server_use_all_protseqs
rpc_server_use_all_protseqs_if
rpc_server_use_protseq
rpc_server_use_protseq_ep
rpc_server_use_protseq_if
ΓòÉΓòÉΓòÉ 5.8.108. rpc_server_register_auth_info ΓòÉΓòÉΓòÉ
Purpose
Registers authentication information with the RPC runtime. This
routine is used by server applications.
Format
#include <dce/rpc.h>
void rpc_server_register_auth_info(
unsigned_char_t *server_princ_name,
unsigned32 authn_svc,
rpc_auth_key_retrieval_fn_t get_key_fn,
void *arg,
unsigned32 *status);
Parameters
Input
server_princ_name Specifies the principal name to use for the server
when authenticating remote procedure calls using the
service specified by authn_svc. The content of the name
and its syntax is defined by the authentication service
in use.
authn_svc Specifies the authentication service to use when the
server receives a remote procedure call request. The
following authentication services are supported:
rpc_c_authn_none No authentication
rpc_c_authn_dce_secret DCE shared-secret key
authentication
rpc_c_authn_dce_public DCE public key
authentication (reserved for
future use)
rpc_c_authn_default DCE default authentication
service
get_key_fn Specifies the address of a server-provided routine that
returns encryption keys.
The following C definition for
rpc_auth_key_retrieval_fn_t illustrates the prototype
for the encryption key acquisition routine:
typedef void (*rpc_auth_key_retrieval_fn_t)
(
void *arg, /* in */
unsigned_char_t *server_princ_name, /* in */
unsigned32 key_type, /* in */
unsigned32 key_ver, /* in */
void **key, /* out */
unsigned32 *status /* out */
);
The RPC runtime passes the server_princ_name parameter
value specified on the call to
rpc_server_register_auth_info, as the server_princ_name
parameter value, to the get_key_fn key acquisition
routine. The RPC runtime automatically provides a value
for the key version (key_ver) parameter. For a key_ver
value of 0 (zero), the key acquisition routine must
return the most recent key available. The routine
returns the key in the key parameter.
Note: The key_type parameter specifies a Kerberos
encryption key type. Because currently the DCE
supports only DES encryption, this parameter can
be ignored.
If the key acquisition routine, when called from
rpc_server_register_auth_info, returns a status other
than rpc_s_ok, the rpc_server_register_auth_info
routines fails and returns the error status to the
calling server.
If the key acquisition routine, when called by the RPC
runtime while authenticating a client remote procedure
call request, returns a status other than rpc_s_ok, the
request fails and the RPC runtime returns the error
status to the client.
arg Specifies a parameter to pass to the get_key_fn key
acquisition routine, if specified. See the get_key_fn
parameter for details.
Specify NULL for arg to use the default key table file,
/krb/v5srvtab. The calling server must be root to
access this file.
If arg is a key table file name, the file must have
been created with the ktadd command. If the specified
key table file resides in /krb5, you can supply only
the file name. If the file does not reside in /krb5,
you must supply the full path name. You must prepend
the file's absolute path name using the prefix FILE:.
Output
status Returns the status code from this routine. On
successful completion, the routine returns rpc_s_ok.
Otherwise, it returns one of the following errors:
rpc_s_unknown_authn_service The authentication
service is unknown.
rpc_s_key_func_not_allowed The authn_svc parameter
contains rpc_c_authn_default
and a non-null value was
supplied for the get_key_fn
parameter.
Usage
The rpc_server_register_auth_info routine registers an authentication
service to use for authenticating remote procedure calls to a
particular server principal. A server calls this routine once for
each authentication service and principal name combination that it
wants to register.
The authentication service specified by a client (using the
rpc_binding_set_auth_info routine) must be one of the authentication
services registered by the server. If it is not, the client's remote
procedure call request fails with a rpc_s_unknown_authn_service
status code.
The following table shows the RPC runtime behavior for acquiring
encryption keys for each supported authentication service. Note that
if authn_svc is rpc_c_authn_default, get_key_fn must be NULL.
ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
Γöé Table 10. RPC Key Acquisition for Authentication Services Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé authn_svc Γöé get_key_fn Γöé arg Γöé Runtime Behavior Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé rpc_c_authn_default Γöé NULL Γöé NULL Γöé Uses the default Γöé
Γöé Γöé Γöé Γöé method of Γöé
Γöé Γöé Γöé Γöé encryption key Γöé
Γöé Γöé Γöé Γöé acquisition from Γöé
Γöé Γöé Γöé Γöé the default key Γöé
Γöé Γöé Γöé Γöé table. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé rpc_c_authn_default Γöé NULL Γöé non-NΓöéLUses the default Γöé
Γöé Γöé Γöé Γöé method of Γöé
Γöé Γöé Γöé Γöé encryption key Γöé
Γöé Γöé Γöé Γöé acquisition from Γöé
Γöé Γöé Γöé Γöé the specified key Γöé
Γöé Γöé Γöé Γöé table. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé rpc_c_authn_default Γöé non-NULL Γöé IgnorΓöédError returned. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé rpc_c_authn_none Γöé ignored Γöé ignorΓöédNo authentication Γöé
Γöé Γöé Γöé Γöé performed. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé rpc_c_authn_dce_secret Γöé NULL Γöé NULL Γöé Uses the default Γöé
Γöé Γöé Γöé Γöé method of Γöé
Γöé Γöé Γöé Γöé encryption key Γöé
Γöé Γöé Γöé Γöé acquisition from Γöé
Γöé Γöé Γöé Γöé the default key Γöé
Γöé Γöé Γöé Γöé table. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé rpc_c_authn_dce_secret Γöé NULL Γöé non-NΓöéLUses the default Γöé
Γöé Γöé Γöé Γöé method of Γöé
Γöé Γöé Γöé Γöé encryption key Γöé
Γöé Γöé Γöé Γöé acquisition from Γöé
Γöé Γöé Γöé Γöé the specified key Γöé
Γöé Γöé Γöé Γöé table. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé rpc_c_authn_dce_secret Γöé non-NULL Γöé NULL Γöé Uses the specified Γöé
Γöé Γöé Γöé Γöé encryption key Γöé
Γöé Γöé Γöé Γöé acquisition Γöé
Γöé Γöé Γöé Γöé routine to obtain Γöé
Γöé Γöé Γöé Γöé keys from the Γöé
Γöé Γöé Γöé Γöé default key table. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé rpc_c_authn_dce_secret Γöé non-NULL Γöé non-NΓöéLUses the specified Γöé
Γöé Γöé Γöé Γöé encryption key Γöé
Γöé Γöé Γöé Γöé acquisition Γöé
Γöé Γöé Γöé Γöé routine to obtain Γöé
Γöé Γöé Γöé Γöé keys from the Γöé
Γöé Γöé Γöé Γöé specified key Γöé
Γöé Γöé Γöé Γöé table. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé rpc_c_authn_dce_public Γöé ignored Γöé ignorΓöéd(Reserved for Γöé
Γöé Γöé Γöé Γöé future use) Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
Related Information
Routines:
rpc_binding_set_auth_info
sec_key_mgmt_get_nth_key
ΓòÉΓòÉΓòÉ 5.8.109. rpc_server_register_if ΓòÉΓòÉΓòÉ
Purpose
Registers an interface with the RPC runtime. This routine is used by
server applications.
Format
#include <dce/rpc.h>
void rpc_server_register_if(
rpc_if_handle_t if_handle,
uuid_t *mgr_type_uuid,
rpc_mgr_epv_t mgr_epv,
unsigned32 *status);
Parameters
Input
if_handle An IDL-generated data structure specifying the
interface to register.
mgr_type_uuid Specifies a type UUID to associate with the mgr_epv
parameter. Specifying the value NULL (or a nil UUID)
registers the if_handle with a nil type UUID.
mgr_epv Specifies the manager routine's entry point vector. To
use the IDL-generated default entry point vector,
specify NULL.
Output
status Returns the status code from this routine. On
successful completion, the routine returns rpc_s_ok.
Otherwise, it returns one of the following errors:
rpc_s_type_already_registered An interface with
the given type UUID is
already registered.
rpc_s_no_memory No memory.
rpc_no_epv If mgr_epv has value NULL and
there is no default epv in
the interface handle.
Usage
The rpc_server_register_if routine registers a server interface with
the RPC runtime. A server can register an unlimited number of
interfaces. After it is registered, an interface is available to
clients through any binding handle of the server, provided that the
binding handle is compatible for the client.
A server must provide the following information to register an
interface:
o An interface specification, which is a data structure generated
by the IDL compiler. The server specifies the interface
specification of the interface using the if_handle parameter.
o A type UUID and manager entry point vector (EPV), a data pair
that determines the manager routine that runs when a server
receives a remote procedure call request from a client.
The server specifies the type UUID and EPV using the
mgr_type_uuid and mgr_epv parameters, respectively. Note that
when a non-nil type UUID is specified, the server must also call
rpc_object_set_type to register objects of this non-nil type.
A server that offers only a single manager for an interface calls
rpc_server_register_if once for that interface. In the simple case
where the single manager's entry point names are the same as the
operation names in the IDL interface definition, the IDL-generated
default manager EPV for the interface can be used. The value NULL in
the mgr_epv parameter specifies the default manager EPV.
Note that if a server offers multiple implementations of an
interface, the server code must register a separate manager entry
point vector for each interface implementation.
Rules for Calling Manager Routines
The RPC runtime dispatches an incoming remote procedure call to a
manager that offers the requested RPC interface. When multiple
managers are registered for an interface, the RPC runtime must select
one of them. To select a manager, the RPC runtime uses the object
UUID specified by the binding handle of the call.
The following table summarizes the rules applied for calling manager
routines.
ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
Γöé Table 11. Rules for Invoking Manager Routines Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé Object UUID Γöé Has Server Γöé Has Server Γöé Dispatching Action Γöé
Γöé of Call(1) Γöé Set Type of Γöé Registered Γöé Γöé
Γöé Γöé Object Γöé Type for Γöé Γöé
Γöé Γöé UUID?(2) Γöé Manager Γöé Γöé
Γöé Γöé Γöé EPV?(3) Γöé Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé nil Γöé Not appli- Γöé yes Γöé Uses the manager with the Γöé
Γöé Γöé cable(4) Γöé Γöé nil type UUID. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé nil Γöé Not appli- Γöé no Γöé Error Γöé
Γöé Γöé cable(4) Γöé Γöé (RPC_S_UNKNOWN_MGR_TYPE). Γöé
Γöé Γöé Γöé Γöé Rejects the remote proce- Γöé
Γöé Γöé Γöé Γöé dure call. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé non-nil Γöé yes Γöé yes Γöé Uses the manager with the Γöé
Γöé Γöé Γöé Γöé same type UUID. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé non-nil Γöé no Γöé ignored Γöé Uses the manager with the Γöé
Γöé Γöé Γöé Γöé nil type UUID. If no Γöé
Γöé Γöé Γöé Γöé manager with the nil type Γöé
Γöé Γöé Γöé Γöé UUID was registered, Γöé
Γöé Γöé Γöé Γöé (error Γöé
Γöé Γöé Γöé Γöé RPC_S_UNKNOWN_MGR_TYPE), Γöé
Γöé Γöé Γöé Γöé rejects the remote proce- Γöé
Γöé Γöé Γöé Γöé dure call. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé non-nil Γöé yes Γöé no Γöé Error Γöé
Γöé Γöé Γöé Γöé (RPC_S_UNKNOWN_MGR_TYPE). Γöé
Γöé Γöé Γöé Γöé Rejects the remote proce- Γöé
Γöé Γöé Γöé Γöé dure call. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé NOTES: Γöé
Γöé Γöé
Γöé (1) Γöé
Γöé This is the object UUID found in a binding handle for a remote Γöé
Γöé procedure. Γöé
Γöé (2) Γöé
Γöé By calling RPC_OBJECT_SET_TYPE to specify the type UUID for an Γöé
Γöé object. Γöé
Γöé (3) Γöé
Γöé By calling RPC_SERVER_REGISTER_IF using the same type UUID. Γöé
Γöé (4) Γöé
Γöé The nil object UUID is always automatically assigned the nil type Γöé
Γöé UUID. It is illegal to specify a nil object UUID in Γöé
Γöé RPC_OBJECT_SET_TYPE. Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
For more information about registering server interfaces and calling
manager routines, see the DCE for OS/2 Warp: Application Development
Guide - Core Components.
Related Information
Routines:
rpc_binding_set_object
rpc_ep_register
rpc_ep_register_no_replace
rpc_ns_binding_export
rpc_object_set_type
rpc_server_unregister_if
ΓòÉΓòÉΓòÉ 5.8.110. rpc_server_unregister_if ΓòÉΓòÉΓòÉ
Purpose
Removes an interface from the RPC runtime. This routine is used by
server applications.
Format
#include <dce/rpc.h>
void rpc_server_unregister_if(
rpc_if_handle_t if_handle,
uuid_t *mgr_type_uuid,
unsigned32 *status);
Parameters
Input
if_handle Specifies an interface specification to unregister
(remove).
Specify NULL to remove all interfaces previously
registered with the type UUID value given in the
mgr_type_uuid parameter.
mgr_type_uuid Specifies the type UUID for the manager entry point
vector (EPV) to remove. This needs to be the same value
as provided in a call to the rpc_server_register_if
routine.
Specify NULL to remove the interface given in the
if_handle parameter for all previously registered type
UUIDs.
Specify a nil UUID to remove the IDL-generated default
manager EPV. In this case all manager EPVs registered
with a non-nil type UUID remain registered.
Output
status Returns the status code from this routine. On
successful completion, the routine returns rpc_s_ok.
Otherwise, it returns one of the following errors:
rpc_s_unknown_if The interface is unknown.
rpc_s_unknown_mgr_type The manager type is
unknown.
Usage
The rpc_server_unregister_if routine removes the association between
an interface and a manager entry point vector (EPV).
Specify the manager EPV to remove by providing, in the mgr_type_uuid
parameter, the type UUID value specified in a call to the
rpc_server_register_if routine. Once removed, an interface is no
longer available to client applications.
When an interface is removed, the RPC runtime stops accepting new
calls for that interface. Currently running calls (on that interface)
are allowed to complete.
The following table summarizes the actions of this routine.
ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
Γöé Table 12. Rules for Removing an Interface Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé if_handle Γöé mgr_type_uuid Γöé Action Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé non-NULL Γöé non-NULL Γöé Removes the manager EPV associ- Γöé
Γöé Γöé Γöé ated with the specified parame- Γöé
Γöé Γöé Γöé ters. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé non-NULL Γöé NULL Γöé Removes all manager EPVs associ- Γöé
Γöé Γöé Γöé ated with the if_handle param- Γöé
Γöé Γöé Γöé eter. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé NULL Γöé non-NULL Γöé Removes all manager EPVs associ- Γöé
Γöé Γöé Γöé ated with the mgr_type_uuid Γöé
Γöé Γöé Γöé parameter. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé NULL Γöé NULL Γöé Removes all manager EPVs. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé NOTE: When both of the parameters if_handle and save mgr_type_uuid Γöé
Γöé are given the value NULL, this routine has the effect of preventing Γöé
Γöé the server from receiving any new remote procedure calls because all Γöé
Γöé the manager EPVs for all interfaces have been removed. Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
Related Information
Routines:
rpc_server_register_if
ΓòÉΓòÉΓòÉ 5.8.111. rpc_server_use_all_protseqs ΓòÉΓòÉΓòÉ
Purpose
Tells the RPC runtime to use all supported protocol sequences for
receiving remote procedure calls. This routine is used by server
applications.
Format
#include <dce/rpc.h>
void rpc_server_use_all_protseqs(
unsigned32 max_call_requests,
unsigned32 *status);
Parameters
Input
max_call_requests Specifies the maximum number of concurrent remote
procedure call requests that the server can accept.
The RPC runtime guarantees that the server can accept
at least this number of concurrent call requests. The
actual number of these requests can be greater than the
value of max_call_requests and can vary for each
protocol sequence.
Use the value rpc_c_protseq_max_reqs_default to specify
the default parameter value.
Note that in this version of DCE RPC, any number you
specify is replaced by the default value.
Also, rpc_server_listen limits (according to its
max_calls_exec parameter) the amount of concurrent
remote procedure call execution. See rpc_server_listen
for more information.
Output
status Returns the status code from this routine. On
successful completion, the routine returns rpc_s_ok.
Otherwise, it returns one of the following errors:
rpc_s_cant_create_socket Cannot create a socket.
rpc_s_max_descs_exceeded Exceeded the maximum
number of network descriptors.
rpc_s_no_protseqs No supported protocol
sequences.
Usage
The rpc_server_use_all_protseqs routine registers all supported
protocol sequences with the RPC runtime. A server must register at
least one protocol sequence with the RPC runtime to receive remote
procedure call requests.
For each protocol sequence registered by a server, the RPC runtime
creates one or more binding handles. Each binding handle contains a
dynamic endpoint that the RPC runtime and operating system generated.
The max_call_requests parameter allows you to specify the maximum
number of concurrent remote procedure call requests the server
handles.
After registering protocol sequences, a server typically calls the
following routines:
rpc_server_inq_bindings Obtains a vector containing all of the
server's binding handles.
rpc_ep_register Registers the binding handles with the local
endpoint map.
rpc_ep_register_no_replace Registers the binding handles with the
local endpoint map.
rpc_ns_binding_export Places the binding handles in the name service
database for access by any client.
rpc_binding_vector_free Frees the vector of server binding handles.
rpc_server_register_if Registers with the RPC runtime those
interfaces that the server offers.
rpc_server_listen Enables the reception of remote procedure calls.
To register protocol sequences selectively, a server calls:
o rpc_server_use_protseq
o rpc_server_use_all_protseqs_if
o rpc_server_use_protseq_if
o rpc_server_use_protseq_ep
For an explanation of how a server can establish a client-server
relationship without using the local endpoint map or the name service
database, see String Binding.
Related Information
Routines:
rpc_binding_from_string_binding
rpc_binding_to_string_binding
rpc_binding_vector_free
rpc_ep_register
rpc_ep_register_no_replace
rpc_ns_binding_export
rpc_server_inq_bindings
rpc_server_listen
rpc_server_register_if
rpc_server_use_all_protseqs_if
rpc_server_use_protseq
rpc_server_use_protseq_ep
rpc_server_use_protseq_if
ΓòÉΓòÉΓòÉ 5.8.112. rpc_server_use_all_protseqs_if ΓòÉΓòÉΓòÉ
Purpose
Tells the RPC runtime to use all the protocol sequences and endpoints
specified in the interface specification for receiving remote
procedure calls. This routine is used by server applications.
Format
#include <dce/rpc.h>
void rpc_server_use_all_protseqs_if(
unsigned32 max_call_requests,
rpc_if_handle_t if_handle,
unsigned32 *status);
Parameters
Input
max_call_requests Specifies the maximum number of concurrent remote
procedure call requests that the server can accept.
The RPC runtime guarantees that the server can accept
at least this number of concurrent call requests. The
actual number of these requests can be greater than the
value of max_call_requests and can vary for each
protocol sequence.
Use the value rpc_c_protseq_max_reqs_default to specify
the default parameter value. Note that in this version
of DCE RPC, any number you specify is replaced by the
default value.
Also, the rpc_server_listen routine limits (according
to its max_calls_exec parameter) the amount of
concurrent remote procedure call execution. See
rpc_server_listen for more information.
if_handle Specifies an interface specification containing the
protocol sequences and their corresponding endpoint
information to use in creating binding handles. Each
created binding handle contains a well known
(nondynamic) endpoint contained in the interface
specification.
Output
status Returns the status code from this routine. On
successful completion, the routine returns rpc_s_ok.
Otherwise, it returns one of the following errors:
rpc_s_calls_too_large_for_wk_ep The maximum number
of concurrent calls is too
large.
rpc_s_cant_bind_socket Cannot bind to a socket.
rpc_s_cant_create_socket Cannot create a socket.
rpc_s_cant_inq_socket Cannot obtain an endpoint
from the socket.
rpc_s_invalid_endpoint_format The interface handle
is not valid.
rpc_s_max_descs_exceeded Exceeded the maximum
number of network
descriptors.
rpc_s_no_protseqs No supported protocol
sequences.
Usage
The rpc_server_use_all_protseqs_if routine registers all protocol
sequences and associated endpoint address information provided in the
IDL file with the RPC runtime. A server must register at least one
protocol sequence with the RPC runtime to receive remote procedure
call requests.
For each protocol sequence registered by a server, the RPC runtime
creates one or more binding handles. Each binding handle contains the
well known endpoint specified in the IDL file.
The max_call_requests parameter allows you to specify the maximum
number of concurrent remote procedure call requests the server
handles.
If you want to register selected protocol sequences specified in the
IDL, your server uses rpc_server_use_protseq_if.
The rpc_server_use_all_protseqs routine contains a list of the
routines a server typically calls after calling this routine.
(However, a server that uses only rpc_server_use_all_protseqs_if does
not subsequently call rpc_ep_register or rpc_ep_register_no_replace.)
For an explanation of how a server can establish a client-server
relationship without using the local endpoint map or the name service
database, see String Binding.
Related Information
Routines:
rpc_binding_vector_free
rpc_ep_register
rpc_ep_register_no_replace
rpc_ns_binding_export
rpc_server_inq_bindings
rpc_server_listen
rpc_server_register_if
rpc_server_use_all_protseqs
rpc_server_use_protseq
rpc_server_use_protseq_ep
rpc_server_use_protseq_if
ΓòÉΓòÉΓòÉ 5.8.113. rpc_server_use_protseq ΓòÉΓòÉΓòÉ
Purpose
Tells the RPC runtime to use the specified protocol sequence for
receiving remote procedure calls. This routine is used by server
applications.
Format
#include <dce/rpc.h>
void rpc_server_use_protseq(
unsigned_char_t *protseq,
unsigned32 max_call_requests,
unsigned32 *status);
Parameters
Input
protseq Specifies a string identifier for the protocol sequence
to register with the RPC runtime. See Protocol Sequence
for a list of string identifiers.
max_call_requests Specifies the maximum number of concurrent remote
procedure call requests that the server can accept.
The RPC runtime guarantees that the server can accept
at least this number of concurrent call requests. The
actual number of these requests can be greater than the
value of max_call_requests and can vary for each
protocol sequence.
Use the value rpc_c_protseq_max_reqs_default to specify
the default parameter value.
Note that in this version of DCE RPC, any number you
specify is replaced by the default value.
Also, the rpc_server_listen routine limits (according
to its max_calls_exec parameter) the amount of
concurrent remote procedure call execution. See
rpc_server_listen for more information.
Output
status Returns the status code from this routine. On
successful completion, the routine returns rpc_s_ok.
Otherwise, it returns one of the following errors:
rpc_s_cant_create_socket Cannot create a socket.
rpc_s_invalid_rpc_protseq The protocol sequence is
not valid.
rpc_s_max_descs_exceeded Exceeded the maximum
number of network
descriptors.
rpc_s_protseq_not_supported The protocol sequence
is not supported on this
host.
Usage
The rpc_server_use_protseq routine registers a single protocol
sequence with the RPC runtime. A server must register at least one
protocol sequence with the RPC runtime to receive remote procedure
call requests. A server can call this routine multiple times to
register additional protocol sequences.
For each protocol sequence registered by a server, the RPC runtime
creates one or more binding handles. Each binding handle contains a
dynamic endpoint that the RPC runtime and operating system generated.
The max_call_requests parameter allows you to specify the maximum
number of concurrent remote procedure call requests the server
handles.
A server calls rpc_server_use_all_protseqs to register all protocol
sequences.
The description of rpc_server_use_all_protseqs contains a list of the
routines a server typically calls after calling this routine. For an
explanation of how a server can establish a client-server
relationship without using the local endpoint map or the name service
database, see String Binding.
Related Information
Routines:
rpc_binding_vector_free
rpc_ep_register
rpc_ep_register_no_replace
rpc_network_is_protseq_valid
rpc_ns_binding_export
rpc_server_inq_bindings
rpc_server_listen
rpc_server_register_if
rpc_server_use_all_protseqs
rpc_server_use_all_protseqs_if
rpc_server_use_protseq_ep
rpc_server_use_protseq_if
ΓòÉΓòÉΓòÉ 5.8.114. rpc_server_use_protseq_ep ΓòÉΓòÉΓòÉ
Purpose
Tells the RPC runtime to use the specified protocol sequence combined
with the specified endpoint for receiving remote procedure calls.
This routine is used by server applications.
Format
#include <dce/rpc.h>
void rpc_server_use_protseq_ep(
unsigned_char_t *protseq ,
unsigned32 max_call_requests,
unsigned_char_t *endpoint,
unsigned32 *status);
Parameters
Input
protseq Specifies a string identifier for the protocol sequence
to register with the RPC runtime. See Protocol Sequence
for a list of string identifiers.
max_call_requests Specifies the maximum number of concurrent remote
procedure call requests that the server can accept.
The RPC runtime guarantees that the server can accept
at least this number of concurrent call requests. The
actual number of these requests can be greater than the
value of max_call_requests and can vary for each
protocol sequence.
Use the value rpc_c_protseq_max_reqs_default to specify
the default parameter value. Note that in this version
of DCE RPC, any number you specify is replaced by the
default value.
Also, rpc_server_listen limits (according to its
max_calls_exec parameter) the amount of concurrent
remote procedure call execution. See rpc_server_listen
for more information.
endpoint Specifies address information for an endpoint. This
information is used in creating a binding handle for
the protocol sequence specified in the protseq
parameter.
Output
status Returns the status code from this routine. On
successful completion, the routine returns rpc_s_ok.
Otherwise, it returns one of the following errors:
rpc_s_calls_too_large_for_wk_ep The maximum number
of concurrent calls is too
large.
rpc_s_cant_bind_socket Cannot bind to a socket.
rpc_s_cant_create_socket Cannot create a socket.
rpc_s_invalid_endpoint_format The endpoint format
is not valid.
rpc_s_invalid_rpc_protseq The protocol sequence is
not valid.
rpc_s_max_descs_exceeded Exceeded the maximum
number of network
descriptors.
rpc_s_protseq_not_supported The protocol sequence
is not supported on this
host.
Usage
The rpc_server_use_protseq_ep routine registers a protocol sequence
and its specified endpoint address information with the RPC runtime.
A server must register at least one protocol sequence with the RPC
runtime to receive remote procedure call requests. A server can call
this routine multiple times to register additional protocol sequences
and endpoints.
For each protocol sequence registered by a server, the RPC runtime
creates one or more binding handles. Each binding handle contains the
well known endpoint specified in the endpoint parameter.
The max_call_requests parameter allows you to specify the maximum
number of concurrent remote procedure call requests the server
handles.
The explanation of rpc_server_use_all_protseqs contains a list of the
routines a server typically calls after calling this routine. For an
explanation of how a server can establish a client-server
relationship without using the local endpoint map or the name service
database, see String Binding.
Related Information
Routines:
rpc_binding_vector_free
rpc_ep_register
rpc_ep_register_no_replace
rpc_ns_binding_export
rpc_server_inq_bindings
rpc_server_listen
rpc_server_register_if
rpc_server_use_all_protseqs
rpc_server_use_all_protseqs_if
rpc_server_use_protseq
ΓòÉΓòÉΓòÉ 5.8.115. rpc_server_use_protseq_if ΓòÉΓòÉΓòÉ
Purpose
Tells the RPC runtime to use the specified protocol sequence combined
with the endpoints in the interface specification for receiving
remote procedure calls. This routine is used by server applications.
Format
#include <dce/rpc.h>
void rpc_server_use_protseq_if(
unsigned_char_t *protseq,
unsigned32 max_call_requests,
rpc_if_handle_t if_handle,
unsigned32 *status);
Parameters
Input
protseq Specifies a string identifier for the protocol sequence
to register with the RPC runtime. See Protocol Sequence
for a list of string identifiers.
max_call_requests Specifies the maximum number of concurrent remote
procedure call requests that the server can accept.
The RPC runtime guarantees that the server can accept
at least this number of concurrent call requests. The
actual number of these requests can be greater than the
value of max_call_requests and can vary for each
protocol sequence.
Use the value rpc_c_protseq_max_reqs_default to specify
the default parameter value.
Note that in this version of DCE RPC, any number you
specify is replaced by the default value.
Also, the rpc_server_listen routine limits (according
to its max_calls_exec parameter) the amount of
concurrent remote procedure call execution. See
rpc_server_listen for more information.
if_handle Specifies the interface specification whose endpoint
information is used in creating a binding for the
protocol sequence specified in the protseq parameter.
Each created binding handle contains a well-known
(nondynamic) endpoint contained in the interface
specification.
Output
status Returns the status code from this routine. On
successful completion, the routine returns rpc_s_ok.
Otherwise, it returns one of the following errors:
rpc_s_calls_too_large_for_wk_ep The maximum number
of concurrent calls is too
large.
rpc_s_cant_bind_socket Cannot bind to a socket.
rpc_s_invalid_endpoint_format The endpoint format
is not valid.
rpc_s_invalid_rpc_protseq The protocol sequence is
not valid.
rpc_s_max_descs_exceeded Exceeded the maximum
number of network
descriptors.
rpc_s_protseq_not_supported The protocol sequence
is not supported on this
host.
Usage
The rpc_server_use_protseq_if routine registers one protocol sequence
with the RPC runtime, including its endpoint address information as
provided in the specified IDL file.
A server must register at least one protocol sequence with the RPC
runtime to receive remote procedure call requests. A server can call
this routine multiple times to register additional protocol
sequences.
For each protocol sequence registered by a server, the RPC runtime
creates one or more binding handles. Each binding handle contains
the well known endpoint specified in the IDL file.
The max_call_requests parameter allows you to specify the maximum
number of concurrent remote procedure call requests the server
handles.
To register all protocol sequences from the IDL, a server calls
rpc_server_use_all_protseqs_if.
The explanation of rpc_server_use_all_protseqs contains a list of the
routines a server typically calls after calling this routine.
(However, a server that uses only rpc_server_use_protseq_if does not
subsequently call rpc_ep_register or rpc_ep_register_no_replace.) For
an explanation of how a server can establish a client-server
relationship without using the local endpoint map or the name service
database, see String Binding.
Related Information
Routines:
rpc_binding_vector_free
rpc_ep_register
rpc_ep_register_no_replace
rpc_ns_binding_export
rpc_server_inq_bindings
rpc_server_listen
rpc_server_register_if
rpc_server_use_all_protseqs
rpc_server_use_all_protseqs_if
rpc_server_use_protseq
rpc_server_use_protseq_ep
ΓòÉΓòÉΓòÉ 5.8.116. rpc_sm_allocate ΓòÉΓòÉΓòÉ
Purpose
Allocates memory within the RPC stub memory management scheme.
Format
#include <rpc.h>
idl_void_p_t rpc_sm_allocate(
unsigned long size,
unsigned32 *status);
Parameters
Input
size Specifies, in bytes, the size of memory to be
allocated.
Output
status Returns the status code from this routine. On
successful completion, the routine returns rpc_s_ok.
Otherwise, it returns an error.
Usage
Applications call rpc_sm_allocate to allocate memory within the RPC
stub memory management scheme. Before a call to this routine, the
stub memory management environment must have been established. For
manager code that is called from the stub, the stub itself normally
established the necessary environment. When rpc_sm_allocate is used
by code that is not called from the stub, the application must
establish the required memory management environment by calling
rpc_sm_enable_allocate.
When the stub establishes the memory management environment, the stub
itself frees any memory allocated by rpc_sm_allocate. The application
can free such memory before returning to the calling stub by calling
rpc_sm_free.
When the application establishes the memory management environment,
it must free any memory allocated, either by calling rpc_sm_free or
by calling rpc_sm_disable_allocate.
Multiple threads may call rpc_sm_allocate and rpc_sm_free to manage
the same memory within the stub memory management environment. To do
so the threads must share the same stub memory management thread
handle. Applications pass thread handles from thread to thread by
calling rpc_sm_get_thread_handle and rpc_sm_set_thread_handle.
Related Information
Routines:
rpc_sm_free
rpc_sm_enable_allocate
rpc_sm_disable_allocate
rpc_sm_get_thread_handle
rpc_sm_set_thread_handle
ΓòÉΓòÉΓòÉ 5.8.117. rpc_sm_client_free ΓòÉΓòÉΓòÉ
Purpose
Frees memory returned from a client stub.
Format
#include <rpc.h>
void rpc_sm_client_free(
idl_void_p_t node_to_free,
unsigned32 *status);
Parameters
Input
node_to_free Specifies a pointer to memory returned from a client
stub.
Output
status Returns the status code from this routine. On
successful completion, the routine returns rpc_s_ok.
Otherwise, it returns an error.
Usage
The rpc_sm_client_free routine releases memory allocated and returned
from a client stub. The thread calling this routine must have the
same thread handle as the thread that made the remote procedure call.
Applications pass thread handles from thread to thread by calling
rpc_sm_get_thread_handle and rpc_sm_set_thread_handle.
This routine enables a routine to deallocate dynamically allocated
memory returned by a remote procedure call without knowledge of the
memory management environment from which it was called.
Related Information
Routines:
rpc_sm_free
rpc_sm_set_client_alloc_free
rpc_sm_swap_client_alloc_free
rpc_sm_get_thread_handle
rpc_sm_set_thread_handle
ΓòÉΓòÉΓòÉ 5.8.118. rpc_sm_destroy_client_context ΓòÉΓòÉΓòÉ
Purpose
Reclaims the client memory resources for a context handle and sets
the context handle to NULL.
Format
#include <rpc.h>
void rpc_sm_destroy_client_context(
idl_void_p_t p_unusable_context_handle,
unsigned32 *status);
Parameters
Input
p_unusable_context_handle Specifies the context handle that can no
longer be accessed.
Output
status Returns the status code from this routine. On
successful completion, the routine returns rpc_s_ok.
Otherwise, it returns an error.
Usage
The rpc_sm_destroy_client_context routine is used by client
applications to reclaim the client resources used in maintaining an
active context handle. Applications call this routine after a
communications error makes the context handle unusable. When the
rpc_sm_destroy_client_context routine reclaims the memory resources,
it also sets the context handle to NULL.
ΓòÉΓòÉΓòÉ 5.8.119. rpc_sm_disable_allocate ΓòÉΓòÉΓòÉ
Purpose
Releases resources and allocated memory within the stub memory
management scheme.
Format
#include <rpc.h>
void rpc_sm_disable_allocate(
unsigned32 *status);
Parameters
Output
status Returns the status code from this routine. On
successful completion, the routine returns rpc_s_ok.
Otherwise, it returns an error.
Usage
The rpc_sm_disable_allocate routine releases all resources acquired
by a call to rpc_sm_enable_allocate and any memory allocated by calls
to rpc_sm_allocate after the call to rpc_sm_enable_allocate was made.
When the stub establishes the memory management environment, the stub
itself frees any memory allocated by rpc_sm_allocate. The application
can free such memory before returning to the calling stub by calling
rpc_sm_free.
The rpc_sm_enable_allocate and rpc_sm_disable_allocate routines must
be used in matching pairs.
Related Information
Routines:
rpc_sm_enable_allocate
rpc_sm_allocate
ΓòÉΓòÉΓòÉ 5.8.120. rpc_sm_enable_allocate ΓòÉΓòÉΓòÉ
Purpose
Enables the stub memory management environment.
Format
#include <rpc.h>
void rpc_sm_enable_allocate(
unsigned32 *status);
Parameters
Output
status Returns the status code from this routine. On
successful completion, the routine returns rpc_s_ok.
Otherwise, it returns an error.
Usage
Applications can call rpc_sm_enable_allocate to establish a stub
memory management environment in cases where one is not established
by the stub itself. A stub memory management environment must be
established before any calls are made to rpc_sm_allocate. For server
manager code called from the stub itself, the stub memory management
environment is normally established by the stub itself. Code that is
called from other contexts needs to call rpc_sm_enable_allocate
before calling rpc_sm_allocate.
Note: For a discussion of how spawned threads acquire a stub memory
management environment, see the rpc_sm_get_thread_handle and
rpc_sm_set_thread_handle routines.
Related Information
Routines:
rpc_sm_disable_allocate
rpc_sm_allocate
ΓòÉΓòÉΓòÉ 5.8.121. rpc_sm_free ΓòÉΓòÉΓòÉ
Purpose
Frees memory allocated by the rpc_sm_allocate routine.
Format
#include <rpc.h>
void rpc_sm_free(
idl_void_p_t node_to_free,
unsigned32 *status);
Parameters
Input
node_to_free Specifies a pointer to memory allocated by
rpc_sm_allocate.
Output
status Returns the status code from this routine. On
successful completion, the routine returns rpc_s_ok.
Otherwise, it returns an error.
Usage
Applications call rpc_sm_free to release memory allocated by
rpc_sm_allocate.
When the stub allocates memory within the stub memory management
environment, manager code called from the stub can also use
rpc_sm_free to release memory allocated by the stub.
The thread calling rpc_sm_free must have the same thread handle as
the thread that allocated the memory with rpc_sm_allocate.
Applications pass thread handles from thread to thread by calling
rpc_sm_get_thread_handle and rpc_sm_set_thread_handle.
Related Information
Routines:
rpc_sm_allocate
rpc_sm_get_thread_handle
rpc_sm_set_thread_handle
ΓòÉΓòÉΓòÉ 5.8.122. rpc_sm_get_thread_handle ΓòÉΓòÉΓòÉ
Purpose
Gets a thread handle for the stub memory management environment.
Format
#include <rpc.h>
rpc_sm_thread_handle_t rpc_sm_get_thread_handle(
unsigned32 *status);
Parameters
Output
status Returns the status code from this routine. On
successful completion, the routine returns rpc_s_ok.
Otherwise, it returns an error.
Usage
Applications call rpc_sm_get_thread_handle to get a thread handle for
the current stub memory management environment. A thread that is
managing memory within the stub memory management scheme calls
rpc_sm_get_thread_handle to get a thread handle for its current stub
memory management environment. A thread that calls
rpc_sm_set_thread_handle with this handle, is able to use the same
memory management environment.
When multiple threads call rpc_sm_allocate and rpc_sm_free to manage
the same memory, they must share the same thread handle. The thread
that established the stub memory management environment calls
rpc_sm_get_thread_handle to get a thread handle before spawning new
threads that manage the same memory. The spawned threads then call
rpc_sm_set_thread_handle with the handle provided by the parent
thread.
Application Note: Typically, rpc_sm_get_thread_handle is called by a
server manager routine before it spawns additional
threads. Normally, the stub sets up the memory management
environment for the manager routine. The manager calls
rpc_sm_get_thread_handle to make this environment
available to the spawned threads.
A thread can also use rpc_sm_get_thread_handle and
rpc_sm_set_thread_handle to save and restore its memory
management environment.
Return Codes
This routine returns a thread handle to the rpc_sm_thread_handle_t
variable.
Related Information
Routines:
rpc_sm_allocate
rpc_sm_free
rpc_sm_set_thread_handle
ΓòÉΓòÉΓòÉ 5.8.123. rpc_sm_set_client_alloc_free ΓòÉΓòÉΓòÉ
Purpose
Sets the memory allocation and freeing mechanisms used by the client
stubs.
Format
#include <rpc.h>
void rpc_sm_set_client_alloc_free (
idl_void_p_t (*p_allocate) ( unsigned long size),
void (p_free) ( idl_void_p_t ptr),
unsigned32 *status),
Parameters
Input
p_allocate Specifies a memory allocator routine.
p_free Specifies a memory freeing routine. This routine is
used to free memory allocated with the routine
specified by p_allocate.
Output
status Returns the status code from this routine. On
successful completion, the routine returns rpc_s_ok.
Otherwise, it returns an error.
Usage
The rpc_sm_set_client_alloc_free routine overrides the default
routines that the client stub uses to manage memory.
Application Note: The default memory management routines are ISO
malloc and ISO free, except when the remote call occurs
within manager code; in which case, the default memory
management routines are rpc_sm_allocate and rpc_sm_free.
Related Information
Routines:
rpc_sm_allocate
rpc_sm_free
ΓòÉΓòÉΓòÉ 5.8.124. rpc_sm_set_thread_handle ΓòÉΓòÉΓòÉ
Purpose
Sets a thread handle for the stub memory management environment.
Format
#include <rpc.h>
void rpc_sm_set_thread_handle (
rpc_sm_thread_handle_t id,
unsigned32 *status),
Parameters
Input
id Specifies a thread handle returned by a call to
rpc_sm_set_thread_handle.
Output
status Returns the status code from this routine. On
successful completion, the routine returns rpc_s_ok.
Otherwise, it returns an error.
Usage
An application thread calls rpc_sm_set_thread_handle to set a thread
handle for memory management within the stub memory management
environment. A thread that is managing memory within the stub memory
management scheme calls rpc_sm_get_thread_handle to get a thread
handle for its current stub memory management environment. A thread
that calls rpc_sm_set_thread_handle with this handle is able to use
the same memory management environment.
When multiple threads call rpc_sm_allocate and rpc_sm_free to manage
the same memory, they must share the same thread handle. The thread
that established the stub memory management environment calls
rpc_sm_get_thread_handle to get a thread handle before spawning new
threads that will manage the same memory. The spawned threads then
call rpc_sm_set_thread_handle with the handle provided by the parent
thread.
Application Note: Typically, rpc_sm_set_thread_handle is called by a
thread spawned by a server manager routine. Normally, the
stub sets up the memory management environment for the
manager routine and the manager calls
rpc_sm_get_thread_handle to get a thread handle. Each
spawned thread then calls rpc_sm_get_thread_handle to get
access to the manager's memory management environment.
A thread can also use rpc_sm_get_thread_handle and
rpc_sm_set_thread_handle to save and restore its memory
management environment.
Related Information
Routines:
rpc_sm_get_thread_handle
rpc_sm_allocate
rpc_sm_free
ΓòÉΓòÉΓòÉ 5.8.125. rpc_sm_swap_client_alloc_free ΓòÉΓòÉΓòÉ
Purpose
Exchanges the current memory allocation and freeing mechanism used by
the client stubs with one supplied by the client.
Format
#include <rpc.h>
void rpc_sm_swap_client_alloc_free
idl_void_p_t (*p_allocate) ( unsigned long size),
void (p_free) (idl_void_p_t ptr)
idl_void_p_t (**p_p_old_allocate) (unsigned long size),
void (**p_p_old_free) ( idl_void_p_t ptr)
unsigned32 *status),
Parameters
Input
p_allocate Specifies a new memory allocation routine.
p_free Specifies a new memory freeing routine.
Output
p_p_old_allocate Returns the memory allocation routine in use before
the call to this routine.
p_p_old_free Returns the memory freeing routine in use before the
call to this routine.
status Returns the status code from this routine. On
successful completion, the routine returns rpc_s_ok.
Otherwise, it returns an error.
Usage
The rpc_sm_swap_client_alloc_free routine exchanges the current
allocating and freeing mechanisms used by the client stubs for
routines supplied by the caller.
Related Information
Routines:
rpc_sm_allocate
rpc_sm_free
rpc_sm_set_client_alloc_free
ΓòÉΓòÉΓòÉ 5.8.126. rpc_ss_allocate ΓòÉΓòÉΓòÉ
Purpose
Allocates memory within the RPC stub memory management scheme. This
routine is used by server or possibly by client applications.
Format
#include <dce/rpc.h>
idl_void_p_t rpc_ss_allocate (idl_size_t size);
Parameters
Input
size Specifies, in bytes, the size of memory to be
allocated. Note that in ANSI standard C environments,
idl_void_p_t is defined as void * and in other
environments is defined as char *.
Usage
Usually, the rpc_ss_allocate routine is used in the manager code that
is called from a server stub. Memory allocated by rpc_ss_allocate is
released by the server stub after marshalling any output parameters
at the end of the remote call in which the memory was allocated. If
you want to release memory allocated by rpc_ss_allocate before
returning from the manager code, use rpc_ss_free.
You can also use rpc_ss_free in manager code to release memory
pointed to by a full pointer (ptr) in an input parameter.
When the server uses rpc_ss_allocate, the server stub creates the
environment the routine needs. If the parameters of the operation
include any pointers other than those used for passing parameters by
reference, the environment is set up automatically.
If you need to use rpc_ss_allocate in a manager code routine that
does not have a pointer in any of its parameters, use an ACF and
apply the enable_allocate attribute to the relevant operation. This
causes the generated server stub to set up the necessary environment.
Note that memory allocated by allocators other than rpc_ss_allocate
is not released when the operation on the server side finishes
running.
If you want to use rpc_ss_allocate outside the code called from a
server stub, you must first create an environment for it by calling
rpc_ss_enable_allocate.
See the DCE for OS/2 Warp: Application Development Guide - Core
Components for more information.
Related Information
Routines:
rpc_ss_free
rpc_ss_enable_allocate
rpc_ss_disable_allocate
rpc_ss_get_thread_handle
rpc_ss_set_thread_handle
ΓòÉΓòÉΓòÉ 5.8.127. rpc_ss_bind_authn_client ΓòÉΓòÉΓòÉ
Purpose
Authenticates a client's identity to a server from a client stub.
Format
#include <rpc.h>
void rpc_ss_bind_authn_client(
rpc_binding_handle_t *binding,
if_handle_t if_handle,
error_status_t *status);
Parameters
Input/Output
binding A pointer to the server binding handle for the remote
procedure call where the routine adds authentication
and authorization context.
Input
if_handle A stub-generated data structure that specifies the
interface of interest. The routine can use this
parameter to resolve a partial binding or to
distinguish between interfaces.
Output
status Returns the status code from this routine. On
successful completion, the routine returns rpc_s_ok.
Otherwise, it returns rpc_s_no_more_bindings, which
directs the client stub not to look for another server
binding.
Usage
The rpc_ss_bind_authn_client routine is a DCE-supplied binding
callout routine for use with the binding_callout ACF interface
attribute.
The binding_callout attribute enables applications to specify the
name of a routine that the client stub calls automatically to modify
a server binding handle with additional information before it
initiates a remote procedure call. This attribute is especially
useful for applications using the automatic binding method, where it
is the client stub that obtains the binding handle, rather than the
application code. The binding_callout attribute provides these
applications with a way to gain access to a server binding handle
from the client stub, because the handle is not accessible from the
application code.
Applications can specify rpc_ss_bind_authn_client to the
binding_callout ACF interface attribute in order to authenticate the
client's identity to a server from the client stub before the remote
procedure call to the server is initiated. This routine performs
one-way authentication: the client does not care which server
principal receives the remote procedure call request, but the server
verifies that the client is who the client claims to be.
The routine sets the protection level used, the authentication
identity, and the authentication service used to their default
values; see the rpc_binding_set_auth_info routine for more
information on these default values. It sets the authorization
service to perform authorization based on the client's principal
name.
Applications can also specify user-written binding callout routines
with the binding_callout attribute to modify server binding handles
from client stubs with other types of information. See the DCE for
OS/2 Warp: Application Development Guide - Core Components for more
information on using the binding_callout ACF attribute.
Related Information
Routines:
rpc_binding_set_auth_info
rpc_ep_resolve_binding
rpc_mgmt_inq_server_princ_name
ΓòÉΓòÉΓòÉ 5.8.128. rpc_ss_client_free ΓòÉΓòÉΓòÉ
Purpose
Frees memory returned from a client stub. This routine is used by
client applications.
Format
#include <dce/rpc.h>
void_rpc_ss_client_free ( idl_void_p_t node_to_free);
Parameters
Input
node_to_free Identifies a pointer to memory returned from a client
stub.
Usage
The rpc_ss_client_free routine releases memory allocated and returned
from a client stub. The thread calling rpc_ss_client_free must have
the same thread handle as the thread that made the remote procedure
call.
This routine enables a routine to deallocate dynamically allocated
memory returned by a remote procedure call without knowledge of the
memory management environment from which it was called.
Related Information
Routines:
rpc_ss_free
rpc_ss_get_thread_handle
rpc_ss_set_client_alloc_free
rpc_ss_set_thread_handle
rpc_ss_swap_client_alloc_free
ΓòÉΓòÉΓòÉ 5.8.129. rpc_ss_destroy_client_context ΓòÉΓòÉΓòÉ
Purpose
Reclaims the client memory resources for the context handle and sets
the context handle to NULL. This routine is used by client
applications.
Format
#include <dce/rpc.h>
void rpc_ss_destroy_client_context(void *p_unusable_context_handle);
Parameters
Input
p_unusable_context_handle Specifies the context handle that can no
longer be accessed.
Usage
The rpc_ss_destroy_client_context routine is used by the client
application to reclaim the client resources used in maintaining an
active context handle. Call this only after a communications error
makes the context handle unusable. When rpc_ss_destroy_client_context
reclaims the memory resources, it also sets the context handle to
NULL.
The rpc_ss_destroy_client_context routine raises no exceptions.
ΓòÉΓòÉΓòÉ 5.8.130. rpc_ss_disable_allocate ΓòÉΓòÉΓòÉ
Purpose
Releases resources and allocated memory. This routine is used by
client applications.
Format
#include <dce/rpc.h>
void rpc_ss_disable_allocate (void);
Usage
The rpc_ss_disable_allocate routine releases (disables) all resources
acquired by a call to rpc_ss_enable_allocate, and any memory
allocated by calls to rpc_ss_allocate after the call to
rpc_ss_enable_allocate was made.
The rpc_ss_enable_allocate and rpc_ss_disable_allocate routines must
be used in matching pairs.
For information about rules for using memory management routines, see
the DCE for OS/2 Warp: Application Development Guide - Core
Components.
Related Information
Routines:
rpc_ss_allocate
rpc_ss_enable_allocate
Book:
DCE for OS/2 Warp: Application Development Guide - Core Components
ΓòÉΓòÉΓòÉ 5.8.131. rpc_ss_enable_allocate ΓòÉΓòÉΓòÉ
Purpose
Enables the allocation of memory by rpc_ss_allocate when not in
manager code. This routine is used by client applications.
Format
#include <dce/rpc.h>
void rpc_ss_enable_allocate(void);
Usage
In sophisticated servers, it may be necessary to call manager code
routines from different environments. This occurs, for example, when
the application is both a client and a server of the same interface.
Therefore, a manager code routine may need to be called both by the
application code and by the stub code. If code, other than manager
code, calls rpc_ss_allocate it must first call rpc_ss_enable_allocate
to initialize the memory management environment that rpc_ss_allocate
uses.
For information about rules for using memory management routines, see
the DCE for OS/2 Warp: Application Development Guide - Core
Components.
Return Codes
An exception, rpc_x_no_memory, when there is insufficient memory
available to set up necessary data structures.
Related Information
Routines:
rpc_ss_allocate
rpc_ss_disable_allocate
Books:
DCE for OS/2 Warp: Application Development Guide - Core Components
ΓòÉΓòÉΓòÉ 5.8.132. rpc_ss_free ΓòÉΓòÉΓòÉ
Purpose
Frees memory allocated by rpc_ss_allocate. This routine is used by
server or possibly by client applications.
Format
#include <dce/rpc.h>
void rpc_ss_free (idl_void_p_t node_to_free);
Parameters
Input
node_to_free Specifies a pointer to memory allocated by
rpc_ss_allocate.
Note that in ANSI standard C environments, idl_void_p_t is defined as
void * and in other environments is defined as char *.
Usage
This routine releases memory allocated by rpc_ss_allocate. The thread
calling rpc_ss_free must have the same thread handle as the thread
that allocated the memory with rpc_ss_allocate. Use it only in an
environment where rpc_ss_allocate is used.
If the manager code allocates memory with rpc_ss_allocate and the
memory is not released by rpc_ss_free during the running of the
manager code, the server stub automatically releases the memory when
the manager code finishes running and returns control to the stub.
Manager code can also use rpc_ss_free to release memory that is
pointed to by a full pointer in an input parameter.
For information about rules for using memory management routines, see
DCE for OS/2 Warp: Application Development Guide - Core Components.
Related Information
Routines:
rpc_ss_allocate
rpc_ss_get_thread_handle
rpc_ss_set_thread_handle
Book:
DCE for OS/2 Warp: Application Development Guide - Core Components
ΓòÉΓòÉΓòÉ 5.8.133. rpc_ss_get_thread_handle ΓòÉΓòÉΓòÉ
Purpose
Gets a thread handle for the manager code before it spawns additional
threads or for the client code when it becomes a server. This routine
is used by server or possibly by client applications.
Format
#include <dce/rpc.h>
rpc_ss_thread_handle_t rpc_ss_get_thread_handle(void);
Usage
The rpc_ss_get_thread_handle routine is used by a server manager
thread when it spawns additional threads. To spawn additional threads
that are able to perform memory management, the server manager code
calls rpc_ss_get_thread_handle and passes the thread handle to each
spawned thread. Each spawned thread that uses the rpc_ss_allocate and
rpc_ss_free for memory management must first call the
rpc_ss_set_thread_handle routine, using the handle obtained by the
original manager thread.
The rpc_ss_get_thread_handle routine can also be used when a program
changes from being a client to being a server. The program gets a
handle on its environment as a client by calling
rpc_ss_get_thread_handle. When the program reverts to being a client
it reestablishes the client environment by calling
rpc_ss_set_thread_handle, supplying the previously obtained handle as
a parameter.
Return Codes
This routine returns a thread handle to the rpc_sm_thread_handle_t
variable.
Example
This routine determines the thread handle, creates a thread, and
passes the thread handle to the thread so it can share the memory
management environment of the calling thread.
#include <pthread.h>
#include <idlbase.h>
pthread_t Launch_thread(
int (*routine_to_launch)(
pthread_addr_t th
)
)
{
rpc_ss_thread_handle_t th = rpc_ss_get_thread_handle;
pthread_t t;
/*
* Create the thread and pass to it the thread handle
* so it can use rpc_ss_set_thread_handle.
*/
pthread_create (&t, pthread_attr_default,
(pthread_startroutine_t)routine_to_launch,
(pthread_addr_t)th);
return t;
}
Related Information
Routines:
rpc_ss_allocate
rpc_ss_free
rpc_ss_set_thread_handle
ΓòÉΓòÉΓòÉ 5.8.134. rpc_ss_set_client_alloc_free ΓòÉΓòÉΓòÉ
Purpose
Sets the memory allocation and freeing mechanism used by the client
stubs, which overrides the default routines the client stub uses to
manage memory for pointed-to nodes. This routine is used by client
applications.
Format
#include <dce/rpc.h>
void rpc_ss_set_client_alloc_free(
idl_void_p_t (*p_allocate) ( idl_size_t size),
void (*p_free) (idl_void_p_t ptr)
);
Parameters
Input
p_allocate Specifies a pointer to a routine that has the same
procedure declaration as the C language malloc routine
and that is used by the client stub to allocate memory.
p_free Specifies a pointer to a routine that has the same
procedure declaration as the C language free routine
and that is used to free memory that was allocated
using the routine pointed at by p_allocate.
Note that in ANSI standard C environments, idl_void_p_t is defined as
void * and in other environments is defined as char *.)
Usage
The rpc_ss_set_client_alloc_free routine overrides the default
routines that the client stub uses to manage memory for pointed-to
nodes. The default memory management routines are malloc and free,
except when the remote call occurs within manager code; in which
case, the default memory management routines are rpc_ss_allocate and
rpc_ss_free.
For information about rules for using memory management routines, see
the DCE for OS/2 Warp: Application Development Guide - Core
Components.
Return Codes
This routine returns an exception, rpc_x_no_memory, when there is
insufficient memory available to set up necessary data structures.
Related Information
Routines:
rpc_ss_allocate
rpc_ss_free
Books:
DCE for OS/2 Warp: Application Development Guide - Core Components
ΓòÉΓòÉΓòÉ 5.8.135. rpc_ss_set_thread_handle ΓòÉΓòÉΓòÉ
Purpose
Sets the thread handle for either a newly created spawned thread or
for a server that was formerly a client and is ready to be a client
again. This routine is used by server or possibly by client
applications.
Format
#include <dce/rpc.h>
void rpc_ss_set_thread_handle (
rpc_ss_thread_handle_t id);
Parameters
Input
id A thread handle returned by a call to
rpc_ss_get_thread_handle.
Usage
The rpc_ss_set_thread_handle routine is used by a thread spawned in
the manager code to associate itself with the main RPC manager
thread. Each spawned thread that uses rpc_ss_allocate and rpc_ss_free
for memory management must call rpc_ss_set_thread_handle, using the
handle that the main RPC manager thread obtained through
rpc_ss_get_thread_handle.
The rpc_ss_set_thread_handle routine can also be used by a program
that originally was a client, then became a server, and is now
reverting to a client. The program must re-establish the client
environment by calling rpc_ss_set_thread_handle, and by supplying the
handle it received (through rpc_ss_get_thread_handle) prior to
becoming a server as a parameter.
Return Codes
This routine returns an exception, rpc_x_no_memory, when there is
insufficient memory available to set up necessary data structures.
Examples
When this routine is invoked within a spawned thread, its parameter
is the thread handle of the calling thread. This example assumes the
data passed to the thread consists of only the middle thread.
#include <pthread.h>
#include <dce/idlbase.h>
int helper_thread (
pthread_addr_t th
)
{
/*
* Set the memory management environment to match the parent environment.
*/
rpc_ss_set_thread_handle(rpc_ss_thread_handle_t)th;
/*
* Real work of this thread follows here ...
*/
}
Related Information
Routines:
rpc_ss_get_thread_handle
rpc_ss_allocate
rpc_ss_free
Book:
DCE for OS/2 Warp: Application Development Guide - Core Components
ΓòÉΓòÉΓòÉ 5.8.136. rpc_ss_swap_client_alloc_free ΓòÉΓòÉΓòÉ
Purpose
Exchanges the current memory allocation and freeing mechanism used by
the client stubs with one supplied by the client. This routine is
used by client applications.
Format
#include <dce/rpc.h>
void rpc_ss_swap_client_alloc_free (
idl_void_p_t (* p_allocate) ( idl_size_t size),
void (*p_free) (idl_void_p_t ptr),
idl_void_p_t (**p_p_old_allocate) (idl_size_t size),
void (**p_p_old_free) (idl_void_p_t ptr)
);
Parameters
Input
p_allocate Specifies a pointer to a routine that has the same
procedure declaration as the malloc routine and that is
used for allocating client stub memory.
p_free Specifies a pointer to a routine that has the same
procedure declaration as the free routine and that is
used for freeing client stub memory.
Output
p_p_old_allocate Specifies a pointer to a pointer to a routine that
has the same procedure declaration as the malloc
routine. A pointer to the routine that was previously
used to allocate client stub memory is returned in this
parameter.
p_p_old_free Specifies a pointer to a pointer to a routine that has
the same procedure declaration as the free routine. A
pointer to the routine that was previously used to free
client stub memory is returned in this parameter.
Note that in ANSI standard C environments, idl_void_p_t is defined as
void * and in other environments is defined as char *.
Usage
The rpc_ss_swap_client_alloc_free routine exchanges the current
client allocating and freeing mechanism used by the client stubs for
one supplied by the caller. If it is appropriate for the client code
called by an application to use a certain memory allocation and
freeing mechanism, regardless of its caller's state, the client code
can swap its own mechanism into place on entry, replacing its
caller's mechanism. It can then swap the caller's mechanism back into
place prior to returning.
See the DCE for OS/2 Warp: Application Development Guide - Core
Components.
Return Codes
This routine returns an exception, rpc_x_no_memory, when there is
insufficient memory available to set up necessary data structures.
Related Information
Routines:
rpc_ss_allocate
rpc_ss_free
rpc_ss_set_client_alloc_free
Book:
DCE for OS/2 Warp: Application Development Guide - Core Components
ΓòÉΓòÉΓòÉ 5.8.137. rpc_string_binding_compose ΓòÉΓòÉΓòÉ
Purpose
Combines the components of a string binding into a string binding.
This routine is used by client or server applications.
Format
#include <dce/rpc.h>
void rpc_string_binding_compose(
unsigned_char_t *obj_uuid,
unsigned_char_t *protseq,
unsigned_char_t *network_addr,
unsigned_char_t *endpoint,
unsigned_char_t *options,
unsigned_char_t **string_binding,
unsigned32 *status );
Parameters
Input
obj_uuid Specifies a NULL-terminated string representation of an
object UUID.
protseq Specifies a NULL-terminated string representation of a
protocol sequence.
network_addr Specifies a NULL-terminated string representation of a
network address.
endpoint Specifies a NULL-terminated string representation of an
endpoint.
options Specifies a NULL-terminated string representation of
network options.
Output
string_binding Returns a pointer to a NULL-terminated string
representation of a binding handle.
Specify NULL to prevent the routine from returning this
parameter. In this case, the application does not call
rpc_string_free.
status Returns the status code from this routine. On
successful completion, the routine returns rpc_s_ok.
Otherwise, it returns an error.
Usage
The rpc_string_binding_compose routine combines string binding handle
components into a string binding handle.
The RPC runtime allocates memory for the string returned in the
string_binding parameter. The application calls rpc_string_free to
deallocate that memory.
Specify NULL or provide a null string (\0) for each input string that
has no data.
Related Information
Routines:
rpc_binding_from_string_binding
rpc_binding_to_string_binding
rpc_string_binding_parse
rpc_string_free
uuid_to_string
ΓòÉΓòÉΓòÉ 5.8.138. rpc_string_binding_parse ΓòÉΓòÉΓòÉ
Purpose
Returns, as separate strings, the components of a string binding.
This routine is used by client or server applications.
Format
#include <dce/rpc.h>
void rpc_string_binding_parse(
unsigned_char_t *string_binding,
unsigned_char_t **obj_uuid,
unsigned_char_t **protseq,
unsigned_char_t **network_addr,
unsigned_char_t **endpoint,
unsigned_char_t **network_options,
unsigned32 *status);
Parameters
Input
string_binding Specifies a NULL-terminated string representation of a
binding.
Output
obj_uuid Returns a pointer to a NULL-terminated string
representation of an object UUID.
Specify NULL to prevent the routine from returning this
parameter. In this case, the application does not call
rpc_string_free.
protseq Returns a pointer to a NULL-terminated string
representation of a protocol sequence.
Specify NULL to prevent the routine from returning this
parameter. In this case, the application does not call
rpc_string_free.
network_addr Returns a pointer to a NULL-terminated string
representation of a network address.
Specify NULL to prevent the routine from returning this
parameter. In this case, the application does not call
rpc_string_free.
endpoint Returns a pointer to a NULL-terminated string
representation of an endpoint.
Specify NULL to prevent the routine from returning this
parameter. In this case, the application does not call
rpc_string_free.
network_options Returns a pointer to a NULL-terminated string
representation of network options.
Specify NULL to prevent the routine from returning this
parameter. In this case, the application does not call
rpc_string_free.
status Returns the status code from this routine. On
successful completion, the routine returns rpc_s_ok.
Otherwise, it returns rpc_s_invalid_string_binding,
which indicates that the string binding is not valid.
Usage
The rpc_string_binding_parse routine parses a string representation
of a binding handle into its component fields.
The RPC runtime allocates memory for each component string the
routine returns. The application calls rpc_string_free once for each
returned string to deallocate the memory for that string.
If any field of the string_binding is empty, rpc_string_binding_parse
returns the empty string in the corresponding output parameter.
Related Information
Routines:
rpc_binding_from_string_binding
rpc_binding_to_string_binding
rpc_string_binding_compose
rpc_string_free
uuid_from_string
ΓòÉΓòÉΓòÉ 5.8.139. rpc_string_free ΓòÉΓòÉΓòÉ
Purpose
Frees a character string allocated by the RPC runtime. This routine
is used by client, server, or management applications.
Format
#include <dce/rpc.h>
void rpc_string_free(
unsigned_char_t **string,
unsigned32 *status);
Parameters
Input/Output
string Specifies the address of the pointer to the character
string to free.
The value NULL is returned.
Output
status Returns the status code from this routine. On
successful completion, the routine returns rpc_s_ok.
Otherwise, it returns an error.
Usage
The rpc_string_free routine deallocates the memory occupied by a
character string returned by the RPC runtime.
An application must call this routine once for each character string
allocated and returned by calls to other RPC runtime routines. These
routines are listed in the "Related Information" section.
Related Information
Routines:
rpc_binding_inq_auth_client
rpc_binding_inq_auth_info
rpc_binding_to_string_binding
rpc_mgmt_ep_elt_inq_next
rpc_mgmt_inq_server_princ_name
rpc_ns_binding_inq_entry_name
rpc_ns_entry_expand_name
rpc_ns_group_mbr_inq_next
rpc_ns_profile_elt_inq_next
rpc_string_binding_compose
rpc_string_binding_parse
sec_rgy_site_binding_get_info
uuid_to_string
ΓòÉΓòÉΓòÉ 5.8.140. rpc_tower_to_binding ΓòÉΓòÉΓòÉ
Purpose
Returns a binding handle from a tower representation.
Format
#include <dce/rpc.h>
void rpc_tower_to_binding(
byte_p_t prot_tower,
rpc_binding_handle_t *binding,
unsigned32 *status);
Parameters
Input
prot_tower Specifies a single protocol tower to convert to a
binding handle.
Output
binding Returns the server binding handle.
status Returns the status code from this routine. On
successful completion, the routine returns rpc_s_ok.
Otherwise, it returns one of the following errors:
rpc_s_invalid_arg The argument is not valid.
rpc_s_invalid_endpoint_format The endpoint format
is not valid.
rpc_s_protseq_not_supported The protocol sequence
is not supported on this host.
Usage
The rpc_tower_to_binding routine creates a server binding handle that
is a canonical representation of a protocol tower.
When the application finishes using the binding parameter, it calls
the rpc_binding_free routine to release the memory used by the
binding handle.
Related Information
Routines:
rpc_binding_copy
rpc_binding_free
rpc_tower_vector_free
rpc_tower_vector_from_binding
ΓòÉΓòÉΓòÉ 5.8.141. rpc_tower_vector_free ΓòÉΓòÉΓòÉ
Purpose
Releases memory associated with a tower vector.
Format
#include <dce/rpc.h>
void rpc_tower_vector_free(
rpc_tower_vector_p_t *twr_vector,
unsigned32 *status);
Parameters
Input
twr_vector Specifies the tower vector to be freed. On return, its
value is NULL.
Output
status Returns the status code from this routine. The status
code is either rpc_s_ok or a value returned from a
called routine.
Usage
The rpc_tower_vector_free routine releases memory associated with a
tower vector, including the towers as well as the vector.
Related Information
Routines:
rpc_binding_copy
rpc_binding_free
rpc_tower_vector_from_binding
rpc_tower_to_binding
ΓòÉΓòÉΓòÉ 5.8.142. rpc_tower_vector_from_binding ΓòÉΓòÉΓòÉ
Purpose
Creates a tower vector from a binding handle.
Format
#include <dce/rpc.h>
void rpc_tower_vector_from_binding(
rpc_if_handle_t if_spec,
rpc_binding_handle_t binding,
rpc_tower_vector_p_t *twr_vector,
unsigned32 *status);
Parameters
Input
if_spec The interface specification that is combined with a
binding handle to form a tower vector.
binding The binding handle that is combined with an interface
specification to form a tower vector.
Output
twr_vector Returns the allocated tower vector.
status Returns the status code from this routine. The status
code is either rpc_s_ok, or rpc_s_no_interfaces, or a
value returned from a called routine.
Usage
The rpc_tower_vector_from_binding routine creates a vector of towers
from a binding handle. After the caller is finished with the tower
vector, the rpc_tower_vector_free routine must be called to release
the memory used by the vector.
Related Information
Routines:
rpc_binding_copy
rpc_binding_free
rpc_tower_to_binding
rpc_tower_vector_free
ΓòÉΓòÉΓòÉ 5.8.143. uuid_compare ΓòÉΓòÉΓòÉ
Purpose
Compares two UUIDs and determines their order. This routine is used
by client, server, or management applications.
Format
#include <dce/uuid.h>
signed32 uuid_compare(
uuid_t *uuid1,
uuid_t *uuid2,
unsigned32 *status);
Parameters
Input
uuid1 Specifies a pointer to a UUID. This UUID is compared
with the UUID specified in uuid2. Use the value NULL to
specify a nil UUID for this parameter.
uuid2 Specifies a pointer to a UUID. This UUID is compared
with the UUID specified in uuid1. Use the value NULL to
specify a nil UUID for this parameter.
Output
status Returns the status code from this routine. On
successful completion, the routine returns uuid_s_ok.
Otherwise, it returns uuid_s_bad_version, which
indicates a bad UUID version.
Usage
The uuid_compare routine compares two UUIDs and determines their
order. A nil UUID is considered the first element in order. The order
of UUIDs is defined by the RPC architecture and is not a temporal
(related to time) ordering. Comparing two specific UUIDs always
returns the same result, regardless of the implementation or system
architecture.
You can use this routine to sort data with UUIDs as a key.
Return Codes
Returns one of the following constants
-1 The uuid1 parameter precedes the uuid2 parameter in order.
0 The uuid1 parameter is equal to the uuid2 parameter in order.
1 The uuid1 parameter follows the uuid2 parameter in order.
Note that a value of 0 (zero) has the same meaning as if
uuid_equal(&uuid1, &uuid2) returned a value of TRUE.
A nil UUID is the first UUID in order. This means the following:
o If uuid1 is NULL and uuid2 is non-nil, the routine returns -1.
o If uuid1 is NULL and uuid2 is NULL, the routine returns 0.
o If uuid1 is non-nil and uuid2 is NULL, the routine returns 1.
Related Information
Routines:
uuid_equal
uuid_is_nil
ΓòÉΓòÉΓòÉ 5.8.144. uuid_create ΓòÉΓòÉΓòÉ
Purpose
Creates a new UUID. This routine is used by client, server, or
management applications.
Format
#include <dce/uuid.h>
void uuid_create(
uuid_t *uuid,
unsigned32 *status);
Parameters
Output
uuid Returns the new UUID.
status Returns the status code from this routine. On
successful completion, the routine returns uuid_s_ok.
Otherwise, it returns uuid_s_no_address, which
indicates that it cannot get the Ethernet hardware
address.
Usage
The uuid_create routine creates a new UUID.
Related Information
Routines:
uuid_create_nil
uuid_from_string
uuid_to_string
ΓòÉΓòÉΓòÉ 5.8.145. uuid_create_nil ΓòÉΓòÉΓòÉ
Purpose
Creates a nil UUID. This routine is used by client, server, or
management applications.
Format
#include <dce/uuid.h>
void uuid_create_nil(
uuid_t *nil_uuid,
unsigned32 *status);
Parameters
Output
nil_uuid Returns a nil UUID.
status Returns the status code from this routine. On
successful completion, the routine returns uuid_s_ok.
Otherwise, it returns an error.
Usage
The uuid_create_nil routine creates a nil UUID.
Related Information
Routines:
uuid_create
ΓòÉΓòÉΓòÉ 5.8.146. uuid_equal ΓòÉΓòÉΓòÉ
Purpose
Determines if two UUIDs are equal. This routine is used by client,
server, or management applications.
Format
#include <dce/uuid.h>
boolean32 uuid_equal(
uuid_t *uuid1,
uuid_t *uuid2,
unsigned32 *status);
Parameters
Input
uuid1 Specifies a pointer to a UUID. This UUID is compared
with the UUID specified in uuid2. Supply the value NULL
to specify a nil UUID for this parameter.
uuid2 Specifies a pointer to a UUID. This UUID is compared
with the UUID specified in uuid1. Supply the value NULL
to specify a nil UUID for this parameter.
Output
status Returns the status code from this routine. On
successful completion, the routine returns uuid_s_ok.
Otherwise, it returns uuid_s_bad_version, which
indicates that the UUID version is not valid.
Usage
The uuid_equal routine compares two UUIDs and determines if they are
equal.
Return Codes
The possible return values and their meanings are as follows:
TRUE The uuid1 parameter is equal to the uuid2 parameter. The
status parameter contains the status code uuid_s_ok.
FALSE The uuid1 parameter is not equal to the uuid2 parameter.
Related Information
Routines:
uuid_compare
ΓòÉΓòÉΓòÉ 5.8.147. uuid_from_string ΓòÉΓòÉΓòÉ
Purpose
Converts a string UUID to its binary representation. This routine is
used by client, server, or management applications.
Format
#include <dce/uuid.h>
void uuid_from_string(
unsigned_char_t *string_uuid,
uuid_t *uuid,
unsigned32 *status);
Parameters
Input
string_uuid Specifies a string representation of a UUID. Supply the
value NULL or the NULL string (\0) to specify a nil
UUID.
Output
uuid Returns the binary form of the UUID specified by the
string_uuid parameter into the address specified by
this parameter.
status Returns the status code from this routine. On
successful completion, the routine returns uuid_s_ok.
Otherwise, it returns one of the following errors:
uuid_s_bad_version Bad UUID version.
uuid_s_invalid_string_uuid The string UUID format
is not valid.
Usage
An application calls the uuid_from_string routine to convert a string
UUID to its binary representation.
Related Information
Routines:
uuid_to_string
ΓòÉΓòÉΓòÉ 5.8.148. uuid_hash ΓòÉΓòÉΓòÉ
Purpose
Creates a hash value for a UUID. This routine is used by client,
server, or management applications.
Format
#include <dce/uuid.h>
unsigned16 uuid_hash(
uuid_t *uuid,
unsigned32 *status);
Parameters
Input
uuid Specifies the UUID for which a hash value is created.
Supply NULL to specify a nil UUID for this parameter.
Output
status Returns the status code from this routine. On
successful completion, the routine returns uuid_s_ok.
Otherwise, it returns the following error:
uuid_s_bad_version Bad UUID version.
Usage
The uuid_hash routine generates a hash value for a specified UUID.
Note that the return value for a single uuid value can differ across
platforms.
Return Codes
This routine returns a hash value for the specified UUID.
ΓòÉΓòÉΓòÉ 5.8.149. uuid_is_nil ΓòÉΓòÉΓòÉ
Purpose
Determines if a UUID is nil. This routine is used by client, server,
or management applications.
Format
#include <dce/uuid.h>
boolean32 uuid_is_nil(
uuid_t *uuid,
unsigned32 *status);
Parameters
Input
uuid Specifies a UUID to test as a nil UUID. Supply NULL to
specify a nil UUID for this parameter.
Output
status Returns the status code from this routine. On
successful completion, the routine returns uuid_s_ok.
Otherwise, it returns uuid_s_bad_version, which
indicates a bad UUID version.
Usage
The uuid_is_nil routine determines whether the specified UUID is a
nil UUID. This routine yields the same result as though an
application:
o Called the uuid_create_nil routine.
o Called the uuid_equal routine to compare the returned nil UUID
to the UUID specified in the uuid parameter.
Return Codes
The possible return values and their meanings are as follows:
TRUE The uuid parameter is a nil UUID. The status parameter
contains the status code uuid_s_ok.
FALSE The uuid parameter is not a nil UUID.
Related Information
Routines:
uuid_compare
uuid_create_nil
uuid_equal
ΓòÉΓòÉΓòÉ 5.8.150. uuid_to_string ΓòÉΓòÉΓòÉ
Purpose
Converts a UUID from a binary representation to a string
representation. This routine is used by client, server, or management
applications.
Format
#include <dce/uuid.h>
void uuid_to_string(
uuid_t *uuid,
unsigned_char_t **string_uuid,
unsigned32 *status);
Parameters
Input
uuid Specifies a UUID in its binary format. Supply NULL to
specify a nil UUID for this parameter.
Output
string_uuid Returns a pointer to the string representation of the
UUID specified in the uuid parameter. Specify NULL for
this parameter to prevent the routine from returning
this information.
status Returns the status code from this routine. On
successful completion, the routine returns uuid_s_ok.
Otherwise, it returns uuid_s_bad_version, which
indicates that the UUID version is not valid.
Usage
The uuid_to_string routine converts a UUID from its binary
representation to its string representation.
The RPC runtime allocates memory for the string returned in the
string_uuid parameter. The application calls rpc_string_free to
deallocate that memory. It is not necessary to call rpc_string_free
when you supply NULL for the string_uuid parameter.
Related Information
Routines:
rpc_string_free
uuid_from_string
ΓòÉΓòÉΓòÉ 6. Directory Service API ΓòÉΓòÉΓòÉ
This section describes the directory service routines and header files. This
interface allows access to Cell Directory Service (CDS) objects, and comprises
two parts, the X/OPEN Directory Services (XDS) and the X/Open Object Management
(XOM) interfaces.
XDS Routines Describes the XDS routines.
XDS Header Files Describes the XDS header files included in the XDS routines.
X/OPEN OSI-Abstract-Data Manipulation Routines Describes the XOM routines.
XOM Header Files Describes the xom.h header files.
ΓòÉΓòÉΓòÉ 6.1. XDS Routines ΓòÉΓòÉΓòÉ
This is an introduction to X/OPEN Directory Services (XDS) routines. XDS
provides a C language binding.
Note: This service interface only supports access to CDS objects. Access to
GDS objects is not supported.
The service interface comprises a number of routines whose descriptions are
summarized in the following list:
ds_adbandon This routine is not supported.
ds_add_entry Adds a leaf entry to the directory information tree
(DIT).
ds_bind Opens a session with a directory user agent.
ds_compare Compares a purported attribute value with the
attribute value stored in the directory for a
particular entry.
ds_initialize Initializes the interface.
ds_list Enumerates the immediate subordinates of a particular
directory entry.
ds_modify_entry Performs a modification of a directory entry.
ds_modify_rdn This routine is not supported.
ds_read Queries information on a directory entry by name.
ds_receive_result This routine is not supported.
ds_remove_entry Removes a leaf entry from the directory information
tree (DIT).
ds_search This routine is not supported.
ds_shutdown Shuts down the interface.
ds_unbind Unbinds from a directory session.
ds_version Negotiates features of the interface and service.
dsX_extract_attr_values Extracts attribute values from an OM object.
The Distributed Computing Environment (DCE) XDS interface does not support
asynchronous operations within the same thread. Therefore, ds_abandon is
redundant. A ds_abandon call returns with a DS_C_ABANDON_FAILED
(DS_E_TOO_LATE) error. Refer to the DCE for OS/2 Warp: Application Development
Guide - Core Components for information on how to abandon an operation. For
ds_receive_result, if there are any outstanding operations (when multiple
threads issue XDS calls in parallel), this routine returns DS_SUCCESS with the
completion_flag_return parameter set to DS_OUTSTANDING_OPERATIONS. If no XDS
calls are outstanding, then ds_receive_result returns with DS_status set to
DS_NO_OUTSTANDING_OPERATION.
The following restrictions apply to this service interface when accessing the
Cell Directory Service (CDS):
o CDS does not support the ds_modify_rdn or ds_search routines. The error
message DS_C_SERVICE_ERROR (DS_E_UNWILLING_TO_PERFORM) is returned if
either of these two routines are attempted on CDS.
o In CDS, no X.500 schema rules apply. There is no:
- Concept of an object class
- Mandatory attributes for a given object
- Set of attributes expressly permitted for a given object
- Predefined definition of single and multivalued attributes
The absence of these schema rules means that errors, which are returned for
breach of schema rules, are not returned.
The CDS naming Directory Information Tree (DIT) is modeled on a typical file
system architecture, where directories are used for storing objects and
directories can contain subdirectories. Leaf objects in the CDS DIT are
similar to X.500 naming objects. However, subtree objects are called
directories as in a file system directory. All new objects must be added to an
existing directory. CDS directory objects cannot be added, removed, modified,
or compared using the XDS programming interface.
In CDS, the naming attribute of an object is not stored in the object.
Consequently, in CDS, ds_read never returns this attribute, and ds_compare
returns with DS_C_ATTRIBUTE_ERROR (DS_E_CONSTRAINT_VIOLATION).
Updates to the directory are not guaranteed to be atomic when using XDS/XOM
over CDS.
Notes
o XDS routines check for NULL pointers and return an error.
o The pointers are checked at the routine interface only. The check is for
NULL only and not for validity.
ΓòÉΓòÉΓòÉ 6.1.1. ds_add_entry ΓòÉΓòÉΓòÉ
Purpose
Adds a leaf entry to the Directory Information Tree (DIT).
Format
#include <xom.h>
#include <xds.h>
DS_status ds_add_entry(
OM_private_object session,
OM_private_object context,
OM_object name,
OM_object entry,
OM_sint *invoke_id_return);
Parameters
Input
session (Object(DS_C_SESSION)). The directory session this
operation is performed against. This must be a private
object.
context (Object(DS_C_CONTEXT)). The directory context to be
used for this operation. This parameter must be a
private object or the DS_DEFAULT_CONTEXT constant.
(Note that DS_SIZE_LIMIT and
DS_DONT_DEREFERENCE_ALIASES do not apply to this
operation.)
name (Object(DS_C_NAME)). The name of the entry to be added.
The immediate superior of the new entry is determined
by removing the last RDN component, which belongs to
the new entry. Any aliases in the name are not
de-referenced.
entry (Object(DS_C_ATTRIBUTE_LIST)). The attribute
information that, together with that from the RDN,
constitutes the entry to be created. Note that an
instance of Object Management (OM) class
DS_C_ENTRY_INFO can be supplied as the value of this
parameter, since DS_C_ENTRY_INFO is a subclass of
DS_C_ATTRIBUTE_LIST.
Output
invoke_id_return (integer). Not supported.
Usage
The ds_add_entry routine adds a leaf entry to the Directory. The
entry can be either an object or an alias.
Notes
Note the following issues for the ds_add_entry operation:
o Only leaf objects (that is, objects that are not CDS directory
objects) can be added to CDS through the XDS interface.
o Only the DS_A_COMMON_NAME and DS_A_MEMBER attributes are valid
for the DS_O_GROUP_OF_NAMES object in CDS.
o GDS-structured attribute types are not supported by CDS. If an
attempt is made to add a GDS-structured attribute type to CDS,
then it returns with a DS_C_ATTRIBUTE_ERROR
(DS_E_CONSTRAINT_VIOLATION).
Since CDS does not implement the X.500 schema rules, some CDS objects
may not contain mandatory attributes like object class and so on.
Return Codes
On successful completion, the routine returns DS_SUCCESS. Otherwise,
it returns one of the following errors:
o DS_C_SYSTEM_ERROR
o The following DS_C_LIBRARY_ERROR errors:
DS_E_BAD_ARGUMENT
DS_E_BAD_CONTEXT
DS_E_BAD_NAME
DS_E_BAD_SESSION
DS_E_MISCELLANEOUS
DS_E_MISSING_TYPE
DS_E_TOO_MANY_OPERATIONS
o The following directory errors:
DS_C_ATTRIBUTE_ERROR
DS_C_NAME_ERROR
DS_C_REFERRAL
DS_C_SECURITY_ERROR
DS_C_SERVICE_ERROR
DS_C_UPDATE_ERROR
Note: DS_C_UPDATE_ERROR (DS_E_AFFECTS_MULTIPLE_DSAS), which is
referred to in the parameter descriptions, need not be
returned if there is local agreement between the DSAs to
allow the entry to be added.
o DS_C_COMMUNICATIONS_ERROR
o The DS_NO_WORKSPACE error constant.
ΓòÉΓòÉΓòÉ 6.1.2. ds_bind ΓòÉΓòÉΓòÉ
Purpose
Opens a session with the Directory.
Format
#include <xom.h>
#include <xds.h>
DS_status ds_bind(
OM_object session,
OM_workspace workspace,
OM_private_object *bound_session_return);
Parameters
Input
session (object(DS_C_SESSION)). Specifies a particular
directory service provider, together with other details
of the service required. This parameter can be either a
public object or a private object. The
DS_DEFAULT_SESSION constant can also be used as the
value of this parameter, causing a new session to be
created with default values for all its OM attributes.
workspace Specifies the workspace (obtained from a call to
ds_initialize) that is to be associated with the
session. All results from directory operations using
this session will be returned as private objects in
this workspace. If the session parameter is a private
object, it must be a private object in this workspace.
Output
bound_session_return (object (DS_C_SESSION)). Upon successful
completion, this parameter contains an instance of a
directory session that can be used as a parameter to
other routines (for example, ds_read). This is a new
private object if the value of the session parameter
was DS_DEFAULT_SESSION or a public object; otherwise,
it is that supplied as a parameter. The routine
supplies default values for any of the OM attributes
that are not present in the session parameter instance
supplied as a parameter. It also sets the value of the
DS_FILE_DESCRIPTOR OM attribute to
DS_NO_VALID_FILE_DESCRIPTOR since this function is not
supported.
Usage
The ds_bind routine sets up a link to the CDS namespace.
Notes
Note that in order to use CDS, ds_bind must be called with the value
of the session parameter set to DS_DEFAULT_SESSION.
Return Codes
On successful completion, the routine returns DS_SUCCESS. Otherwise,
it returns one of the following errors:
o DS_C_SYSTEM_ERROR
o The following DS_C_LIBRARY_ERROR errors:
DS_E_BAD_SESSION
DS_E_BAD_WORKSPACE
DS_E_MISCELLANEOUS
DS_E_NOT_SUPPORTED
DS_E_TOO_MANY_SESSIONS
o The following directory errors:
DS_C_SECURITY_ERROR
DS_C_SERVICE_ERROR
o DS_COMMUNICATIONS_ERROR
o The DS_NO_WORKSPACE error constant.
Related Information
Routines:
ds_unbind
ΓòÉΓòÉΓòÉ 6.1.3. ds_compare ΓòÉΓòÉΓòÉ
Purpose
Compares a purported attribute value with the attribute value stored
in the directory for a particular entry.
Format
#include <xom.h>
#include <xds.h>
DS_status ds_compare(
OM_private_object session,
OM_private_object context,
OM_object name,
OM_object ava,
OM_private_object *result_return,
OM_sint *invoke_id_return);
Parameters
Input
session (Object(DS_C_SESSION)). The directory session against
which this operation is performed. This must be a
private object.
context (Object(DS_C_CONTEXT)). The directory context to be
used for this operation. Note that DS_SIZE_LIMIT does
not apply to this operation. This parameter must be a
private object or the DS_DEFAULT_CONTEXT constant.
name (Object(DS_C_NAME)). The name of the target object
entry. Any aliases in the name are dereferenced unless
prohibited by the DS_DONT_DEREFERENCE_ALIASES service
control attribute of the DS_C_CONTEXT object.
ava (Object(DS_C_AVA)). The attribute value assertion (AVA)
that specifies the attribute type and value to be
compared with those in the entry.
Output
result_return (Object(DS_C_COMPARE_RESULT)). Upon successful
completion, the result contains flags indicating
whether the values matched and whether the comparison
was made against the original entry. It also contains
the distinguished name (DN) of the target object if an
alias is dereferenced.
invoke_id_return (integer). Not supported.
Usage
The ds_compare routine compares the value supplied in the given ava
parameter with the value or values of the same attribute type in the
named entry.
Notes
Note the following issues for the ds_compare operation:
o In CDS, the naming attribute of an object is not stored in the
attribute list of an object. Thus in CDS, a ds_compare of the
purported naming attribute value with the naming attribute value
of the directory object always fails to match.
o GDS-structured types are not supported by CDS. If a
GDS-structured attribute type is used as a parameter to
ds_compare on a CDS object, then it returns with the error
DS_C_ATTRIBUTE_ERROR (DS_E_CONSTRAINT_VIOLATION).
o In CDS, ds_compare can only be used on leaf objects. Otherwise,
a DS_C_NAME_ERROR (DS_E_NO_SUCH_OBJECT) is returned.
Return Codes
On successful completion, the routine returns DS_SUCCESS. Otherwise,
it returns one of the following errors:
o DS_C_SYSTEM_ERROR
o The following DS_C_LIBRARY_ERROR errors:
DS_E_BAD_ARGUMENT
DS_E_BAD_CONTEXT
DS_E_BAD_NAME
DS_E_BAD_SESSION
DS_E_MISCELLANEOUS
DS_E_MISSING_TYPE
DS_E_TOO_MANY_OPERATIONS
o The following directory errors:
DS_C_ATTRIBUTE_ERROR
DS_C_NAME_ERROR
DS_C_REFERRAL
DS_C_SECURITY_ERROR
DS_C_SERVICE_ERROR
o DS_COMMUNICATIONS_ERROR
o The DS_NO_WORKSPACE error constant.
Note that the operation fails and an error is returned either if the
target object is not found or if it does not have an attribute of the
required type.
ΓòÉΓòÉΓòÉ 6.1.4. ds_initialize ΓòÉΓòÉΓòÉ
Purpose
Initializes the XDS interface.
Format
#include <xom.h>
#include <xds.h>
OM_workspace ds_initialize(void);
Usage
The ds_initialize routine performs any necessary initialization of
the XDS Application Program Interface (API) including the creation of
a workspace. It must be called before any other directory interface
routines are called. This routine can be called multiple times, in
which case each call returns a workspace that is distinct from other
workspaces created by ds_initialize but not yet deleted by
ds_shutdown.
Return Codes
Upon successful completion, OM_workspace contains a handle to a
workspace in which OM objects can be created and manipulated. Objects
created in this workspace, and only such objects, can be used as
parameters to the other directory interface routines. This routine
returns NULL if it fails.
Related Information
Routines:
ds_shutdown
ΓòÉΓòÉΓòÉ 6.1.5. ds_list ΓòÉΓòÉΓòÉ
Purpose
Enumerates the immediate subordinates of a particular directory
entry.
Format
#include <xom.h>
#include <xds.h>
DS_status ds_list(
OM_private_object session,
OM_private_object context,
OM_object name,
OM_private_object *result_return,
OM_sint *invoke_id_return);
Parameters
Input
session (Object(DS_C_SESSION)). The directory session against
which this operation is performed. This must be a
private object.
context (Object(DS_C_CONTEXT)). The directory context to be
used for this operation. This parameter must be a
private object or the DS_DEFAULT_CONTEXT constant.
name (Object(DS_C_NAME)). The name of the object entry whose
immediate subordinates are to be listed. Any aliases in
the name are dereferenced unless prohibited by the
DS_DONT_DEREFERENCE_ALIASES service control attribute
of the DS_C_CONTEXT object.
Output
result_return (Object(DS_C_LIST_RESULT)). Upon successful completion,
the result contains some information about the target
object's immediate subordinates. It also contains the
distinguished names of the target object, if an alias
was dereferenced to find it. Aliases in the subordinate
names are not dereferenced.
invoke_id_return (integer). Not supported.
Usage
The ds_list routine is used to obtain a list of the immediate
subordinates of the named entry.
Note: The DS_SIZE_LIMIT and DS_TIME_LIMIT environment variables are
not supported when listing the contents of a CDS directory.
Return Codes
If the named object is located (even if there are no subordinates),
the routine returns DS_SUCCESS. Otherwise, it returns one of the
following errors:
o DS_C_SYSTEM_ERROR
o The following DS_C_LIBRARY_ERROR errors:
DS_E_BAD_ARGUMENT
DS_E_BAD_CONTEXT
DS_E_BAD_NAME
DS_E_BAD_SESSION
DS_E_MISCELLANEOUS
DS_E_MISSING_TYPE
DS_E_TOO_MANY_OPERATIONS
o The following directory errors:
DS_C_NAME_ERROR
DS_C_REFERRAL
DS_C_SECURITY_ERROR
DS_C_SERVICE_ERROR
o DS_COMMUNICATIONS_ERROR
o The DS_NO_WORKSPACE error constant.
ΓòÉΓòÉΓòÉ 6.1.6. ds_modify_entry ΓòÉΓòÉΓòÉ
Purpose
Performs a modification on a directory entry.
Format
#include <xom.h>
#include <xds.h>
DS_status ds_modify_entry(
OM_private_object session,
OM_private_object context,
OM_object name,
OM_object changes,
OM_sint *invoke_id_return);
Parameters
Input
session (Object(DS_C_SESSION)). The directory session against
which this operation is performed. This must be a
private object.
context (Object(DS_C_CONTEXT)). The directory context to be
used for this operation. Note that DS_SIZE_LIMIT and
DS_DONT_DEREFERENCE_ALIASES do not apply to this
operation. This parameter must be a private object or
the DS_DEFAULT_CONTEXT constant.
name (Object(DS_C_NAME)). The name of the target object
entry. Any aliases in the name are not dereferenced.
changes (Object(DS_C_ENTRY_MODIFICATION_LIST)). A sequence of
modifications to the named entry.
Output
invoke_id_return (integer). Not supported.
Usage
The ds_modify_entry routine is used to make a series of one or more
of the following changes to a single directory entry:
o Add a new attribute (DS_ADD_ATTRIBUTE).
o Remove an attribute (DS_REMOVE_ATTRIBUTE).
o Add attribute values (DS_ADD_VALUES).
o Remove attribute values (DS_REMOVE_VALUES).
Values can be replaced by a combination of adding values and removing
values in a single operation.
The result of the operation is as if each modification is made in the
order specified in the changes parameter. If any of the individual
modifications fails, then a DS_C_ATTRIBUTE_ERROR is reported.
Notes
Note the following issues for the ds_modify_entry operation:
o Naming schema rules do not apply in CDS. Thus, the following
attribute errors are never returned by CDS:
- DS_E_NO_SUCH_ATTRIBUTE_OR_VALUE
- DS_E_ATTRIBUTE_OR_VALUE_ALREADY_EXISTS Naming operations
that would normally return these errors succeed in CDS. In
particular, the addition of an attribute that already exists
does not return with an error. Instead, the values of the
attribute to be added are combined with the values of the
existing attribute.
o GDS-structured attribute types are not supported by CDS. If a
GDS-structured attribute type is used as a parameter to
ds_modify_entry on a CDS object, then it returns with a
DS_C_ATTRIBUTE_ERROR (DS_E_CONSTRAINT_VIOLATION). In CDS,
ds_modify_entry can only be used on leaf objects; otherwise, a
DS_C_NAME_ERROR (DS_E_NO_SUCH_OBJECT) is returned.
This operation is not atomic for XDS/XOM over CDS.
Return Codes
If all the modifications succeeded, the routine returns DS_SUCCESS.
Otherwise, it returns one of the following errors:
o DS_C_SYSTEM_ERROR
o The following DS_C_LIBRARY_ERROR errors:
DS_E_BAD_ARGUMENT
DS_E_BAD_CONTEXT
DS_E_BAD_NAME
DS_E_BAD_SESSION
DS_E_MISCELLANEOUS
DS_E_MISSING_TYPE
DS_E_TOO_MANY_OPERATIONS
o The following directory errors:
DS_C_ATTRIBUTE_ERROR
DS_C_NAME_ERROR
DS_C_REFERRAL
DS_C_SECURITY_ERROR
DS_C_SERVICE_ERROR
DS_C_UPDATE_ERROR
o DS_COMMUNICATIONS_ERROR
o The DS_NO_WORKSPACE error constant.
ΓòÉΓòÉΓòÉ 6.1.7. ds_read ΓòÉΓòÉΓòÉ
Purpose
Queries information on an entry by name.
Format
#include <xom.h>
#include <xds.h>
DS_status ds_read(
OM_private_object session,
OM_private_object context,
OM_object name,
OM_object selection,
OM_private_object *result_return,
OM_sint *invoke_id_return);
Parameters
Input
session (Object (DS_C_SESSION)). The directory session this
operation is performed against. This must be a private
object.
context (Object (DS_C_CONTEXT)). The directory context to be
used for this operation. Note that DS_SIZE_LIMIT does
not apply to this operation. This parameter must be a
private object or the DS_DEFAULT_CONTEXT constant.
name (Object (DS_C_NAME)). The name of the target object
entry. Any aliases in the name are dereferenced unless
prohibited by the DS_DONT_DEREFERENCE_ALIASES service
control attribute of the DS_C_CONTEXT object.
selection (Object (DS_C_ENTRY_INFORMATION_SELECTION)). Specifies
what information from the entry is requested.
Information about no attributes, all attributes, or
only for a named set can be chosen. Attribute types are
always returned, but the attribute values need not be
returned. The possible values of this parameter are
given in DCE for OS/2 Warp: Application Development
Guide - Core Components.
Output
result_return (Object (DS_C_READ_RESULT)). Upon successful
completion, the result contains the DN of the target
object, and a flag indicating whether the result came
from the original entry or a copy. It also contains any
requested attribute types and values. Attribute
information is only returned if access rights are
sufficient.
invoke_id_return (integer). Not supported.
Usage
The ds_read routine is used to extract information from an explicitly
named entry. It can also be used to verify a distinguished name (DN).
Notes
Note the following issues for the ds_read operation:
o Since CDS does not implement the X.500 schema rules, some CDS
objects may not contain mandatory attributes like object class
and so on.
o In CDS, the naming attribute of an object is not stored in the
attribute list for the object. Therefore in CDS, ds_read does
not return this attribute in the attribute list for an object.
Return Codes
On successful completion, the routine returns DS_SUCCESS. Otherwise,
it returns one of the following errors:
o DS_C_SYSTEM_ERROR
o The following DS_C_LIBRARY_ERROR errors:
DS_E_BAD_ARGUMENT
DS_E_BAD_ATTRIBUTE
DS_E_BAD_CONTEXT
DS_E_BAD_NAME
DS_E_BAD_SESSION
DS_E_MISCELLANEOUS
DS_E_MISSING_TYPE
DS_E_TOO_MANY_OPERATIONS
o The following directory errors:
DS_C_ATTRIBUTE_ERROR
DS_C_NAME_ERROR
DS_C_REFERRAL
DS_C_SECURITY_ERROR
DS_C_SERVICE_ERROR
o DS_COMMUNICATIONS_ERROR
o The DS_NO_WORKSPACE error constant.
Notes In GDS, a DS_C_ATTRIBUTE_ERROR
(DS_E_NO_SUCH_ATTRIBUTE_OR_VALUE) is reported if an explicit
list of attributes is specified by the selection parameter,
but none of them are present in the entry. This error is not
reported if any of the selected attributes are present.
A DS_C_SECURITY_ERROR (DS_E_INSUFFICIENT_ACCESS_RIGHTS) is only
reported where access rights preclude the reading of all requested
attribute values.
Related Information
Books:
DCE for OS/2 Warp: Application Development Guide - Core Components
ΓòÉΓòÉΓòÉ 6.1.8. ds_remove_entry ΓòÉΓòÉΓòÉ
Purpose
Removes a leaf entry from the Directory Information Tree (DIT).
Format
#include <xom.h>
#include <xds.h>
DS_status ds_remove_entry(
OM_private_object session,
OM_private_object context,
OM_object name,
OM_sint *invoke_id_return);
Parameters
Input
session (Object (DS_C_SESSION). The directory session this
operation is performed against. This must be a private
object.
context (Object (DS_C_CONTEXT)). The directory context to be
used for this operation. Note that DS_SIZE_LIMIT and
DS_DONT_DEREFERENCE_ALIASES do not apply to this
operation. This parameter must be a private object or
the DS_DEFAULT_CONTEXT constant.
name (Object (DS_C_NAME)). The name of the target object
entry. Any aliases in the name are not dereferenced.
Output
invoke_id_return (Integer). Not supported.
Usage
The ds_remove_entry routine is used to remove a leaf entry from the
directory (either an object entry or an alias entry).
Return Codes
On successful completion, the routine returns DS_SUCCESS. Otherwise,
it returns one of the following errors:
o DS_C_SYSTEM_ERROR
o The following DS_C_LIBRARY_ERROR errors:
DS_E_BAD_ARGUMENT
DS_E_BAD_CONTEXT
DS_E_BAD_NAME
DS_E_BAD_SESSION
DS_E_MISCELLANEOUS
DS_E_MISSING_TYPE
DS_E_TOO_MANY_OPERATIONS
o The following directory errors:
DS_C_NAME_ERROR
DS_C_REFERRAL
DS_C_SECURITY_ERROR
DS_C_SERVICE_ERROR
DS_C_UPDATE_ERROR
o DS_C_COMMUNICATIONS_ERROR
o The DS_NO_WORKSPACE error constant.
ΓòÉΓòÉΓòÉ 6.1.9. ds_shutdown ΓòÉΓòÉΓòÉ
Purpose
Shuts down the interface.
Format
#include <xom.h>
#include <xds.h>
DS_status ds_shutdown(
OM_workspace workspace);
Parameters
Input
workspace Specifies the workspace (obtained from a call to
ds_initialize) that is to be deleted.
Usage
The ds_shutdown routine deletes the workspace established by
ds_initialize and enables the service to release resources. All
sessions associated with the workspace must be terminated by calling
ds_unbind prior to calling ds_shutdown. No other directory interface
routine can reference the specified workspace after it is deleted.
However, om_delete and om_instance can be called if referring to
public objects.
Return Codes
On successful completion, the routine returns DS_SUCCESS. Otherwise,
it returns one of the following errors:
o DS_C_SERVICE_ERROR (value DS_E_BUSY) if ds_shutdown is called
before all directory connections have been released with
ds_unbind.
o The DS_INVALID_WORKSPACE error constant.
This routine does not return a DS_C_COMMUNICATIONS_ERROR or any
directory errors.
Related Information
Routines:
ds_initialize
ΓòÉΓòÉΓòÉ 6.1.10. ds_unbind ΓòÉΓòÉΓòÉ
Purpose
Unbinds from a directory session.
Format
#include <xom.h>
#include <xds.h>
DS_status ds_unbind(
OM_private_object session);
Parameters
Input
session (Object (DS_C_SESSION)). The directory session that is
to be unbound. This must be a private object. The value
of the DS_FILE_DESCRIPTOR OM attribute is
DS_NO_VALID_FILE_DESCRIPTOR if the routine succeeds.
The remaining OM attributes are unchanged.
Usage
The ds_unbind routine terminates the given directory session, and
makes the parameter unavailable for use with other interface routines
(except ds_bind).
The unbound session can be used again as a parameter to ds_bind
possibly after modification by the Object Management routines. When
it is no longer required, it must be deleted using the Object
Management routines.
Return Codes
On successful completion, the routine returns DS_SUCCESS. Otherwise,
it returns one of the following errors:
o DS_C_SYSTEM_ERROR
o DS_C_SERVICE_ERROR (value DS_E_BUSY) if ds_shutdown is called
before all directory connections have been released with
ds_unbind.
o The following DS_C_LIBRARY_ERROR errors:
DS_E_BAD_SESSION
DS_E_MISCELLANEOUS
o The DS_NO_WORKSPACE error constant.
This routine does not return a DS_C_COMMUNICATIONS_ERROR or any
directory errors.
Related Information
Routines:
ds_bind
ΓòÉΓòÉΓòÉ 6.1.11. ds_version ΓòÉΓòÉΓòÉ
Purpose
Negotiates features of the interface and service.
Format
#include <xom.h>
#include <xds.h>
DS_status ds_version(
DS_feature feature_list[],
OM_workspace workspace);
Parameters
Input
workspace Specifies the workspace obtained from a call to
om_initialize for which the features are to be
negotiated. The features are in effect for operations
that use the workspace or directory sessions associated
with the workspace.
Input/Output
feature_list[] An ordered sequence of features, each represented by
an object identifier. The sequence is terminated by an
object identifier having no components (a length of 0
(zero) and any value for the data pointer.) If the
routine completed successfully, an ordered sequence of
boolean values is returned, with the same number of
elements as the feature_list parameter. If this
parameter contains OM_TRUE, each value indicates that
the corresponding feature is now part of the interface.
If this parameter contains OM_FALSE, each value
indicates that the corresponding feature is not
available.
This result is combined with the feature_list parameter
as a single array of structures of type DS_feature,
which is defined as follows:
typedef struct
{
OM_object_identifier feature;
OM_boolean activated;
} DS_feature;
Usage
The ds_version routine negotiates features of the interface, which
are represented by object identifiers. The DS_SERVICE_PACKAGE is
supported for use with CDS. The ds_version routine cannot be issued
until after a workspace is initialized with ds_initialize.
Note: The user is not required to issue the ds_version routine when
accessing CDS.
Return Codes
On successful completion, the routine returns DS_SUCCESS. Otherwise,
it returns one of the following errors:
o DS_C_SYSTEM_ERROR
o The following DS_C_LIBRARY_ERROR errors:
DS_E_BAD_WORKSPACE
DS_E_MISCELLANEOUS
o The DS_NO_WORKSPACE error constant.
Related Information
Books:
DCE for OS/2 Warp: Application Development Guide - Core Components
ΓòÉΓòÉΓòÉ 6.1.12. dsX_extract_attr_values ΓòÉΓòÉΓòÉ
Purpose
Extracts attribute values from an OM object.
Format
#include <xom.h>
#include <xds.h>
#include <xdsext.h>
OM_return_code dsX_extract_attr_values(
OM_private_object object,
OM_object_identifier attribute_type,
OM_boolean local_strings,
OM_public_object *values,
OM_value_position *total_number);
Parameters
Input
object The private object from which the attribute values are
to be extracted. Objects of type DS_C_ATTRIBUTE_LIST or
DS_C_ENTRY_INFO are supported.
attribute_type The attribute type from which the values are to be
extracted.
local_strings Indicates whether the conversion to local string format
should be performed. This parameter is not supported.
Output
values Present only if the return value from OM_return_code is
OM_SUCCESS. This parameter points to a public object
containing an array of OM descriptors with the
extracted attribute values.
total_number Contains the total number of attribute values that have
been extracted.
Note: The total includes only the attribute
descriptors in the values parameter. It excludes
the special descriptor signaling the end of a
public object.
Usage
The dsX_extract_attr_values routine is used to extract the attribute
values associated with the specified attribute type from an OM
object. The OM object must be of type DS_C_ATTRIBUTE_LIST or
DS_C_ENTRY_INFO. It returns an object containing an array of OM
descriptors.
Notes
The memory space for the values return parameter is allocated by
dsX_extract_attr_values. The calling application is responsible for
releasing this memory with the om_delete routine.
Return Codes
On successful completion, the routine returns OM_SUCCESS in the
OM_return_code variable. Otherwise, it returns one of the constants
defined in the xom.h header file.
ΓòÉΓòÉΓòÉ 6.2. XDS Header Files ΓòÉΓòÉΓòÉ
There are ten XDS header files. The following four are required for using the
XDS API over CDS:
xds.h Contains definitions for the XDS routines and Directory Service
Package. This header file must be included by all applications
using the XDS API.
xdsbdcp.h Contains definitions for the Basic Directory Contents Package.
This header file is part of the X/Open XDS specifications and
is required when using the Basic Directory Contents Package.
xdscds.h Contains definitions for the Cell Directory Package. This
header file is a DCE extension to the XDS API, and is required
when using CDS.
xdsext.h Contains definitions for the convenience library routines.
The following six header files are shipped for users that have applications
that work with both CDS and GDS:
o xdsdme.h
o xdsgds.h
o xdsmdup.h
o xdssap.h
o xmhp.h
o xmsga.h
Using these files allows the application to compile, but only accesses to CDS
entries will be successful. These header files are found in the directory
d:\opt\dcelocal\include where d: is the drive where DCE is installed.
ΓòÉΓòÉΓòÉ 6.3. X/OPEN OSI-Abstract-Data Manipulation Routines ΓòÉΓòÉΓòÉ
The X/Open Object Management (XOM) routines comprise the C interface. The
service interface comprises a number of routines whose purpose and range of
capabilities are summarized as follows:
om_copy This routine creates an independent copy of an existing private
object and all its subobjects. The copy is placed in the work
space of the original object, or in another specified by the
XOM application.
om_copy_value This routine replaces an existing attribute value or inserts a
new value in one private object with a copy of an existing
attribute value found in another. Both values must be strings.
om_create This routine creates a new private object that is an instance
of a particular class. The object can be initialized with the
attribute values specified as initial in the class definition.
The service does not permit the API user to explicitly create
instances of all classes, but rather only those indicated by a
package's definition as having this property.
om_delete This routine deletes a service-generated public object, or
makes a private object inaccessible.
om_get This routine creates a new public object that is an exact but
independent copy of an existing private object. The client can
request certain exclusions, each of which reduces the copy to a
part of the original. The client can also request that values
be converted from one syntax to another before they are
returned.
The copy can exclude attributes of types other than those
specified, values at positions other than those specified
within an attribute, the values of multivalued attributes,
copies of (not handles for) subobjects, or all attribute values
(revealing only an attribute's presence).
om_instance This routine determines whether an object is an instance of a
particular class. The client can determine an object's class
simply by inspection. This routine is useful since it reveals
that an object is an instance of a particular class, even if
the object is an instance of a subclass of that class.
om_put This routine places or replaces in one private object copies of
the attribute values of another public or private object.
The source values can be inserted before any existing
destination values, before the value at a specified position in
the destination attribute, or after any existing destination
values. Alternatively, the source values can be substituted for
any existing destination values or for the values at specified
positions in the destination attribute.
om_read This routine reads a segment of a value of an attribute of a
private object. The value must be a string. The value can
first be converted from one syntax to another. The routine
enables the client to read an arbitrarily long value without
requiring that the service place a copy of the entire value in
memory.
om_remove This routine removes and discards particular values of an
attribute of a private object. The attribute itself is removed
if no values remain.
om_write This routine writes a segment of a value of an attribute to a
private object. The value must be a string. The segment can
first be converted from one syntax to another. The written
segment becomes the value's last segment since any elements
beyond it are discarded. The routine enables the client to
write an arbitrarily long value without having to place a copy
of the entire value in memory.
omX_extract This routine creates a new public object that is an exact but
independent copy of an existing subobject in a private object.
It is similar to the om_get routine but includes an additional
parameter, navigation_path, which contains directions to the
required object to be extracted.
omX_fill This routine initializes an OM descriptor structure with
user-supplied values for it's type, syntax, and value.
omX_fill_oid This routine initializes an OM descriptor structure with
user-supplied values for it's type and value. The syntax of the
descriptor is always set to OM_S_OBJECT_IDENTIFIER_STRING.
omX_object_to_string This routine converts an OM object into a string format.
omX_string_to_object This routine creates a new private object, which is built
from the string and class input parameters.
In the C interface, the routines are realized by macros. The routine prototype
in the Format section of the routine specification shows the client's view of
the routine.
The intent of the interface definition is that each routine be atomic; that
is, either it carries out its assigned task in full and reports success, or it
fails to carry out even a part of the task and reports an exception. However,
the service does not guarantee that a task is always carried out in full.
Notes
o XOM routines check for NULL pointers and return an error except for work
space pointers.
o Pointers are checked only at the routine interface. The check is only for
NULL and not for validity. If NULL pointers or invalid pointers are
passed this may result in an undetermined behavior.
o All of the routines in the XOM interface include the xom.h header file.
ΓòÉΓòÉΓòÉ 6.4. XOM Header Files ΓòÉΓòÉΓòÉ
The XOM header files are xom.h, xomi.h, and xomext.h. The xom.h file includes
xomi.h, which is used by the service interface. The xom.h header file contains
the XOM definition required by applications. The xomext.h file contains
definitions for the convenience library routines. All of these files can be
found in the directory d:\opt\dcelocal\include where d: is the drive where DCE
is installed.
ΓòÉΓòÉΓòÉ 6.4.1. om_copy ΓòÉΓòÉΓòÉ
Purpose
Creates a new private object that is an exact but independent copy of
an existing private object.
Format
#include <xom.h>
OM_return_code om_copy(
OM_private_object original,
OM_workspace workspace,
OM_private_object *copy);
Parameters
Input
original The original that remains accessible.
workspace The work space where the copy is to be created. The
original's class must be in a package associated with
this work space.
Output
copy The new copy of the private object. This result is
present if, and only if, the return value for
OM_return_code is OM_SUCCESS.
Usage
The om_copy routine creates a new private object, the copy, that is
an exact but independent copy of an existing private object, the
original. The routine is recursive, which means that copying the
original also copies its subobjects.
Return Codes
On successful completion, the routine returns OM_SUCCESS in the
OM_return_code variable. Otherwise, it returns one of the following
errors:
OM_FUNCTION_INTERRUPTED
OM_MEMORY_INSUFFICIENT
OM_NETWORK_ERROR
OM_NO_SUCH_CLASS
OM_NO_SUCH_OBJECT
OM_NO_SUCH_WORKSPACE
OM_NOT_PRIVATE
OM_PERMANENT_ERROR
OM_POINTER_INVALID
OM_SYSTEM_ERROR
OM_TEMPORARY_ERROR
OM_TOO_MANY_VALUES
The exact constants for OM_return_code are defined in the xom.h
header file.
ΓòÉΓòÉΓòÉ 6.4.2. om_copy_value ΓòÉΓòÉΓòÉ
Purpose
Places or replaces a string in one private object with a copy of a
string in another private object.
Format
#include <xom.h>
OM_return_code om_copy_value(
OM_private_object source,
OM_type source_type,
OM_value_position source_value_position,
OM_private_object destination,
OM_type destination_type,
OM_value_position destination_value_position);
Parameters
Input
source The source that remains accessible.
source_type Identifies the type of an attribute. One of the
attribute values is copied.
source_value_position The position within the attribute referred to
by source_type of the value copied.
destination The destination that remains accessible.
destination_type Identifies the type of the attribute. One of the
attribute values is placed or replaced.
destination_value_position The position within the destination
attribute of the value placed or replaced. If the value
position exceeds the number of values present in the
destination attribute, the parameter is assumed to be
equal to that number.
Usage
The om_copy_value routine places or replaces an attribute value in
one private object (the destination) with a copy of an attribute
value in another private object (the source). The source value is a
string. The copy's syntax is that of the original.
Return Codes
On successful completion, the routine returns OM_SUCCESS in the
OM_return_code variable. Otherwise, it returns one of the following
errors:
OM_FUNCTION_DECLINED
OM_FUNCTION_INTERRUPTED
OM_MEMORY_INSUFFICIENT
OM_NETWORK_ERROR
OM_NO_SUCH_OBJECT
OM_NO_SUCH_TYPE
OM_NOT_PRESENT
OM_NOT_PRIVATE
OM_PERMANENT_ERROR
OM_POINTER_INVALID
OM_SYSTEM_ERROR
OM_TEMPORARY_ERROR
OM_WRONG_VALUE_LENGTH
OM_WRONG_VALUE_SYNTAX
OM_WRONG_VALUE_TYPE
The exact constants for OM_return_code are defined in the xom.h
header file.
ΓòÉΓòÉΓòÉ 6.4.3. om_create ΓòÉΓòÉΓòÉ
Purpose
Creates a new private object that is an instance of a particular
class.
Format
#include <xom.h>
OM_return_code om_create(
OM_object_identifier class,
OM_boolean initialize,
OM_workspace workspace,
OM_private_object *object);
Parameters
Input
class Identifies the class of the object to be created. The
specified class is concrete.
initialize Determines whether the object created is initialized as
specified in the definition of its class. If this
parameter is OM_TRUE, the object is made to comprise
the attribute values specified as initial values in the
tabular definitions of the object's class and its
superclasses. If this parameter is OM_FALSE, the object
is made to comprise the OM_CLASS attribute alone.
workspace The work space where the object is created. The
specified class is in a package associated with this
work space.
Output
object The created object. This result is present if, and
only if, the return value for OM_return_code is
OM_SUCCESS.
Usage
The om_create routine creates a new private object that is an
instance of a particular class.
Notes
By subsequently adding new values to the object and replacing and
removing existing values, the client can create all conceivable
instances of the object's class.
Return Codes
On successful completion, the routine returns OM_SUCCESS in the
OM_return_code variable. Otherwise, it returns one of the following
errors:
OM_FUNCTION_DECLINED
OM_FUNCTION_INTERRUPTED
OM_MEMORY_INSUFFICIENT
OM_NETWORK_ERROR
OM_NO_SUCH_CLASS
OM_NO_SUCH_WORKSPACE
OM_NOT_CONCRETE
OM_PERMANENT_ERROR
OM_POINTER_INVALID
OM_SYSTEM_ERROR
OM_TEMPORARY_ERROR
The exact constants for OM_return_code are defined in the xom.h
header file.
ΓòÉΓòÉΓòÉ 6.4.4. om_delete ΓòÉΓòÉΓòÉ
Purpose
Deletes a private or service-generated object.
Format
#include <xom.h>
OM_return_code om_delete(
OM_object subject);
Parameters
Input
subject The object that is to be deleted.
Usage
The om_delete routine deletes a service-generated public object or
makes a private object inaccessible. It is not intended for use on
client-generated public objects.
If applied to a service-generated public object, the routine deletes
the object and releases any resources associated with the object,
including the space occupied by descriptors and attribute values.
The routine is applied recursively to any public subobjects. This
does not affect any private subobjects.
If applied to a private object, the routine makes the object
inaccessible. Any existing object handles for the object are
invalidated. The routine is applied recursively to any private
subobjects.
Return Codes
On successful completion, the routine returns OM_SUCCESS in the
OM_return_code variable. Otherwise, it returns one of the following
errors:
OM_FUNCTION_INTERRUPTED
OM_MEMORY_INSUFFICIENT
OM_NETWORK_ERROR
OM_NO_SUCH_OBJECT
OM_NO_SUCH_SYNTAX
OM_NO_SUCH_TYPE
OM_NOT_THE_SERVICES
OM_PERMANENT_ERROR
OM_POINTER_INVALID
OM_SYSTEM_ERROR
OM_TEMPORARY_ERROR
The exact constants for OM_return_code are defined in the xom.h
header file.
ΓòÉΓòÉΓòÉ 6.4.5. om_get ΓòÉΓòÉΓòÉ
Purpose
Creates a public copy of all or particular parts of a private object.
Format
#include <xom.h>
OM_return_code om_get(
OM_private_object original,
OM_exclusions exclusions,
OM_type_list included_types,
OM_boolean local_strings,
OM_value_position initial_value,
OM_value_position limiting_value,
OM_public_object *copy,
OM_value_position *total_number);
Parameters
Input
original The original that remains accessible.
exclusions Explicit requests for 0 (zero) or more exclusions, each
of which reduces the copy to a prescribed portion of
the original. The exclusions apply to the attributes
of the object but not to those of its subobjects.
Apart from OM_NO_EXCLUSIONS, each value is chosen from
the following list. When multiple exclusions are
specified, each is applied in the order that it is
displayed in the list with lower-numbered exclusions
having precedence over higher-numbered exclusions. If,
after the application of an exclusion, that portion of
the object is not returned, no further exclusions need
be applied to that portion.
OM_EXCLUDE_ALL_BUT_THESE_TYPES The copy includes
descriptors comprising only
attributes of specified types. Note
that this exclusion provides a means
for determining the values of
specified attributes, as well as the
syntaxes of those values.
OM_EXCLUDE_MULTIPLES The copy includes a single
descriptor for each attribute that
has two or more values, rather than
one descriptor for each value. None
of these descriptors contains an
attribute value, and the
OM_S_NO_VALUE bit of the syntax
component is set.
If the attribute has values of two
or more syntaxes, the descriptor
identifies one of those syntaxes;
however, the syntax identified is
not specified. Note that this
exclusion provides a means for
discerning the presence of
multivalued attributes without
simultaneously obtaining their
values.
OM_EXCLUDE_ALL_BUT_THESE_VALUES The copy includes
descriptors comprising only values
at specified positions within an
attribute. Note that when this
exclusion is used in conjunction
with the
OM_EXCLUDE_ALL_BUT_THESE_TYPES
exclusion, it provides a means for
determining the values of a
specified attribute, as well as the
syntaxes of those values, one or
more but not all attributes at a
time.
OM_EXCLUDE_VALUES The copy includes a single
descriptor for each attribute value,
but the descriptor does not contain
the value, and the OM_S_NO_VALUE bit
of the syntax component is set. Note
that this exclusion provides a means
for determining an object's
composition, that is, the type and
syntax of each of its attribute
values.
OM_EXCLUDE_SUBOBJECTS The copy includes, for each
value whose syntax is OM_S_OBJECT, a
descriptor containing an object
handle for the original private
subobject, rather than a public copy
of it. This handle makes that
subobject accessible for use in
subsequent routine calls. Note that
this exclusion provides a means for
examining an object one level at a
time.
OM_EXCLUDE_DESCRIPTORS When this exclusion is
specified, no descriptors are
returned and the copy result is not
present. The total_number parameter
reflects the number of descriptors
that would be returned by applying
the other inclusion and exclusion
specifications. Note that this
exclusion provides an attribute
analysis capability. For instance,
the total number of values in a
multivalued attribute can be
determined by specifying an
inclusion of the specific attribute
type, and exclusions of
OM_EXCLUDE_DESCRIPTORS,
OM_EXCLUDE_SUBOBJECTS, and
OM_EXCLUDE_ALL_BUT_THESE_TYPES.
The OM_EXCLUDE_ALL_BUT_THESE_VALUES exclusion affects
the choice of descriptors, while the OM_EXCLUDE_VALUES
exclusion affects the composition of descriptors.
included_types Identifies the types of the attributes to be included
in the copy (provided that they are displayed in the
original). This parameter contains a value if, and only
if, OM_EXCLUDE_ALL_BUT_THESE_TYPES exclusion is
requested.
local_strings This boolean parameter indicates whether conversion to
local string format should be carried out. This
parameter is not supported.
initial_value Specifies the position within each attribute of the
first value to be included in the copy. This parameter
contains a value if, and only if, the
OM_EXCLUDE_ALL_BUT_THESE_VALUES exclusion is requested.
If it is OM_ALL_VALUES or exceeds the number of values
present in an attribute, the parameter is taken to be
equal to that number.
limiting_value Specifies the position within each attribute one
beyond that of the last value to be included in the
copy. This parameter contains a value if, and only if,
the OM_EXCLUDE_ALL_BUT_THESE_VALUES exclusion is
requested. If this parameter is not greater than the
initial_value parameter, no values are included (and no
descriptors are returned).
If it is OM_ALL_VALUES or exceeds the number of values
present in an attribute, the parameter is assumed to be
equal to that number.
Output
copy The copy parameter is present only if the return value
from OM_return_code is OM_SUCCESS and the
OM_EXCLUDE_DESCRIPTORS exclusion is not specified.
The space occupied by the public object and every
attribute value that is a string is service-provided.
If the client alters any part of that space, the effect
upon the service's subsequent behavior is unspecified.
total_number The number of attribute descriptors returned in the
public object, but not in any of its subobjects, based
on the inclusion and exclusion parameters specified.
If the OM_EXCLUDE_DESCRIPTORS exclusion is specified,
no copy result is returned and the total_number result
reflects the actual number of attribute descriptors
that would be returned based on the remaining inclusion
and exclusion values. Note that the total includes only
the attribute descriptors in the copy parameter. It
excludes the special descriptor signaling the end of a
public object.
Usage
The om_get routine creates a new public object (copy) that is an
exact but independent copy of an existing private object, the
original parameter. The client can request certain exclusions, each
of which reduces the copy to a part of the original.
One exclusion is always requested implicitly. For each attribute
value in the original that is a string whose length exceeds an
implementation-defined number, the copy parameter includes a
descriptor that omits the elements (but not the length) of the
string. The elements component of the string component in the
descriptor's value component is OM_ELEMENTS_UNSPECIFIED, and the
OM_S_LONG_STRING bit of the syntax component is set to OM_TRUE. Note
that the client can access long values by means of om_read.
Return Codes
On successful completion, the routine returns OM_SUCCESS in the
OM_return_code variable. Otherwise, it returns one of the following
errors:
OM_FUNCTION_INTERRUPTED
OM_MEMORY_INSUFFICIENT
OM_NETWORK_ERROR
OM_NO_SUCH_EXCLUSION
OM_NO_SUCH_OBJECT
OM_NO_SUCH_TYPE
OM_NOT_PRIVATE
OM_PERMANENT_ERROR
OM_POINTER_INVALID
OM_SYSTEM_ERROR
OM_TEMPORARY_ERROR
OM_WRONG_VALUE_SYNTAX
OM_WRONG_VALUE_TYPE
The exact constants for OM_return_code are defined in the xom.h
header file.
ΓòÉΓòÉΓòÉ 6.4.6. om_instance ΓòÉΓòÉΓòÉ
Purpose
Determines whether an object is an instance of a particular class or
any of its subclasses.
Format
#include <xom.h>
OM_return_code om_instance(
OM_object subject,
OM_object_identifier class,
OM_boolean *instance);
Parameters
Input
subject The subject that remains accessible.
class Identifies the class in question.
Output
instance Indicates whether the subject is an instance of the
specified class or any of its subclasses. This result
is present if, and only if, the value of the
OM_return_code is set to OM_SUCCESS.
Usage
The om_instance routine determines whether a service-generated public
or private object (subject) is an instance of a particular class or
any of its subclasses.
Notes
The client can determine the object class, C, by inspecting the
object, using programming language constructs if the object is public
or om_get if it is private. The om_instance routine is useful because
it reveals that an object is an instance of the specified class, even
if C is a subclass of that class.
Return Codes
On successful completion, the routine returns OM_SUCCESS in the
OM_return_code variable. Otherwise, it returns one of the following
errors:
OM_FUNCTION_INTERRUPTED
OM_MEMORY_INSUFFICIENT
OM_NETWORK_ERROR
OM_NO_SUCH_CLASS
OM_NO_SUCH_OBJECT
OM_NO_SUCH_SYNTAX
OM_NOT_THE_SERVICES
OM_PERMANENT_ERROR
OM_POINTER_INVALID
OM_SYSTEM_ERROR
OM_TEMPORARY_ERROR
The exact constants for OM_return_code are defined in the xom.h
header file.
ΓòÉΓòÉΓòÉ 6.4.7. om_put ΓòÉΓòÉΓòÉ
Purpose
Places or replaces in one private object copies of the attribute
values of another public or private object.
Format
#include <xom.h>
OM_return_code om_put(
OM_private_object destination,
OM_modification modification,
OM_object source,
OM_type_list included_types,
OM_value_position initial_value,
OM_value_position limiting_value);
Parameters
Input
destination The destination that remains accessible. The
destination's class is unaffected.
modification The nature of the requested modification. The
modification determines how om_put uses the attribute
values in the source to modify the object. In all
cases, for each attribute present in the source, copies
of its values are placed in the object's destination
attribute of the same type. The data value is chosen
from among the following:
OM_INSERT_AT_BEGINNING The source values are
inserted before any existing
destination values. (The latter are
retained.)
OM_INSERT_AT_CERTAIN_POINT The source values are
inserted before the value at a
specified position in the
destination attribute. (The latter
are retained.)
OM_INSERT_AT_END The source values are inserted
after any existing destination
values. (The latter are retained.)
OM_REPLACE_ALL The source values are placed in the
destination attribute. The existing
destination values, if any, are
discarded.
OM_REPLACE_CERTAIN_VALUES The source values are
substituted for the values at
specified positions in the
destination attribute. (The latter
are discarded.)
source The source that remains accessible. The source's class
is ignored. However, the attributes being copied from
the source must be compatible with the destination's
class definition.
included_types If present, this parameter identifies the types of the
attributes to be included in the destination (provided
that they are displayed in the source); otherwise, all
attributes are to be included.
initial_value Specifies the position within each destination
attribute where source values are inserted, or of the
first value replaced, respectively. This parameter
contains a value if, and only if, the modification
parameter is OM_INSERT_AT_CERTAIN_POINT or
OM_REPLACE_CERTAIN_VALUES.
If it is OM_ALL_VALUES, or exceeds the number of values
present in a destination attribute, the parameter is
taken to be equal to that number.
limiting_value Specifies the position within each destination
attribute one beyond that of the last value replaced.
This parameter contains a value if, and only if, the
modification parameter is OM_REPLACE_CERTAIN_VALUES. If
this parameter is present, it must be greater than the
initial_value parameter.
If the limiting_value parameter is OM_ALL_VALUES or
exceeds the number of values present in a destination
attribute, the parameter is taken to be equal to that
number.
Usage
The om_put routine places or replaces in one private object (that is,
the destination) copies of the attribute values of another public or
private object (that is, the source). The client can specify that the
source's values replace all or particular values in the destination
or are inserted at a particular position within each attribute. All
string values being copied that are in the local representation are
first converted into the nonlocal representation for that syntax
(which may entail the loss of some information).
Return Codes
On successful completion, the routine returns OM_SUCCESS in the
OM_return_code variable. Otherwise, it returns one of the following
errors:
OM_FUNCTION_DECLINED
OM_FUNCTION_INTERRUPTED
OM_MEMORY_INSUFFICIENT
OM_NETWORK_ERROR
OM_NO_SUCH_CLASS
OM_NO_SUCH_MODIFICATION
OM_NO_SUCH_OBJECT
OM_NO_SUCH_SYNTAX
OM_NO_SUCH_TYPE
OM_NOT_CONCRETE
OM_NOT_PRESENT
OM_NOT_PRIVATE
OM_PERMANENT_ERROR
OM_POINTER_INVALID
OM_SYSTEM_ERROR
OM_TEMPORARY_ERROR
OM_TOO_MANY_VALUES
OM_VALUES_NOT_ADJACENT
OM_WRONG_VALUE_LENGTH
OM_WRONG_VALUE_MAKEUP
OM_WRONG_VALUE_NUMBER
OM_WRONG_VALUE_POSITION
OM_WRONG_VALUE_SYNTAX
OM_WRONG_VALUE_TYPE
The exact constants for OM_return_code are defined in the xom.h
header file.
ΓòÉΓòÉΓòÉ 6.4.8. om_read ΓòÉΓòÉΓòÉ
Purpose
Reads a segment of a string in a private object.
Format
#include <xom.h>
OM_return_code om_read(
OM_private_object subject,
OM_type type,
OM_value_position value_position,
OM_boolean local_string,
OM_string_length *string_offset,
OM_string *elements);
Parameters
Input
subject The subject that remains accessible.
type Identifies the type of the attribute one of whose
values is read.
value_position The position within the attribute of the value read.
local_string This boolean parameter indicates whether conversion to
local string format should be carried out. This
parameter is ignored.
Input/Output
string_offset On input, the offset, in octets, of the start of the
string segment to be read. If it exceeds the total
length of the string, the parameter is equal to the
string length. On output, it contains the offset, in
octets, of the start of the next string segment to be
read, or 0 (zero) if the final segment of the value is
read. The result is present if, and only if, the
OM_return_code is OM_SUCCESS. The value returned can be
used as the input string_offset parameter in the next
call of this routine. This enables sequential reading
of a value of a long string.
elements On input, the space the client provides for the segment
to be read. The string's contents are initially
unspecified. The length of the string is initially the
number of octets required to contain the segment that
the routine is to read.
On output, the string's elements become the elements
actually read. The length of the string becomes the
number of octets required to hold the segment actually
read. This can be less than the initial length if the
segment is the last in a long string.
Usage
The om_read routine reads a segment of an attribute value in a
private object, namely the subject. The segment returned is a segment
of the string value that is returned if the complete value is read in
a single call. Note that this routine enables the client to read an
arbitrarily long value without requiring that the service place a
copy of the entire value in memory.
Return Codes
On successful completion, the routine returns OM_SUCCESS in the
OM_return_code variable. Otherwise, it returns one of the following
errors:
OM_FUNCTION_INTERRUPTED
OM_MEMORY_INSUFFICIENT
OM_NETWORK_ERROR
OM_NO_SUCH_OBJECT
OM_NO_SUCH_TYPE
OM_NOT_PRESENT
OM_NOT_PRIVATE
OM_PERMANENT_ERROR
OM_POINTER_INVALID
OM_SYSTEM_ERROR
OM_TEMPORARY_ERROR
OM_WRONG_VALUE_SYNTAX
The exact constants for OM_return_code are defined in the xom.h
header file.
ΓòÉΓòÉΓòÉ 6.4.9. om_remove ΓòÉΓòÉΓòÉ
Purpose
Removes and discards values of an attribute of a private object.
Format
#include <xom.h>
OM_return_code om_remove(
OM_private_object subject,
OM_type type,
OM_value_position initial_value,
OM_value_position limiting_value);
Parameters
Input
subject The subject that remains accessible. The subject's
class is unaffected.
type Identifies the type of the attribute some of whose
values are removed. The type is not OM_CLASS.
initial_value The position within the attribute of the first value
removed.
If it is OM_ALL_VALUES or exceeds the number of values
present in the attribute, the parameter is taken to be
equal to that number.
limiting_value The position within the attribute one beyond that of
the last value removed. If this parameter is not
greater than the initial_value parameter, no values are
removed.
If it is OM_ALL_VALUES or exceeds the number of values
present in an attribute, the parameter is taken to be
equal to that number.
Usage
The om_remove routine removes and discards particular values of an
attribute of the private object specified in subject. If no values
remain, the attribute itself is also removed. If the value is a
subobject, the value is first removed and then om_delete is applied
to it, which destroys the object.
Return Codes
On successful completion, the routine returns OM_SUCCESS in the
OM_return_code variable. Otherwise, it returns one of the following
errors:
OM_FUNCTION_DECLINED
OM_FUNCTION_INTERRUPTED
OM_MEMORY_INSUFFICIENT
OM_NETWORK_ERROR
OM_NO_SUCH_OBJECT
OM_NO_SUCH_TYPE
OM_NOT_PRESENT
OM_NOT_PRIVATE
OM_PERMANENT_ERROR
OM_POINTER_INVALID
OM_SYSTEM_ERROR
OM_TEMPORARY_ERROR
The exact constants for OM_return_code are defined in the xom.h
header file.
ΓòÉΓòÉΓòÉ 6.4.10. om_write ΓòÉΓòÉΓòÉ
Purpose
Writes a segment of a string into a private object.
Format
#include <xom.h>
OM_return_code om_write(
OM_private_object subject,
OM_type type,
OM_value_position value_position,
OM_syntax syntax,
OM_string_length *string_offset,
OM_string elements);
Parameters
Input
subject The subject that remains accessible.
type Identifies the type of the attribute one of whose
values is written.
value_position The position within the above attribute of the value
to be written. The value position can neither be
negative nor exceed the number of values present. If it
equals the number of values present, the segment is
inserted into the attribute as a new value.
syntax If the value being written is not already present in
the subject, this identifies the syntax that the value
has. It must be a permissible syntax for the attribute
of which this is a value. If the value being written is
already present in the subject, then that value's
syntax is preserved and this parameter is ignored.
elements The string segment to be written. A copy of this
segment occupies a position within the string value
being written, starting at the offset given by the
string_offset input parameter. Any values already at
or beyond this offset are discarded.
Output
string_offset On input, the offset, in octets, of the start of the
string segment to be written. If it exceeds the current
length of the string value being written, the parameter
is taken to be equal to that current length. On output,
it contains the offset, in octets, after the last
string segment written. This result is present if, and
only if, the OM_return_code result is OM_SUCCESS. The
value returned in string_offset can be used as the
input string_offset parameter the next time this
routine is called. This enables sequential writing of
the value of a long string.
Usage
The om_write routine writes a segment of an attribute value in the
private object contained in the subject parameter.
The segment supplied is a segment of the string value that is
supplied if the complete value is written in a single call.
The written segment is made the last segment of the value. The
routine discards any values whose offset equals or exceeds the
string_offset result. If the value being written is in the local
representation, it is converted to the nonlocal representation (which
may entail the loss of information and which may yield a different
number of elements than that provided). Note that this routine
enables the client to write an arbitrarily long value without having
to place a copy of the entire value in memory.
Return Codes
On successful completion, the routine returns OM_SUCCESS in the
OM_return_code variable. Otherwise, it returns one of the following
errors:
OM_FUNCTION_DECLINED
OM_FUNCTION_INTERRUPTED
OM_MEMORY_INSUFFICIENT
OM_NETWORK_ERROR
OM_NO_SUCH_OBJECT
OM_NO_SUCH_SYNTAX
OM_NO_SUCH_TYPE
OM_NOT_PRESENT
OM_NOT_PRIVATE
OM_PERMANENT_ERROR
OM_POINTER_INVALID
OM_SYSTEM_ERROR
OM_TEMPORARY_ERROR
OM_WRONG_VALUE_LENGTH
OM_WRONG_VALUE_MAKEUP
OM_WRONG_VALUE_POSITION
OM_WRONG_VALUE_SYNTAX
The exact constants for OM_return_code are defined in the xom.h
header file.
ΓòÉΓòÉΓòÉ 6.4.11. omX_extract ΓòÉΓòÉΓòÉ
Purpose
Extracts the first occurrence of the requested OM type from an
object.
Format
#include <xom.h>
#include <xomext.h>
OM_return_code omX_extract(
OM_private_object object,
OM_type_list navigation_path,
OM_exclusions exclusions,
OM_type_list included_types,
OM_boolean local_strings,
OM_value_position initial_value,
OM_value_position limiting_value,
OM_public_object *values,
OM_value_position *total_number);
Parameters
Input
object The object from which data is to be extracted.
navigation_path Contains a NULL-terminated list of OM types that lead
to the target object to be extracted. This parameter
does not include the OM type of the target object.
Note: If the list contains only the NULL-terminator,
this routine is equivalent to om_get.
exclusions Explicit requests for zero or more exclusions, each of
which reduces the copy to a prescribed portion of the
original. The exclusions apply to the attributes of the
target object, but not to those of its subobjects.
Apart from OM_NO_EXCLUSIONS, each value is chosen from
the following list. When multiple exclusions are
specified, each is applied in the order in which it is
displayed in the list, with lower-numbered exclusions
having precedence over higher-numbered exclusions. If,
after the application of an exclusion, that portion of
the object is not returned, no further exclusions need
to be applied to that portion.
OM_EXCLUDE_ALL_BUT_THESE_TYPES The copy includes
descriptors comprising only attributes of
specified types.
Note: This exclusion provides a means for
determining the values of specified
attributes, as well as the syntaxes of
those values.
OM_EXCLUDE_MULTIPLES The copy includes a single
descriptor for each attribute that has two or
more values, instead of a single descriptor
for each value. None of these descriptors
contains an attribute value, and the
OM_S_NO_VALUE bit of the syntax component is
set.
If the attribute has values of two or more
syntaxes, the descriptor identifies one of
the syntaxes; however, the syntax identified
is not specified.
Note: This exclusion provides a means for
discerning the presence of multivalued
attributes without simultaneously
obtaining their values.
OM_EXCLUDE_ALL_BUT_THESE_VALUES The copy includes
descriptors comprising only values at
specified positions within an attribute.
Note: When this exclusion is used in
conjunction with the
OM_EXCLUDE_ALL_BUT_THESE_TYPES
exclusion, it provides a means for
determining the values of a specified
attribute, as well as the syntaxes of
those values, for one or more but not
all attributes at a time.
OM_EXCLUDE_VALUES The copy includes a single
descriptor for each attribute value, but the
descriptor does not contain the value, and
the OM_S_NO_VALUE bit of the syntax component
is set.
Note: This exclusion provides a means for
determining an object's composition
(that is, the type and syntax of each
of its attribute values).
OM_EXCLUDE_SUBOBJECTS For each value whose syntax
is OM_S_OBJECT, the copy includes a
descriptor containing an object handle for
the original private subobject, rather than a
public copy of it. This handle makes that
subobject accessible for use in subsequent
function calls.
Note: This exclusion provides a means for
examining an object one level at a
time.
OM_EXCLUDE_DESCRIPTORS When this exclusion is
specified, no descriptors are returned and
the copy result is not present. The
total_number parameter reflects the number of
descriptors that would be returned by
applying the other inclusion and exclusion
specifications.
Note: This exclusion provides an attribute
analysis capability. For instance, the
total number of values in a
multivalued attribute can be
determined by specifying an inclusion
of the specific attribute type, and
exclusions of OM_EXCLUDE_DESCRIPTORS,
OM_EXCLUDE_SUBOBJECTS, and
OM_EXCLUDE_ALL_BUT_THESE_TYPES.
The OM_EXCLUDE_ALL_BUT_THESE_VALUES exclusion affects
the choice of descriptors, while the OM_EXCLUDE_VALUES
exclusion affects the composition of descriptors.
included_types Identifies the types of the attributes to be included
in the copy (provided that they are displayed in the
original). This parameter contains a value if, and only
if, the OM_EXCLUDE_ALL_BUT_THESE_TYPES exclusion is
requested.
local_strings This boolean parameter indicates whether conversion to
local string format should be carried out. This
parameter is not supported.
initial_value Specifies the position, within each attribute, of the
first value to be included in the copy. This parameter
contains a value if, and only if, the
OM_EXCLUDE_ALL_BUT_THESE_VALUES exclusion is requested.
If the parameter is OM_ALL_VALUES or exceeds the number
of values present in an attribute, it is taken to be
equal to that number.
limiting_value Specifies the position, within each attribute, of one
beyond that of the last value to be included in the
copy. If this parameter is not greater than the
initial_value parameter, no values are included (and no
descriptors are returned). This parameter contains a
value if, and only if, the
OM_EXCLUDE_ALL_BUT_THESE_VALUES exclusion is requested.
If the parameter is OM_ALL_VALUES or exceeds the number
of values present in an attribute, it is taken to be
equal to that number.
Output
values The values parameter is present only if the return
value from OM_return_code is OM_SUCCESS and the
OM_EXCLUDE_DESCRIPTORS exclusion is not specified. It
contains the array of OM descriptors extracted.
The memory space for values is provided by omX_extract.
It is the responsibility of the calling application to
subsequently release this space with a call to
om_delete.
total_number The number of attribute descriptors returned in the
public object, but not in any of its subobjects, based
on the inclusion and exclusion parameters specified. If
the OM_EXCLUDE_DESCRIPTORS exclusion is specified, no
values result is returned and the total_number result
reflects the actual number of attribute descriptors
that would be returned based on the remaining inclusion
and exclusion values.
Note: The total includes only the attribute
descriptors in the values parameter. It excludes
the special descriptor signaling the end of a
public object.
Usage
The omX_extract routine creates a new public object that is an exact,
but independent, copy of an existing subobject in a private object.
It is similar to the om_get routine but includes an additional
parameter, navigation_path, which contains directions to the required
object to be extracted. The client can request certain exclusions,
each of which reduces the copy to a part of the original.
One exclusion is always requested implicitly. For each attribute
value in the original that is a string whose length exceeds an
implementation-defined number, the values parameter includes a
descriptor that omits the elements (but not the length) of the
string. The elements component of the string component in the
descriptor's value component is OM_ELEMENTS_UNSPECIFIED, and the
OM_S_LONG_STRING bit of the syntax component is set to OM_TRUE.
The parameters exclusions, included_types, local_strings,
initial_value, and limiting_value only apply to the target object
being extracted.
Note: String lengths of up to 4000 bytes are valid. The maximum
length of a CDS attribute value is 4000 bytes. The client can
also access long values by means of om_read.
Return Codes
On successful completion, the routine returns OM_SUCCESS in the
OM_return_code variable. Otherwise, it returns one of the constants
defined in the xom.h header file.
ΓòÉΓòÉΓòÉ 6.4.12. omX_fill ΓòÉΓòÉΓòÉ
Purpose
Initializes an OM_descriptor structure.
Format
#include <xom.h>
#include <xomext.h>
OM_return_code omX_fill(
OM_type type,
OM_syntax syntax,
OM_uint32 length,
void *elements,
OM_descriptor *destination);
Parameters
Input
type The type of OM descriptor structure.
syntax The syntax value for this OM descriptor.
length The data length for values of string syntax. Zero is
entered for values of type OM_object. When initializing
an OM_descriptor with an OM_type that has an OM_syntax
of either OM_S_INTEGER, OM_S_BOOLEAN or
OM_S_ENUMERATION, the associated value must be entered
in the length parameter.
elements The string contents.
Output
destination Contains the filled descriptor.
Note: The user must provide the storage for the
OM_descriptor. The address is passed as input in
the destination parameter.
Usage
The omX_fill routine is used to initialize an OM_descriptor structure
with user-supplied values for its type, syntax, and value.
Return Codes
On successful completion, the routine returns OM_SUCCESS in the
OM_return_code variable. Otherwise, it returns one of the constants
defined in the xom.h header file.
ΓòÉΓòÉΓòÉ 6.4.13. omX_fill_oid ΓòÉΓòÉΓòÉ
Purpose
Initializes an OM_descriptor structure with an object identifier
value.
Format
#include <xom.h>
#include <xomext.h>
OM_return_code omX_fill_oid(
OM_type type,
OM_object_identifier object_id,
OM_descriptor *destination);
Parameters
Input
type The type of OM_descriptor structure.
object_id The object identifier value.
Output
destination Contains the filled descriptor.
Note: The user must provide the storage for the
OM_descriptor. The address is passed as input in
the destination parameter.
Usage
The omX_fill_oid routine is used to initialize an OM_descriptor
structure with user-supplied values for its type and value. The
syntax of the descriptor is always set to
OM_S_OBJECT_IDENTIFIER_STRING.
Return Codes
On successful completion, the routine returns OM_SUCCESS in the
OM_return_code variable. Otherwise, it returns one of the constants
defined in the xom.h header file.
ΓòÉΓòÉΓòÉ 6.4.14. omX_object_to_string ΓòÉΓòÉΓòÉ
Purpose
Converts an OM object from descriptor to string format.
Format
#include <xom.h>
#include <xomext.h>
OM_return_code omX_object_to_string(
OM_object object,
OM_boolean local_strings,
OM_string *string);
Parameters
Input
object Contains the OM object to be converted.
local_strings This boolean parameter indicates whether conversion to
local string format should be carried out. This
parameter is not supported.
Output
string Contains the converted object in string format. The
calling routine should provide the memory for string.
The string's contents are initially unspecified. The
string's length becomes the number of octets required
to contain the segment that the routine is to read. The
service modifies this parameter. The string's elements
become the elements actually read. The string's length
becomes the number of octets required to hold the
segment actually read.
Usage
The omX_object_to_string routine converts an OM object into a string
format. The object can either be a client-generated or a
service-generated public or private object.
The objects that can be handled by this routine are restricted to
those defined in the schema file, xschema. Additionally, the OM
objects DS_C_ATTRIBUTE_ERROR and DS_C_ERROR are also handled. For
these, a message string containing the error message is returned.
For the syntax of the output strings please refer to XDS/XOM
Convenience Routines.
Return Codes
On successful completion, the routine returns OM_SUCCESS in the
OM_return_code variable. Otherwise, it returns one of the constants
defined in the xom.h header file.
ΓòÉΓòÉΓòÉ 6.4.15. omX_string_to_object ΓòÉΓòÉΓòÉ
Purpose
Converts an OM object specified in string format to descriptor
format.
Format
#include <xom.h>
#include <xomext.h>
OM_return_code omX_string_to_object(
OM_workspace workspace,
OM_string *string,
OM_object_identifier class,
OM_boolean local_strings,
OM_private_object *object,
OM_integer *error_position,
OM_integer *error_type);
Parameters
Input
workspace The workspace pointer obtained from a ds_initialize
call.
string The string to be converted. For details of the string
syntaxes allowed, refer to XDS/XOM Convenience
Routines.
class The OM class of the object to be created.
local_strings This boolean parameter indicates whether conversion to
local string format should be carried out. This
parameter is not supported.
Output
object The converted object.
error_position If the input string contains a syntax error,
error_position indicates the position in the string
where the error was detected.
error_type Indicates the type of error (for example, Attribute
Abbreviation expected, '/' expected, and so on...).
Refer to the xomext.h header file for explanations of
the error types.
Usage
The omX_string_to_object routine creates a new private object, which
is built from the string and class input parameters. The objects that
can be created by this routine are restricted to those defined in the
schema file, xschema.
For the syntax of the input strings please refer to XDS/XOM
Convenience Routines.
Notes
The memory space for the object return parameter is allocated by
omX_string_to_object. The calling application is responsible for
releasing this memory with a call to the om_delete routine.
Return Codes
On successful completion, the routine returns OM_SUCCESS in the
OM_return_code variable. Otherwise, it returns one of the constants
defined in the xom.h header file.
If there is a syntax error in the input string, OM_return_code is set
to OM_WRONG_VALUE_MAKEUP and the type of error is returned in
error_type. Refer to the xomext.h header file for explanations of the
error types.
ΓòÉΓòÉΓòÉ 7. The DCE Distributed Time Service API ΓòÉΓòÉΓòÉ
The DCE Distributed Time Service (DTS) programming routines can obtain
timestamps that are based on Coordinated Universal Time (UTC), translate
between different timestamp formats, and perform calculations on timestamps.
Applications can call the DTS routines from server or clerk systems and use the
timestamps that DTS supplies to determine event sequencing, duration, and
scheduling.
The DTS routines can perform the following basic functions:
o Retrieve the current (UTC-based) time from DTS.
o Convert binary timestamps expressed in the utc time structure to or from
tm structure components.
o Convert the binary timestamps expressed in the utc time structure to or
from timespec structure components.
o Convert the binary timestamps expressed in the utc time structure to or
from ASCII text strings.
o Compare two binary time values.
o Calculate binary time values.
o Obtain time zone information.
DTS can convert between several types of binary time structures that are based
on different calendars and time unit measurements. DTS uses UTC-based time
structures, and can convert other types of time structures to its own
presentation of UTC-based time.
See the following subtopics for more information:
Time Service Terms
Time Service Default Values
Time Service Routine Categories
Time Service Routines
ΓòÉΓòÉΓòÉ 7.1. Time Service Terms ΓòÉΓòÉΓòÉ
Following are definitions of terms used throughout this chapter:
Absolute time
An interval on a time scale; absolute time measurements are
derived from system clocks or external time-providers. For DTS,
absolute times reference the UTC standard and include inaccuracy
and other information. When you display an absolute time, DTS
converts the time to ASCII text string:
1990-11-21-13:30:25.785-04:00I000.082
Relative time
A discrete time interval that is often added to or subtracted
from an absolute time. A Time Differential Factor (TDF)
associated with an absolute time is one example of a relative
time. Note that a relative time does not use the calendar date
fields, since these fields concern absolute time.
Coordinated Universal Time (UTC)
The international time standard that DTS uses. The zero hour of
UTC is based on the zero hour of Greenwich Mean Time (GMT). The
documentation consistently refers to the time zone of the
Greenwich Meridian as GMT. However, this time zone is also
sometimes referred to as UTC.
Reference information for the localtime system routine provides
additional details.
The Time Differential Factor (TDF)
The difference between UTC and the time in a particular time
zone.
The user's environment determines the time zone rule (details are
system-dependent).
If the user's environment does not specify a time zone rule, the system's rule
is used (details of the rule are system-dependent).
The DCE for OS/2 Warp: Application Development Guide - Core Components
provides additional information about UTC and GMT, TDF and time zones, and
relative and absolute times.
ΓòÉΓòÉΓòÉ 7.2. Time Service Default Values ΓòÉΓòÉΓòÉ
Unless otherwise specified, the default input and output parameters are:
o If NULL is specified for a utc input parameter, the current time is used.
o If NULL is specified for any output parameter, no result is returned.
ΓòÉΓòÉΓòÉ 7.3. Time Service Routine Categories ΓòÉΓòÉΓòÉ
The following illustration categorizes the DTS portable interface routines by
function.
DTS API Routines Shown by Functional Grouping
ΓòÉΓòÉΓòÉ 7.4. Time Service Routines ΓòÉΓòÉΓòÉ
An alphabetical listing of the DTS portable interface routines and a brief
description of each one follows:
utc_abstime Computes the absolute value of a relative binary
timestamp.
utc_addtime Computes the sum of two binary timestamps; the
timestamps can be two relative times or a relative time
and an absolute time.
utc_anytime Converts a binary timestamp to a tm structure, using the
TDF information contained in the timestamp to determine
the TDF returned with the tm structure.
utc_anyzone Gets the time zone label and offset from GMT, using the
TDF contained in the utc input parameter.
utc_ascanytime Converts a binary timestamp to an ASCII text string that
represents an arbitrary time zone.
utc_ascgmtime Converts a binary timestamp to an ASCII text string that
expresses a GMT time.
utc_asclocaltime Converts a binary timestamp to an ASCII text string that
represents a local time.
utc_ascreltime Converts a relative binary timestamp to an ASCII text
string that represents the time.
utc_binreltime Converts a relative binary timestamp to two timespec
structures that express relative time and inaccuracy.
utc_bintime Converts a binary timestamp to a timespec structure.
utc_boundtime Returns a single UTC time whose inaccuracy includes an
event, given two UTC times, one before and one after the
event.
utc_cmpintervaltime Compares two binary timestamps or two relative binary
timestamps.
utc_cmpmidtime Compares two binary timestamps or two relative binary
timestamps, ignoring inaccuracies.
utc_gettime Returns the current system time and inaccuracy as a
binary timestamp.
utc_getusertime Returns the time and process-specific TDF, rather than
the system-specific TDF.
utc_gmtime Converts a binary timestamp to a tm structure that
expresses GMT or the equivalent UTC.
utc_gmtzone Gets the time zone label for GMT.
utc_localtime Converts a binary timestamp to a tm structure that
expresses local time.
utc_localzone Gets the local time zone label and offset from GMT,
given a utc time.
utc_mkanytime Converts a tm structure and TDF (expressing the time in
an arbitrary time zone) to a binary timestamp.
utc_mkascreltime Converts a NULL-terminated character string that
represents a relative timestamp to a binary timestamp.
utc_mkasctime Converts a NULL-terminated character string that
represents an absolute timestamp to a binary timestamp.
utc_mkbinreltime Converts a timespec structure expressing a relative time
to a binary timestamp.
utc_mkbintime Converts a timespec structure to a binary timestamp.
utc_mkgmtime Converts a tm structure that expresses GMT or UTC to a
binary timestamp.
utc_mklocaltime Converts a tm structure that expresses local time to a
binary timestamp.
utc_mkreltime Converts a tm structure that expresses relative time to
a relative binary timestamp.
utc_mulftime Multiplies a relative binary timestamp by a
floating-point value.
utc_multime Multiplies a relative binary timestamp by an integer
factor.
utc_pointtime Converts a binary timestamp to three binary timestamps
that represent the earliest, most likely, and latest
time.
utc_reltime Converts a relative binary timestamp to a tm structure.
utc_spantime Given two (possibly unordered) binary timestamps,
returns a single UTC time interval whose inaccuracy
spans the two input binary timestamps.
utc_subtime Computes the difference between two binary timestamps
that express either an absolute time and a relative
time, two relative times, or two absolute times.
ΓòÉΓòÉΓòÉ 7.4.1. utc_abstime ΓòÉΓòÉΓòÉ
Purpose
Computes the absolute value of a relative binary timestamp.
Format
#include <dce\utc.h>
int utc_abstime(
utc_t *result,
utc_t *utc);
Parameters
Input
utc Relative binary timestamp. Use NULL if you want this
routine to use the current time for this parameter.
Output
result Absolute value of the input relative binary timestamp.
Usage
The utc_abstime routine computes the absolute value of a relative
binary timestamp. The input timestamp represents a relative (delta)
time.
Return Codes
0 Indicates that the routine ran successfully.
-1 Indicates an invalid time parameter or invalid results.
Examples
The following example scales a relative time, computes its absolute
value, and prints the result.
utc_t relutc, scaledutc;
char timstr[UTC_MAX_STR_LEN];
/*
* Make sure relative timestamp represents a positive interval.
*/
utc_abstime(&relutc, /* Out: Abs-value of rel time */
&relutc); /* In: Relative time to scale */
/*
* Scale it by a factor of 17...
*/
utc_multime(&scaledutc, /* Out: Scaled relative time */
&relutc, /* In: Relative time to scale */
17L); /* In: Scale factor */
utc_ascreltime(timstr, /* Out: ASCII relative time */
UTC_MAX_STR_LEN, /* In: Length of input string */
&scaledutc); /* In: Relative time to */
/* convert */
printf("%s\n",timstr);
/*
* Scale it by a factor of 17.65...
*/
utc_mulftime(&scaledutc, /* Out: Scaled relative time */
&relutc, /* In: Relative time to scale */
17.65); /* In: Scale factor */
utc_ascreltime(timstr, /* Out: ASCII relative time */
UTC_MAX_STR_LEN, /* In: Length of input string */
&scaledutc); /* In: Relative time to */
/* convert */
printf("%s\n",timstr);
ΓòÉΓòÉΓòÉ 7.4.2. utc_addtime ΓòÉΓòÉΓòÉ
Purpose
Computes the sum of two binary timestamps.
Format
#include <dce\utc.h>
int utc_addtime(
utc_t result,
utc_t *utc1,
utc_t *utc2);
Parameters
Input
utc1 Binary timestamp or relative binary timestamp. Use NULL
if you want this routine to use the current time for
this parameter.
utc2 Binary timestamp or relative binary timestamp. Use NULL
if you want this routine to use the current time for
this parameter.
Output
result Resulting binary timestamp or relative binary
timestamp, depending upon the operation performed:
o relative time + relative time = relative time
o absolute time + relative time = absolute time
o relative time + absolute time = absolute time
o absolute time + absolute time is undefined (see
the note later in this section).
Usage
The utc_addtime routine adds two binary timestamps, producing a third
binary timestamp whose inaccuracy is the sum of the two input
inaccuracies. One or both of the input timestamps typically
represents a relative (delta) time. The TDF in the first input
timestamp is copied to the output. The timestamps can be two relative
times or a relative time and an absolute time.
Notes
Although no error is returned, the combination absolute time +
absolute time should not be used.
Return Codes
0 Indicates that the routine ran successfully.
-1 Indicates an invalid time parameter or invalid results.
Examples
The following example shows how to compute a timestamp that
represents a time at least five seconds in the future.
utc_t now, future, fivesec;
reltimespec_t tfivesec;
timespec_t tzero;
/*
* Construct a timestamp that represents 5 seconds...
*/
tfivesec.tv_sec = 5;
tfivesec.tv_nsec = 0;
tzero.tv_sec = 0;
tzero.tv_nsec = 0;
utc_mkbinreltime(&fivesec, /* Out: 5 secs in binary timestamp */
&tfivesec, /* In: 5 secs in timespec */
&tzero); /* In: 0 secs inaccuracy in timespec */
/*
* Get the maximum possible current time.*
* (The NULL input parameter is used to specify the current time.)
*/
utc_pointtime((utc_t *)0, /* Out: Earliest possible current time */
(utc_t *)0, /* Out: Midpoint of current time */
&now, /* Out: Latest possible current time */
(utc_t *)0); /* In: Use current time */
/*
* Add 5 seconds to get future timestamp...
*/
utc_addtime(&future, /* Out: Future binary timestamp */
&now, /* In: Latest possible time now */
&fivesec); /* In: 5 secs */
Related Information
Routines:
utc_subtime
ΓòÉΓòÉΓòÉ 7.4.3. utc_anytime ΓòÉΓòÉΓòÉ
Purpose
Converts a binary timestamp to a tm structure.
Format
#include <dce\utc.h>
int utc_anytime(
struct tm *timetm,
long *tns,
struct tm *inacctm,
long *ins,
long *tdf,
utc_t *utc);
Parameters
Input
utc Binary timestamp. Use NULL if you want this routine to
use the current time for this parameter.
Output
timetm Time component of the binary timestamp expressed in the
timestamp's local time.
tns Nanoseconds since the Time component of the binary
timestamp.
inacctm Seconds of inaccuracy component of the binary
timestamp. If the inaccuracy is finite, tm_mday returns
a value of -1 and tm_mon and tm_year return values of
0. The field tm_yday contains the inaccuracy in days.
If the inaccuracy is unspecified, all tm structure
fields return values of -1.
ins Nanoseconds of inaccuracy component of the binary
timestamp.
tdf TDF component of the binary timestamp in units of
seconds east of GMT.
Usage
The utc_anytime routine converts a binary timestamp to a tm structure
using the TDF information contained in the timestamp to determine the
TDF returned with the tm structure. The TDF information contained in
the timestamp is returned with the time and inaccuracy components;
the TDF component determines the offset from GMT and the local time
value of the tm structure. Additional returns include nanoseconds
since Time and nanoseconds of inaccuracy.
Return Codes
0 Indicates that the routine ran successfully.
-1 Indicates an invalid time argument or invalid results.
Examples
The following example converts a timestamp, using the TDF information
in the timestamp, and then prints the result.
utc_t evnt;
struct tm tmevnt;
timespec_t tevnt, ievnt;
char tznam[80];
/*
* Assume evnt contains the timestamp to convert...
*
* Get time as a tm structure, using the time zone information in
* the timestamp...
*/
utc_anytime(&tmevnt, /* Out: tm struct of time of evnt */
(long *)0, /* Out: nanosec of time of evnt */
(struct tm *)0, /* Out: tm struct of inacc of evnt */
(long *)0, /* Out: nanosec of inacc of evnt */
(int *)0, /* Out: tdf of evnt */
&evnt); /* In: binary timestamp of evnt */
/*
* Get the time and inaccuracy as timespec structures...
*/
utc_bintime(&tevnt, /* Out: timespec of time of evnt */
&ievnt, /* Out: timespec of inacc of evnt */
(int *)0, /* Out: tdf of evnt */
&evnt); /* In: Binary timestamp of evnt */
/*
* Construct the time zone name from time zone information in the
* timestamp...
*/
utc_anyzone(tznam, /* Out: Time zone name */
80, /* In: Size of time zone name */
(long *)0, /* Out: tdf of event */
(long *)0, /* Out: Daylight saving flag */
&evnt); /* In: Binary timestamp of evnt */
/*
* Print timestamp in the format:
*
* 1991-03-05-21:27:50.023I0.140 (GMT-5:00)
* 1992-04-02-12:37:24.003Iinf (GMT+7:00)
*
*/
printf("%d-%02d-%02d-%02d:%02d:%02d.%03d",
tmevnt.tm_year+1900, tmevnt.tm_mon+1, tmevnt.tm_mday,
tmevnt.tm_hour, tmevnt.tm_min, tmevnt.tm_sec,
(tevnt.tv_nsec/1000000));
if ((long)ievnt.tv_sec == -1)
printf("Iinf");
else
printf("I%d.%03d", ievnt.tv_sec, (ievnt.tv_nsec/1000000));
printf(" (%s)", tznam);
Related Information
Routines:
utc_mkanytime
utc_anyzone
utc_gettime
utc_getusertime
utc_gmtime
utc_localtime
ΓòÉΓòÉΓòÉ 7.4.4. utc_anyzone ΓòÉΓòÉΓòÉ
Purpose
Gets the time zone label and offset from GMT, using the TDF contained
in the input utc.
Format
#include <dce\utc.h>
int utc_anyzone(
char *tzname,
size_t tzlen,
long *tdf,
int *isdst,
utc_t *utc);
Parameters
Input
tzlen Length of the tzname buffer.
utc Binary timestamp. Use NULL if you want this routine to
use the current time for this parameter.
Output
tzname Character string that is long enough to hold the time
zone label.
tdf Longword with differential in seconds east of GMT.
isdst Integer with a value of -1, indicating that no
information is supplied as to whether it is Standard
Time or Daylight Savings Time. A value of -1 is always
returned.
Usage
The utc_anyzone routine gets the time zone label and offset from GMT
by using the TDF contained in the utc input parameter. The label
returned is always of the form GMT+n or GMT-n where n is the tdf
expressed in hours:minutes. (The label associated with an arbitrary
time zone is not known; only the offset is known.)
Notes
All of the Output parameters are optional. No value is returned and
no error occurs if the pointer is NULL.
Return Codes
0 Indicates that the routine ran successfully.
-1 Indicates an invalid time argument or an insufficient buffer.
Examples
See the example in utc_anytime.
Related Information
Routines:
utc_anytime
utc_gmtzone
utc_localzone
ΓòÉΓòÉΓòÉ 7.4.5. utc_ascanytime ΓòÉΓòÉΓòÉ
Purpose
Converts a binary timestamp to an ASCII text string that represents
an arbitrary time zone.
Format
#include <dce\utc.h>
int utc_ascanytime(
char *cp,
size_t stringlen,
utc_t *utc);
Parameters
Input
stringlen The length of the cp buffer.
utc Binary timestamp. Use NULL if you want this routine to
use the current time for this parameter.
Output
cp An ASCII text string that represents the time.
Usage
The utc_ascanytime routine converts a binary timestamp to an ASCII
string that expresses a time. The TDF component in the timestamp
determines the local time used in the conversion.
Return Codes
0 Indicates that the routine ran successfully.
-1 Indicates an invalid time parameter or invalid results.
Examples
The following example converts a time to an ASCII text string that
expresses the time in the time zone where the timestamp was
generated.
utc_t evnt;
char localTime[UTC_MAX_STR_LEN];
/*
* Assuming that evnt contains the timestamp to convert, convert
* the time to ASCII in the following format:
*
* 1991-04-01-12:27:38.37-8:00I2.00
*/
utc_ascanytime(localtime, /* Out: Converted time */
UTC_MAX_STR_LEN, /* In: Length of string */
&evnt); /* In: Time to convert */
Related Information
Routines:
utc_ascgmtime
utc_asclocaltime
ΓòÉΓòÉΓòÉ 7.4.6. utc_ascgmtime ΓòÉΓòÉΓòÉ
Purpose
Converts a binary timestamp to an ASCII text string that expresses a
GMT time.
Format
#include <dce\utc.h>
int utc_ascgmtime(
char *cp,
size_t stringlen,
utc_t *utc);
Parameters
Input
stringlen Length of the cp buffer.
utc Binary timestamp.
Output
cp An ASCII text string that represents the time.
Usage
The utc_ascgmtime routine converts a binary timestamp to an ASCII
text string that expresses a time in GMT.
Return Codes
0 Indicates that the routine ran successfully.
-1 Indicates an invalid time parameter or invalid results.
Examples
The following example converts the current time to GMT format.
char gmTime[UTC_MAX_STR_LEN];
/*
* Convert the current time to ASCII in the following format:
*
* 1991-04-01-12:27:38.37I2.00
*/
utc_ascgmtime(gmTime, /* Out: Converted time */
UTC_MAX_STR_LEN, /* In: Length of string */
(utc_t*) NULL); /* In: Time to convert */
/* Default is current time */
Related Information
Routines:
utc_ascanytime
utc_asclocaltime
ΓòÉΓòÉΓòÉ 7.4.7. utc_asclocaltime ΓòÉΓòÉΓòÉ
Purpose
Converts a binary timestamp to an ASCII text string that represents a
local time.
Format
#include <dce\utc.h>
int utc_asclocaltime(
char *cp,
size_t stringlen,
utc_t *utc);
Parameters
Input
stringlen Length of the cp buffer.
utc Binary timestamp. Use NULL if you want this routine to
use the current time for this parameter.
Output
cp An ASCII text string that represents the time.
Usage
The utc_asclocaltime routine converts a binary timestamp to an ASCII
text string that expresses local time.
The user's environment determines the time zone rule (details are
system dependent). For example, on OS/2 systems, the user selects a
time zone by specifying the TZ environment variable.
If the user's environment does not specify a time zone rule, the
system's rule is used (details of the rule are system dependent.) For
example, on OS/2 systems, the rule in the localtime file is used.
Return Codes
0 Indicates that the routine ran successfully.
-1 Indicates an invalid time parameter or invalid results.
Examples
The following example converts the current time to local time.
char localTime[UTC_MAX_STR_LEN];
/*
* Convert the current time...
*/
utc_asclocaltime(localTime, /* Out: Converted time */
UTC_MAX_STR_LEN, /* In: Length of string */
(utc_t*) NULL); /* In: Time to convert */
/* Default is current time */
Related Information
Routines:
utc_ascanytime
utc_ascgmtime
ΓòÉΓòÉΓòÉ 7.4.8. utc_ascreltime ΓòÉΓòÉΓòÉ
Purpose
Converts a relative binary timestamp to an ASCII text string that
represents the time.
Format
#include <dce\utc.h>
int utc_ascreltime(
char *cp,
const size_t stringlen,
utc_t *utc);
Parameters
Input
utc Relative binary timestamp. Use NULL if you want this
routine to use the current time for this parameter.
stringlen Length of the cp buffer.
Output
cp An ASCII text string that represents the time.
Usage
The utc_ascreltime routine converts a relative binary timestamp to an
ASCII text string that represents the time.
Return Codes
0 Indicates that the routine ran successfully.
-1 Indicates an invalid time parameter or invalid results.
Examples
See the example in utc_abstime.
Related Information
Routines:
utc_mkascreltime
ΓòÉΓòÉΓòÉ 7.4.9. utc_binreltime ΓòÉΓòÉΓòÉ
Purpose
Converts a relative binary timestamp to two timespec structures that
express relative time and inaccuracy.
Format
#include <dce\utc.h>
int utc_binreltime(
reltimespec_t *timesp,
timespec_t *inaccsp,
utc_t *utc);
Parameters
Input
utc Relative binary timestamp. Use NULL if you want this
routine to use the current time for this parameter.
Output
timesp Time component of the relative binary timestamp, in the
form of seconds and nanoseconds since the base time
(1970-01-01:00:00:00.0+00:00I0).
inaccsp Inaccuracy component of the relative binary timestamp,
in the form of seconds and nanoseconds.
Usage
The utc_binreltime routine converts a relative binary timestamp to
two timespec structures that express relative time and inaccuracy.
These timespec structures describe a time interval.
Return Codes
0 Indicates that the routine ran successfully.
-1 Indicates an invalid time argument or invalid results.
Examples
The following example measures the duration of a process, then prints
the resulting relative time and inaccuracy.
utc_t before, duration;
reltimespec_t tduration;
timespec_t iduration;
/*
* Get the time before the start of the operation...
*/
utc_gettime(&before); /* Out: Before binary timestamp */
/*
* ...Later...
* Subtract, getting the duration as a relative time.
*
* NOTE: The NULL argument is used to obtain the current time.
*/
utc_subtime(&duration, /* Out: Duration rel bin timestamp */
(utc_t *)0, /* In: After binary timestamp */
&before); /* In: Before binary timestamp */
/*
* Convert the relative times to timespec structures...
*/
utc_binreltime(&tduration, /* Out: Duration time timespec */
&iduration, /* Out: Duration inacc timespec */
&duration); /* In: Duration rel bin timestamp */
/*
* Print the duration...
*/
printf("%d.%04d", tduration.tv_sec, (tduration.tv_nsec/10000));
if ((long)iduration.tv_sec == -1)
printf("Iinf\n");
else
printf("I%d.%04d\n", iduration.tv_sec, (iduration.tv_nsec/100000));
Related Information
Routines:
utc_mkbinreltime
ΓòÉΓòÉΓòÉ 7.4.10. utc_bintime ΓòÉΓòÉΓòÉ
Purpose
Converts a binary timestamp to a timespec structure.
Format
#include <dce\utc.h>
int utc_bintime(
timespec_t *timesp,
timespec_t *inaccsp,
long *tdf,
utc_t *utc);
Parameters
Input
utc Binary timestamp. Use NULL if you want this routine to
use the current time for this parameter.
Output
timesp Time component of the binary timestamp, in the form of
seconds and nanoseconds since the base time.
inaccsp Inaccuracy component of the binary timestamp, in the
form of seconds and nanoseconds.
tdf TDF component of the binary timestamp in the form of
signed number of seconds east of GMT.
Usage
The utc_bintime routine converts a binary timestamp to a timespec
structure. The TDF information contained in the timestamp is
returned.
Return Codes
0 Indicates that the routine ran successfully.
-1 Indicates an invalid time argument or invalid results.
Examples
See the example in utc_anytime.
Related Information
Routines:
utc_binreltime
utc_mkbintime
ΓòÉΓòÉΓòÉ 7.4.11. utc_boundtime ΓòÉΓòÉΓòÉ
Purpose
Returns a single UTC time whose inaccuracy includes an event, given
two UTC times, one before and one after the event.
Format
#include <dce\utc.h>
int utc_boundtime(
utc_t *result,
utc_t *utc1,
utc_t *utc2);
Parameters
Input
utc1 Before binary timestamp or relative binary timestamp.
Use NULL if you want this routine to use the current
time for this parameter.
utc2 After binary timestamp or relative binary timestamp.
Use NULL if you want this routine to use the current
time for this parameter.
Output
result Spanning timestamp.
Usage
Given two UTC times, the utc_boundtime routine returns a single UTC
time whose inaccuracy bounds the two input times. This is useful for
timestamping events; the routine gets the utc values before and after
the event and then calls utc_boundtime to build a timestamp that
includes the event.
Notes
The TDF in the output UTC value is copied from the utc2 input. If
one or both input values have infinite inaccuracies, the returned
time value also has an unspecified inaccuracy and is the average of
the two input values.
Return Codes
0 Indicates that the routine ran successfully.
-1 Indicates an invalid time parameter or invalid parameter order.
Examples
The following example records the time of an event and constructs a
single timestamp, which includes the time of the event. Note that
the utc_getusertime routine is called so the time zone information
that is included in the timestamp references the user's environment
rather than the system's default time zone.
The user's environment determines the time zone rule (details are
system dependent). For example, on OS/2 systems, the user selects a
time zone by specifying the TZ environment variable.
If the user's environment does not specify a time zone rule, the
system's rule is used (details of the rule are system dependent). For
example, on OS/2 systems, the rule in the localtime file is used.
utc_t before, after, evnt;
/*
* Get the time before the event...
*/
utc_getusertime(&before); /* Out: Before binary timestamp */
/*
* Get the time after the event...
*/
utc_getusertime(&after); /* Out: After binary timestamp */
/*
* Construct a single timestamp that describes the time of the
* event...
*/
utc_boundtime(&evnt, /* Out: Timestamp that bounds event */
&before, /* In: Before binary timestamp */
&after); /* In: After binary timestamp */
Related Information
Routines:
utc_gettime
utc_pointtime
utc_spantime
ΓòÉΓòÉΓòÉ 7.4.12. utc_cmpintervaltime ΓòÉΓòÉΓòÉ
Purpose
Compares two binary timestamps or two relative binary timestamps.
Format
#include <dce\utc.h>
int utc_cmpintervaltime(
enum utc_cmptype *relation,
utc_t *utc1,
utc_t *utc2);
Parameters
Input
utc1 Binary timestamp or relative binary timestamp. Use NULL
if you want this routine to use the current time for
this parameter.
utc2 Binary timestamp or relative binary timestamp. Use NULL
if you want this routine to use the current time for
this parameter.
Output
relation Receives the result of the comparison of utc1:utc2
where the result is an enumerated type with one of the
following values:
o utc_equalTo
o utc_lessThan
o utc_greaterThan
o utc_indeterminate
Usage
The utc_cmpintervaltime routine compares two binary timestamps and
returns a flag indicating that the first time is greater than, less
than, equal to, or overlapping with the second time. Two times
overlap if the intervals (time - inaccuracy, time - inaccuracy) of
the two times intersect.
The input binary timestamps express two absolute or two relative
times. Do not compare relative binary timestamps and absolute binary
timestamps. If you do, no meaningful results and no errors are
returned.
The following routine does a temporal ordering of the time intervals.
utc1 is utc_lessThan utc2 iff
utc1.time + utc1.inacc < utc2.time - utc2.inacc
utc1 is utc_greaterThan utc2 iff
utc1.time - utc1.inacc > utc2.time + utc2.inacc
utc1 utc_equalTo utc2 iff
utc1.time == utc2.time and
utc1.inacc == 0 and
utc2.inacc == 0
utc1 is utc_indeterminate with respect to utc2 if the intervals
overlap.
Return Codes
0 Indicates that the routine ran successfully.
-1 Indicates an invalid time argument.
Examples
The following example checks to see if the current time is definitely
after 13:00 local time.
struct tm tmtime, tmzero;
enum utc_cmptype relation;
utc_t testtime;
/*
* Zero the tm structure for inaccuracy...
*/
memset(&tmzero, 0, sizeof(tmzero));
/*
* Get the current time, mapped to a tm structure...
*
* NOTE: The NULL argument is used to get the current time.
*/
utc_gmtime(&tmtime, /* Out: Current GMT time in tm struct */
(long *)0, /* Out: Nanoseconds of time */
(struct tm *)0, /* Out: Current inaccuracy in tm struct */
(long *)0, /* Out: Nanoseconds of inaccuracy */
(utc_t *)0); /* In: Current timestamp */
/*
* Construct a tm structure that corresponds to 13:00 local time...
*/
tmtime.tm_hour = 13;
tmtime.tm_min = 0;
tmtime.tm_sec = 0;
/*
* Convert to a binary timestamp...
*/
utc_mkgmtime(&testtime, /* Out: Binary timestamp of 13:00 */
&tmtime, /* In: 1:00 PM in tm struct */
0, /* In: Nanoseconds of time */
&tmzero, /* In: Zero inaccuracy in tm struct */
0); /* In: Nanoseconds of inaccuracy */
/*
* Compare to the current time. Note the use of the NULL argument...
*/
utc_cmpintervaltime(&relation, /* Out: Comparison relation */
(utc_t *)0, /* In: Current timestamp */
&testtime); /* In: 13:00 timestamp */
/*
* If it is not later - wait, print a message, etc.
*/
if (relation != utc_greaterThan) {
/*
* Note: It could be earlier than 13:00 or it could be
* indeterminate. If indeterminate, for some applications
* it might be worth waiting.
*/
}
Related Information
Routines:
utc_cmpmidtime
ΓòÉΓòÉΓòÉ 7.4.13. utc_cmpmidtime ΓòÉΓòÉΓòÉ
Purpose
Compares two binary timestamps or two relative binary timestamps,
ignoring inaccuracies.
Format
#include <dce\utc.h>
int utc_cmpmidtime(
enum utc_cmptype *relation,
utc_t *utc1,
utc_t *utc2);
Parameters
Input
utc1 Binary timestamp or relative binary timestamp. Use NULL
if you want this routine to use the current time for
this parameter.
utc2 Binary timestamp or relative binary timestamp. Use NULL
if you want this routine to use the current time for
this parameter.
Output
relation Result of the comparison of utc1:utc2 where the result
is an enumerated type with one of the following values:
o utc_equalTo
o utc_lessThan
o utc_greaterThan.
Usage
The utc_cmpmidtime routine compares two binary timestamps and returns
a flag indicating that the first timestamp is greater than, less
than, or equal to the second timestamp. Inaccuracy information is
ignored for this comparison; the input values are therefore
equivalent to the midpoints of the time intervals described by the
input binary timestamps.
The input binary timestamps express two absolute or two relative
times. Do not compare relative binary timestamps to absolute binary
timestamps. If you do, no meaningful results and no errors are
returned.
The following routine does a lexical ordering on the time interval
midpoints.
utc1 is utc_lessThan utc2 iff
utc1.time < utc2.time
utc1 is utc_greaterThan utc2 iff
utc1.time > utc2.time
utc1 is utc_equalTo utc2 iff
utc1.time == utc2.time
Return Codes
0 Indicates that the routine ran successfully.
-1 Indicates an invalid time argument.
Examples
The following example checks if the current time (ignoring
inaccuracies) is after 13:00 local time.
struct tm tmtime, tmzero;
enum utc_cmptype relation;
utc_t testtime;
/*
* Zero the tm structure for inaccuracy...
*/
memset(&tmzero, 0, sizeof(tmzero));
/*
* Get the current time, mapped to a tm structure...
*
* NOTE: The NULL argument is used to get the current time.
*/
utc_localtime(&tmtime, /* Out: Current local time in tm struct */
(long *)0, /* Out: Nanoseconds of time */
(struct tm *)0, /* Out: Current inacc in tm struct */
(long *)0, /* Out: Nanoseconds of inaccuracy */
(utc_t *)0); /* In: Current timestamp */
/*
* Alter the tm structure to correspond to 13:00 local time ...
*/
tmtime.tm_hour = 13;
tmtime.tm_min = 0;
tmtime.tm_sec = 0;
/*
* Convert to a binary timestamp...
*/
utc_mklocaltime(&testtime, /* Out: Binary timestamp of 13:00 */
&tmtime, /* In: 13:00 in tm struct */
0, /* In: Nanoseconds of time */
&tmzero, /* In: Zero inaccuracy in tm struct */
0); /* In: Nanoseconds of inaccuracy */
/*
* Compare to the current time. Note the use of the NULL argument...
*/
utc_cmpmidtime(&relation, /* Out: Comparison relation */
(utc_t *)0, /* In: Current timestamp */
&testtime); /* In: 13:00 local timestamp */
/*
* If the time is not later - wait, print a message, etc.
*/
if (relation != utc_greaterThan) {
/* It is not later than 13:00 local time. Note that
* this depends on the setting of the user's environment.
*/
}
Related Information
Routines:
utc_cmpintervaltime
ΓòÉΓòÉΓòÉ 7.4.14. utc_gettime ΓòÉΓòÉΓòÉ
Purpose
Returns the current system time and inaccuracy as a binary timestamp.
Format
#include <dce\utc.h>
int utc_gettime(
utc_t *utc);
Parameters
Output
utc System time as a binary timestamp.
Usage
The utc_gettime routine returns the current system time and
inaccuracy in a binary timestamp. The routine takes the TDF from the
operating system's kernel; the TDF is specified in a system dependent
manner.
Return Codes
0 Indicates that the routine ran successfully.
-1 Generic error that indicates the time service cannot be accessed.
Examples
See the example in utc_binreltime.
ΓòÉΓòÉΓòÉ 7.4.15. utc_getusertime ΓòÉΓòÉΓòÉ
Purpose
Returns the time and process-specific TDF, rather than the
system-specific TDF.
Format
#include <dce\utc.h>
int utc_getusertime(
utc_t *utc);
Parameters
Output
utc System time as a binary timestamp.
Usage
The utc_getusertime routine returns the system time and inaccuracy in
a binary timestamp. The routine takes the TDF from the user's
environment, which determines the time zone rule (details are system
dependent). For example, on OS/2 systems, the user selects a time
zone by specifying the TZ environment variable. (See utc_localtime
for additional information.)
If the user's environment does not specify a TDF, the system's TDF is
used. The system's time zone rule is applied (details of the rule
are system dependent). For example, on OS/2 systems, the rule in the
localtime file is used.
Return Codes
0 Indicates that the routine ran successfully.
-1 Generic error that indicates the time service cannot be accessed.
Examples
See the example in utc_boundtime.
Related Information
Routines:
utc_gettime
ΓòÉΓòÉΓòÉ 7.4.16. utc_gmtime ΓòÉΓòÉΓòÉ
Purpose
Converts a binary timestamp to a tm structure that expresses
Greenwich Mean Time (GMT) or the equivalent UTC.
Format
#include <dce\utc.h>
int utc_gmtime(
struct tm *timetm,
long *tns,
struct tm *inacctm,
long *ins,
utc_t *utc);
Parameters
Input
utc Binary timestamp to be converted to tm structure
components. Use NULL if you want this routine to use
the current time for this parameter.
Output
timetm Time component of the binary timestamp.
tns Nanoseconds since Time component of the binary
timestamp.
inacctm Seconds of the inaccuracy component of the binary
timestamp. If the inaccuracy is finite, tm_mday returns
a value of -1 and tm_mon and tm_year return values of
zero. The field tm_yday contains the inaccuracy in
days. If the inaccuracy is unspecified, all tm
structure fields return values of -1.
ins Nanoseconds of inaccuracy component of the binary
timestamp. If the inaccuracy is unspecified, ins
returns a value of -1.
Usage
The utc_gmtime (GMT) routine converts a binary timestamp to a tm
structure that expresses GMT (or the equivalent UTC). Additional
returns include nanoseconds since Time and nanoseconds of inaccuracy.
Return Codes
0 Indicates that the routine ran successfully.
-1 Indicates an invalid time argument or invalid results.
Examples
See the example in utc_cmpintervaltime.
Related Information
Routines:
utc_anytime
utc_gmtzone
utc_localtime
utc_mkgmtime
ΓòÉΓòÉΓòÉ 7.4.17. utc_gmtzone ΓòÉΓòÉΓòÉ
Purpose
Gets the time zone label for GMT.
Format
#include <dce\utc.h>
int utc_gmtzone(
char *tzname,
size_t tzlen,
long *tdf,
int *isdst,
utc_t *utc);
Parameters
Input
tzlen Length of buffer tzname.
utc Binary timestamp. This parameter is ignored.
Output
tzname Character string long enough to hold the time zone
label.
tdf Long word with differential in seconds east of GMT. A
value of zero is always returned.
isdst Integer with a value of zero, indicating that Daylight
Savings Time is not in effect. A value of zero is
always returned.
Usage
The utc_gmtzone routine gets the time zone label and zero offset from
GMT. Outputs are always tdf = 0 and tzname = GMT. This routine exists
for symmetry with the utc_anyzone and the utc_localzone routines.
Use NULL if you want this routine to use the current time for this
parameter.
Notes
All of the output parameters are optional. No value is returned and
no error occurs if the tzname pointer is NULL.
Return Codes
0 Indicates that the routine ran successfully (always returned).
Examples
The following example prints out the current time in both local time
and GMT time.
utc_t now;
struct tm tmlocal, tmgmt;
long tzoffset;
int tzdaylight;
char tzlocal[80], tzgmt[80];
/*
* Get the current time once, so both conversions use the same
* time...
*/
utc_gettime(&now);
/*
* Convert to local time, using the process TZ environment
* variable...
*/
utc_localtime(&tmlocal, /* Out: Local time tm structure */
(long *)0, /* Out: Nanosec of time */
(struct tm *)0, /* Out: Inaccuracy tm structure */
(long *)0, /* Out: Nanosec of inaccuracy */
(int *)0, /* Out: TDF of local time */
&now); /* In: Current timestamp (ignore) */
/*
* Get the local time zone name, offset from GMT, and current
* daylight savings flag...
*/
utc_localzone(tzlocal, /* Out: Local time zone name */
80, /* In: Length of loc time zone name */
&tzoffset, /* Out: Loc time zone offset in secs */
&tzdaylight, /* Out: Local time zone daylight flag */
&now); /* In: Current binary timestamp */
/*
* Convert to GMT...
*/
utc_gmtime(&tmgmt, /* Out: GMT tm structure */
(long *)0, /* Out: Nanoseconds of time */
(struct tm *)0, /* Out: Inaccuracy tm structure */
(long *)0, /* Out: Nanoseconds of inaccuracy */
&now); /* In: Current binary timestamp */
/*
* Get the GMT time zone name...
*/
utc_gmtzone(tzgmt, /* Out: GMT time zone name */
80, /* In: Size of GMT time zone name */
(long *)0, /* Out: GMT time zone offset in secs */
(int *)0, /* Out: GMT time zone daylight flag */
&now); /* In: Current binary timestamp */
/* (ignore) */
/*
* Print out times and time zone information in the following
* format:
*
* 12:00:37 (EDT) = 16:00:37 (GMT)
* EDT is -240 minutes ahead of Greenwich Mean Time.
* Daylight savings time is in effect.
*/
printf("%d:%02d:%02d (%s) = %d:%02d:%02d (%s)\n",
tmlocal.tm_hour, tmlocal.tm_min, tmlocal.tm_sec, tzlocal,
tmgmt.tm_hour, tmgmt.tm_min, tmgmt.tm_sec, tzgmt);
printf("%s is %d minutes ahead of Greenwich Mean Time\n", tzlocal, tzoffset/60);
if (tzdaylight != 0)
printf("Daylight savings time is in effect\n");
Related Information
Routines:
utc_anyzone
utc_gmtime
utc_localzone
ΓòÉΓòÉΓòÉ 7.4.18. utc_localtime ΓòÉΓòÉΓòÉ
Purpose
Converts a binary timestamp to a tm structure that expresses local
time.
Format
#include <dce\utc.h>
int utc_localtime(
struct tm *timetm,
long *tns,
struct tm *inacctm,
long *ins,
utc_t *utc);
Parameters
Input
utc Binary timestamp. Use NULL if you want this routine to
use the current time for this parameter.
Output
timetm Time component of the binary timestamp, expressing
local time.
tns Nanoseconds since Time component of the binary
timestamp.
inacctm Seconds of the inaccuracy component of the binary
timestamp. If the inaccuracy is finite, tm_mday returns
a value of -1 and tm_mon and tm_year return values of
zero. The field tm_yday contains the inaccuracy in
days. If the inaccuracy is unspecified, all tm
structure fields return values of -1.
ins Nanoseconds of inaccuracy component of the binary
timestamp. If the inaccuracy is unspecified, ins
returns a value of -1.
Usage
The utc_localtime routine converts a binary timestamp to a tm
structure that expresses local time.
The user's environment determines the time zone rule (details are
system dependent). For example, on OS/2 systems, the user selects a
time zone by specifying the TZ environment variable.
If the user's environment does not specify a time zone rule, the
system's rule is used (details of the rule are system dependent). For
example, on OS/2 systems, the rule in the localtime file is used.
Additional returns include nanoseconds since Time and nanoseconds of
inaccuracy.
Return Codes
0 Indicates that the routine ran successfully.
-1 Indicates an invalid time argument or invalid results.
Examples
See the example in utc_gmtzone.
Related Information
Routines:
utc_anytime
utc_gmtime
utc_localzone
utc_mklocaltime
ΓòÉΓòÉΓòÉ 7.4.19. utc_localzone ΓòÉΓòÉΓòÉ
Purpose
Gets the local time zone label and offset from GMT, given utc.
Format
#include <dce\utc.h>
int utc_localzone(
char *tzname,
size_t tzlen,
long *tdf,
int *isdst,
utc_t *utc);
Parameters
Input
tzlen Length of the tzname buffer.
utc Binary timestamp. Use NULL if you want this routine to
use the current time for this parameter.
Output
tzname Character string long enough to hold the time zone
label.
tdf Long word with differential in seconds east of GMT.
isdst Integer with a value of zero if Standard Time is in
effect or a value of 1 if Daylight Savings Time is in
effect.
Usage
The utc_localzone routine gets the local time zone label and offset
from GMT, given utc.
The user's environment determines the time zone rule (details are
system dependent). For example, on OS/2 systems, the user selects a
time zone by specifying the TZ environment variable.
If the user's environment does not specify a time zone rule, the
system's rule is used (details of the rule are system dependent). For
example, on OS/2 systems, the rule in the localtime file is used.
Notes
All of the Output parameters are optional. No value is returned and
no error occurs if the pointer is NULL.
Return Codes
0 Indicates that the routine ran successfully.
-1 Indicates an invalid time argument or an insufficient buffer.
Examples
See the example in utc_gmtzone.
Related Information
Routines:
utc_anyzone
utc_gmtzone
utc_localtime
ΓòÉΓòÉΓòÉ 7.4.20. utc_mkanytime ΓòÉΓòÉΓòÉ
Purpose
Converts a tm structure and TDF (expressing the time in an arbitrary
time zone) to a binary timestamp.
Format
#include <dce\utc.h>
int utc_mkanytime(
utc_t *utc,
struct tm *timetm,
long tns,
struct tm *inacctm,
long ins,
long tdf);
Parameters
Input
timetm A tm structure that expresses the local time; tm_wday
and tm_yday are ignored on input; the value of tm_isdt
should be -1.
tns Nanoseconds since the Time component.
inacctm A tm structure that expresses days, hours, minutes, and
seconds of inaccuracy. If a NULL pointer is passed or
tm_yday is negative, the inaccuracy is considered to be
unspecified; tm_mday, tm_mon, tm_wday, and tm_isdst are
ignored on input.
ins Nanoseconds of inaccuracy component.
tdf Time Differential Factor to use in conversion.
Output
utc Resulting binary timestamp.
Usage
The utc_mkanytime routine converts a tm structure and TDF (expressing
the time in an arbitrary time zone) to a binary timestamp. Required
inputs include nanoseconds since Time and nanoseconds of inaccuracy.
Return Codes
0 Indicates that the routine ran successfully.
-1 Indicates an invalid time argument or invalid results.
Examples
The following example converts a string ISO format time in an
arbitrary time zone to a binary timestamp. This may be part of an
input timestamp routine, although a real implementation will include
range checking.
utc_t utc;
struct tm tmtime, tminacc;
float tsec, isec;
double tmp;
long tnsec, insec;
int i, offset, tzhour, tzmin, year, mon;
char *string;
/* Try to convert the string... */
if(sscanf(string, "%d-%d-%d-%d:%d:%e+%d:%dI%e",
&year, &mon, &tmtime.tm_mday, &tmtime.tm_hour,
&tmtime.tm_min, &tsec, &tzhour, &tzmin, &isec) != 9) {
/* Try again with a negative TDF... */
if (sscanf(string, "%d-%d-%d-%d:%d:%e-%d:%dI%e",
&year, &mon, &tmtime.tm_mday, &tmtime.tm_hour,
&tmtime.tm_min, &tsec, &tzhour, &tzmin, &isec) != 9) {
/* ERROR */
exit(1);
}
/* TDF is negative */
tzhour = -tzhour;
tzmin = -tzmin;
}
/* Fill in the fields... */
tmtime.tm_year = year - 1900;
tmtime.tm_mon = --mon;
tmtime.tm_sec = tsec;
tnsec = (modf(tsec, &tmp)*1.0E9);
offset = tzhour*3600 + tzmin*60;
tminacc.tm_sec = isec;
insec = (modf(isec, &tmp)*1.0E9);
/* Convert to a binary timestamp... */
utc_mkanytime(&utc, /* Out: Resultant binary timestamp */
&tmtime, /* In: tm struct that represents input */
tnsec, /* In: Nanoseconds from input */
&tminacc, /* In: tm struct that represents inacc */
insec, /* In: Nanoseconds from input */
offset); /* In: TDF from input */
Related Information
Routines:
utc_anytime
utc_anyzone
ΓòÉΓòÉΓòÉ 7.4.21. utc_mkascreltime ΓòÉΓòÉΓòÉ
Purpose
Converts a NULL-terminated character string that represents a
relative timestamp to a binary timestamp.
Format
#include <dce\utc.h>
int utc_mkascreltime(
utc_t *utc,
char *string);
Parameters
Input
string A NULL-terminated string that expresses a relative
timestamp in its ISO format.
Output
utc Resulting binary timestamp.
Usage
The utc_mkascreltime routine converts a NULL-terminated string, which
represents a relative timestamp, to a binary timestamp.
Notes
The text string must be NULL-terminated.
Return Codes
0 Indicates that the routine ran successfully.
-1 Indicates an invalid time parameter or invalid results.
Examples
The following example converts an ASCII relative time string to its
binary equivalent.
utc_t utc;
char str[UTC_MAX_STR_LEN];
/*
* Relative time of -333 days, 12 hours, 1 minute, 37.223 seconds
* Inaccuracy of 50.22 seconds in the format: -333-12:01:37.223I50.22
*/
(void)strcpy((void *)str,
"-333-12:01:37.223I50.22");
utc_mkascreltime(&utc, /* Out: Binary utc */
str); /* In: String */
Related Information
Routines:
utc_ascreltime
ΓòÉΓòÉΓòÉ 7.4.22. utc_mkasctime ΓòÉΓòÉΓòÉ
Purpose
Converts a NULL-terminated character string that represents an
absolute timestamp to a binary timestamp.
Format
#include <dce\utc.h>
int utc_mkasctime(
utc_t *utc,
char *string);
Parameters
Input
string A NULL-terminated string that expresses an absolute
time.
Output
utc Resulting binary timestamp.
Usage
The utc_mkasctime routine converts a NULL-terminated string that
represents an absolute time to a binary timestamp.
Notes
The text string must be NULL-terminated.
Return Codes
0 Indicates that the routine ran successfully.
-1 Indicates an invalid time parameter or invalid results.
Examples
The following example converts an ASCII time string to its binary
equivalent.
utc_t utc;
char str[UTC_MAX_STR_LEN];
/*
* July 4, 1776, 12:01:37.223 local time
* TDF of -5:00 hours
* Inaccuracy of 3600.32 seconds
*/
(void)strcpy((void *)str,
"1776-07-04-12:01:37.223-5:00I3600.32");
utc_mkasctime(&utc, /* Out: Binary utc */
str); /* In: String */
Related Information
Routines:
utc_ascanytime
utc_ascgmtime
utc_asclocaltime
ΓòÉΓòÉΓòÉ 7.4.23. utc_mkbinreltime ΓòÉΓòÉΓòÉ
Purpose
Converts a timespec structure expressing a relative time to a binary
timestamp.
Format
#include <dce\utc.h>
int utc_mkbinreltime(
utc_t *utc,
reltimespec_t *timesp,
timespec_t *inaccsp);
Parameters
Input
timesp A reltimespec structure that expresses a relative time.
inaccsp A timespec structure that expresses inaccuracy. If a
NULL pointer is passed or if tv_sec is set to a value
of -1, the inaccuracy is considered to be unspecified.
Output
utc Resulting relative binary timestamp.
Usage
The utc_mkbinreltime routine converts a timespec structure that
expresses relative time to a binary timestamp.
Return Codes
0 Indicates that the routine ran successfully.
-1 Indicates an invalid time argument or invalid results.
Examples
See the example in utc_addtime.
Related Information
Routines:
utc_binreltime
utc_mkbintime
ΓòÉΓòÉΓòÉ 7.4.24. utc_mkbintime ΓòÉΓòÉΓòÉ
Purpose
Converts a timespec structure to a binary timestamp.
Format
#include <dce\utc.h>
int utc_mkbintime(
utc_t *utc,
timespec_t *timesp,
timespec_t *inaccsp,
long tdf);
Parameters
Input
timesp A timespec structure that expresses time since
1970-01-01:00:00:00.0+0:00I0.
inaccsp A timespec structure that expresses inaccuracy. If a
NULL pointer is passed or if tv_sec is set to a value
of -1, the inaccuracy is considered to be unspecified.
tdf TDF component of the binary timestamp.
Output
utc Resulting binary timestamp.
Usage
The utc_mkbintime routine converts a timespec structure time to a
binary timestamp. The TDF input is used as the TDF of the binary
timestamp.
Return Codes
0 Indicates that the routine ran successfully.
-1 Indicates an invalid time argument or invalid results.
Examples
The following example obtains the current time from time, converts it
to a binary timestamp with an inaccuracy of 5.2 seconds, and
specifies GMT.
timespec_t ttime, tinacc;
utc_t utc;
/*
* Obtain the current time (without the inaccuracy)...
*/
ttime.tv_sec = time((time_t *)0);
ttime.tv_nsec = 0;
/*
* Specify the inaccuracy...
*/
tinacc.tv_sec = 5;
tinacc.tv_nsec = 200000000;
/*
* Convert to a binary timestamp...
*/
utc_mkbintime(&utc, /* Out: Binary timestamp */
&ttime, /* In: Current time in timespec */
&tinacc, /* In: 5.2 seconds in timespec */
0); /* In: TDF of GMT */
Related Information
Routines:
utc_bintime
utc_mkbinreltime
ΓòÉΓòÉΓòÉ 7.4.25. utc_mkgmtime ΓòÉΓòÉΓòÉ
Purpose
Converts a tm structure that expresses GMT or UTC to a binary
timestamp.
Format
#include <dce\utc.h>
int utc_mkgmtime(
utc_t *utc,
struct tm *timetm,
long tns,
struct tm *inacctm,
long ins);
Parameters
Input
timetm A tm structure that expresses GMT. On input, tm_wday
and tm_yday are ignored; the value of tm_isdt should be
-1.
tns Nanoseconds since the Time component.
inacctm A tm structure that expresses days, hours, minutes, and
seconds of inaccuracy. If a NULL pointer is passed, or
if tm_yday is negative, the inaccuracy is considered to
be unspecified. On input, tm_mday, tm_mon, tm_wday, and
tm_isdst are ignored.
ins Nanoseconds of inaccuracy component.
Output
utc Resulting binary timestamp.
Usage
The utc_mkgmtime routine converts a tm structure that expresses GMT
or UTC to a binary timestamp. Additional inputs include nanoseconds
since the last second of Time and nanoseconds of inaccuracy.
Return Codes
0 Indicates that the routine ran successfully.
-1 Indicates an invalid time argument or invalid results.
Examples
See the example in utc_cmpintervaltime.
Related Information
Routines:
utc_gmtime
ΓòÉΓòÉΓòÉ 7.4.26. utc_mklocaltime ΓòÉΓòÉΓòÉ
Purpose
Converts a tm structure that expresses local time to a binary
timestamp.
Format
#include <dce\utc.h>
int utc_mklocaltime(
utc_t *utc,
struct tm *timetm,
long tns,
struct tm *inacctm,
long ins);
Parameters
Input
timetm A tm structure that expresses the local time. On
input, tm_wday and tm_yday are ignored; the value of
tm_isdt should be -1.
tns Nanoseconds since Time component.
inacctm A tm structure that expresses days, hours, minutes, and
seconds of inaccuracy. If a NULL pointer is passed, or
if tm_yday is negative, the inaccuracy is considered to
be unspecified. On input, tm_mday, tm_mon, tm_wday,
and tm_isdst are ignored.
ins Nanoseconds of inaccuracy component.
Output
utc Resulting binary timestamp.
Usage
The utc_mklocaltime routine converts a tm structure that expresses
local time to a binary timestamp.
The user's environment determines the time zone rule (details are
system dependent). For example, on OS/2 systems, the user selects a
time zone by specifying the TZ environment variable. (See
utc_localtime for additional information.)
If the user's environment does not specify a time zone rule, the
system's rule is used (details of the rule are system dependent). For
example, on OS/2 systems, the rule in the localtime file is used.
Additional inputs include nanoseconds since the last second of Time
and nanoseconds of inaccuracy.
Return Codes
0 Indicates that the routine ran successfully.
-1 Indicates an invalid time argument or invalid results.
Examples
See the example in utc_cmpmidtime.
Related Information
Routines:
utc_localtime
ΓòÉΓòÉΓòÉ 7.4.27. utc_mkreltime ΓòÉΓòÉΓòÉ
Purpose
Converts a tm structure that expresses relative time to a relative
binary timestamp.
Format
#include <dce\utc.h>
int utc_mkreltime(
utc_t *utc,
struct tm *timetm,
long tns,
struct tm *inacctm,
long ins);
Parameters
Input
timetm A tm structure that expresses a relative time. On
input, tm_wday and tm_yday are ignored. The value of
tm_isdt should be -1.
tns Nanoseconds since Time component.
inacctm A tm structure that expresses seconds of inaccuracy. If
a NULL pointer is passed, or if tm_yday is negative,
the inaccuracy is considered to be unspecified. On
input, tm_mday, tm_mon, tm_year, tm_wday, tm_isdst, and
tm_zone are ignored.
ins Nanoseconds of inaccuracy component.
Output
utc Resulting relative binary timestamp.
Usage
The utc_mkreltime routine converts a tm structure that expresses
relative time to a relative binary timestamp. Additional inputs
include nanoseconds since the last second of Time and nanoseconds of
inaccuracy.
Return Codes
0 Indicates that the routine ran successfully.
-1 Indicates an invalid time argument or invalid results.
Examples
The following example converts the relative time
125-03:12:30.1I120.25 to a relative binary timestamp.
utc_t utc;
struct tm tmtime, tminacc;
long tnsec, insec;
/*
* Fill in the fields...
*/
memset ((void *)&tmtime, 0, sizeof(tmtime));
tmtime.tm_mday = 125;
tmtime.tm_hour = 3;
tmtime.tm_min = 12;
tmtime.tm_sec = 30;
tnsec = 100000000; /* .1 * 1.0E9 */
memset((void *)&tminacc, 0, sizeof(tminacc));
tminacc.tm_sec = 120;
tnsec = 250000000; /* .25 * 1.0E9 */
/*
* Convert to a relative binary timestamp...
*/
utc_mkreltime(&utc, /* Out: Resultant binary timestamp */
&tmtime, /* In: tm struct that represents input */
tnsec, /* In: Nanoseconds from input */
&tminacc, /* In: tm struct that represents inacc */
insec); /* In: Nanoseconds from input */
Related Information
Routines:
utc_reltime
ΓòÉΓòÉΓòÉ 7.4.28. utc_mulftime ΓòÉΓòÉΓòÉ
Purpose
Multiplies a relative binary timestamp by a floating-point value.
Format
#include <dce\utc.h>
int utc_mulftime(
utc_t *result,
utc_t *utc1,
double factor);
Parameters
Input
utc1 Relative binary timestamp. Use NULL if you want this
routine to use the current time for this parameter.
factor Real scale factor (double-precision floating-point
value).
Output
result Resulting relative binary timestamp.
Usage
The utc_mulftime routine multiplies a relative binary timestamp by a
floating-point value. Either or both may be negative; the resulting
relative binary timestamp has the appropriate sign. The unsigned
inaccuracy in the relative binary timestamp is also multiplied by the
absolute value of the floating-point value.
Return Codes
0 Indicates that the routine ran successfully.
-1 Indicates an invalid time argument or invalid results.
Examples
The following example scales a relative time by a floating-point
factor and prints the result.
utc_t relutc, scaledutc;
struct tm sacledreltm;
char timstr[UTC_MAX_STR_LEN];
/*
* Assume relutc contains the time to scale.
*/
utc_multime(&scaledutc, /* Out: Scaled rel time */
&relutc, /* In: Rel time to scale */
17.65); /* In: Scale factor */
utc_ascreltime(timstr, /* Out: ASCII rel time */
UTC_MAX_STR_LEN, /* In: Input buffer length */
&scaledutc); /* In: Rel time to convert */
printf("%s\n",timstr);
/*
* Convert it to a tm structure and print it.
*/
utc_reltime(&scaledreltm, /* Out: Scaled rel tm */
(long *)0, /* Out: Scaled rel nano-sec */
(struct tm *)0, /* Out: Scaled rel inacc tm */
(long *)0, /* Out: Scd rel inacc nanos */
&scaledutc); /* In: Rel time to convert */
printf("Approximately %d days, %d hours and %d minutes\n",
scaledreltm.tm_yday, scaledreltm.tm_hour, scaledreltm.tm_min);
Related Information
Routines:
utc_multime
ΓòÉΓòÉΓòÉ 7.4.29. utc_multime ΓòÉΓòÉΓòÉ
Purpose
Multiplies a relative binary timestamp by an integer factor.
Format
#include <dce\utc.h>
int utc_multime(
utc_t *result,
utc_t *utc1,
long factor);
Parameters
Input
utc1 Relative binary timestamp.
factor Integer scale factor.
Output
result Resulting relative binary timestamp.
Usage
The utc_multime routine multiplies a relative binary timestamp by an
integer. Either or both may be negative; the resulting binary
timestamp has the appropriate sign. The unsigned inaccuracy in the
binary timestamp is also multiplied by the absolute value of the
integer.
Return Codes
0 Indicates that the routine ran successfully.
-1 Indicates an invalid time argument or invalid results.
Examples
The following example scales a relative time by an integral value and
prints the result.
utc_t relutc, scaledutc;
char timstr[UTC_MAX_STR_LEN];
/*
* Assume relutc contains the time to scale. Scale it by a factor
* of 17...
*/
utc_multime(&scaledutc, /* Out: Scaled rel time */
&relutc, /* In: Rel time to scale */
17L); /* In: Scale factor */
utc_ascreltime(timstr, /* Out: ASCII rel time */
UTC_MAX_STR_LEN, /* In: Input buffer length */
&scaledutc); /* In: Rel time to convert */
printf("Scaled result is %s", timstr);
Related Information
Routines:
utc_mulftime
ΓòÉΓòÉΓòÉ 7.4.30. utc_pointtime ΓòÉΓòÉΓòÉ
Purpose
Converts a binary timestamp to three binary timestamps that represent
the earliest, most likely, and latest time.
Format
#include <dce\utc.h>
int utc_pointtime(
utc_t *utclp,
utc_t *utcmp,
utc_t *utchp,
utc_t *utc);
Parameters
Input
utc Binary timestamp or relative binary timestamp. Use NULL
if you want this routine to use the current time for
this parameter.
Output
utclp Lowest (earliest) possible absolute time or shortest
possible relative time that the input timestamp can
represent.
utcmp Midpoint of the input binary timestamp.
utchp Highest (latest) possible absolute time or the longest
possible relative time that the input timestamp can
represent.
Usage
The utc_pointtime routine converts a binary timestamp to three binary
timestamps that represent the earliest, latest, and most likely
(midpoint) times. If the input is a relative binary time, the
outputs represent relative binary times.
Notes
All outputs have zero inaccuracy. An error is returned if the input
binary timestamp has an unspecified inaccuracy.
Return Codes
0 Indicates that the routine ran successfully.
-1 Indicates an invalid time argument.
Examples
See the example in utc_addtime.
Related Information
Routines:
utc_boundtime
utc_spantime
ΓòÉΓòÉΓòÉ 7.4.31. utc_reltime ΓòÉΓòÉΓòÉ
Purpose
Converts a relative binary timestamp to a tm structure.
Format
#include <dce\utc.h>
int utc_reltime(
struct tm *timetm,
long *tns,
struct tm *inacctm,
long *ins,
utc_t *utc);
Parameters
Input
utc Relative binary timestamp.
Output
timetm Relative time component of the relative binary
timestamp. The field tm_mday returns a value of -1 and
the fields tm_year and tm_mon return values of zero.
The field tm_yday contains the number of days of
relative time.
tns Nanoseconds since Time component of the relative binary
timestamp.
inacctm Seconds of inaccuracy component of the relative binary
timestamp. If the inaccuracy is finite, tm_mday returns
a value of -1 and tm_mon and tm_year return values of
zero. The field tm_yday contains the inaccuracy in
days. If the inaccuracy is unspecified, all tm
structure fields return values of -1.
ins Nanoseconds of inaccuracy component of the relative
binary timestamp.
Usage
The utc_reltime routine converts a relative binary timestamp to a tm
structure. Additional returns include nanoseconds since Time and
nanoseconds of inaccuracy.
Return Codes
0 Indicates that the routine ran successfully.
-1 Indicates an invalid time argument or invalid results.
Examples
See the example in utc_mulftime.
Related Information
Routines:
utc_mkreltime
ΓòÉΓòÉΓòÉ 7.4.32. utc_spantime ΓòÉΓòÉΓòÉ
Purpose
Returns a single UTC time interval whose inaccuracy spans the two
input binary timestamps, given two (possibly unordered) binary
timestamps.
Format
#include <dce\utc.h>
int utc_spantime(
utc_t *result,
utc_t *utc1,
utc_t *utc2);
Parameters
Input
utc1 Binary timestamp. Use NULL if you want this routine to
use the current time for this parameter.
utc2 Binary timestamp. Use NULL if you want this routine to
use the current time for this parameter.
Output
result Spanning timestamp.
Usage
Given two binary timestamps, the utc_spantime routine returns a
single UTC time interval whose inaccuracy spans the two input
timestamps (that is, the interval resulting from the earliest
possible time of either timestamp to the latest possible time of
either timestamp).
Notes
The tdf in the output UTC value is copied from the utc2 input. If
either input binary timestamp has an unspecified inaccuracy, an error
is returned.
Return Codes
0 Indicates that the routine ran successfully.
-1 Indicates an invalid time argument.
Examples
The following example computes the earliest and latest times for an
array of 10 timestamps.
utc_t time_array[10], testtime, earliest, latest;
int i;
/*
* Set the running timestamp to the first entry...
*/
testtime = time_array[0];
for (i=1; i<10; i++) {
/*
* Compute the minimum and the maximum against the next
* element...
*/
utc_spantime(&testtime, /* Out: Resultant interval */
&testtime, /* In: Largest previous interval */
16:16:45_array[i]); /* In: Element under test */
}
/*
* Compute the earliest and latest possible times...
*/
utc_pointtime(&earliest, /* Out: Earliest poss time in array */
(utc_t *)0, /* Out: Midpoint */
&latest, /* Out: Latest poss time in array */
&testtime); /* In: Spanning interval */
Related Information
Routines:
utc_boundtime
utc_gettime
utc_pointtime
ΓòÉΓòÉΓòÉ 7.4.33. utc_subtime ΓòÉΓòÉΓòÉ
Purpose
Computes the difference between two binary timestamps.
Format
#include <dce\utc.h>
int utc_subtime(
utc_t *result,
utc_t *utc1,
utc_t *utc2);
Parameters
Input
utc1 Binary timestamp or relative binary timestamp. Use NULL
if you want this routine to use the current time for
this parameter.
utc2 Binary timestamp or relative binary timestamp. Use NULL
if you want this routine to use the current time for
this parameter.
Output
result Resulting binary timestamp or relative binary
timestamp, depending upon the operation performed:
o absolute time - absolute time = relative time
o relative time - relative time = relative time
o absolute time - relative time = absolute time
o relative time - absolute time is undefined. See
the note below.
Usage
The utc_subtime routine subtracts one binary timestamp from another.
The two binary timestamps express either an absolute time and a
relative time, two relative times, or two absolute times. The
resulting timestamp is utc1 minus utc2. The inaccuracies of the two
input timestamps are combined and included in the output timestamp.
The TDF in the first timestamp is copied to the output.
Notes
Although no error is returned, the combination relative time -
absolute time should not be used.
Return Codes
0 Indicates that the routine ran successfully.
-1 Indicates an invalid time argument or invalid results.
Examples
See the example in utc_binreltime.
Related Information
Routines:
utc_addtime
ΓòÉΓòÉΓòÉ 8. DCE Security Services API ΓòÉΓòÉΓòÉ
The Distributed Computing Environment (DCE) Security Services Application
Program Interface (API) allows developers to create network services with
access to the authentication and authorization capabilities of DCE Security
services and facilities.
The calling of a network service generally consists of a client process
requesting some action from a server process. The client can itself be a
server, or a user, and the server can also be a client of other servers. Before
the targeted server runs the specified action, it must be sure of the client's
identity, and it must know whether the client is authorized to request the
service.
The routines in this API are the same routines used by various user-level tools
provided as part of the DCE. For example, the screatdb tool is written with
sec_rgy routines, acl_edit is written with sec_acl routines, and the dcelogin
program, with which a user logs into a DCE system, is written using sec_login
routines. Most sites will find the user-level tools adequate for their needs
and must use the Security API only to customize or replace the function of
these tools.
Though most of the routines in the Security API represent remote procedure
calls, code has been provided on the client side to handle much of the overhead
involved with making remote calls. These stubs handle binding to the requested
security server site, the marshalling of data into whatever form is needed for
transmission, and other bookkeeping involved with these remote calls. An
application programmer can use the Security Service interfaces as if they were
composed of simple C functions.
The Security Services API consists of ten sets of remote procedure calls (RPCs)
used to communicate with various security-related services and facilities.
They include:
DCE Access Control List API Implements an access control list (ACL) protocol
for the authorization of a principal to network services.
DCE Audit API Allows applications to perform auditing and to analyze audit
trails.
DCE Extended Privilege Attribute API Allows clients and servers to run secure
operations using one or more intermediate servers.
DCE Extended Registry Attribute API Provides facilities for extending the
Registry database by creating, maintaining, and viewing attribute
types and instances, and providing information to and receiving
it from outside attribute servers.
DCE Generic Security Service API Provides security services to applications
using peer-to-peer communications.
DCE Login API Validates a principal's network identity.
DCE Key Management API Provides facilities for the maintenance of account keys
for daemon principals.
DCE ID Mapping API Maps file system names to Universal Unique IDs (UUIDs) and
vice versa.
DCE Password Management API Provides the tools necessary to develop customized
password management servers, and to call them from client
password change programs.
Registry API Maintains the network registry of principal identities.
ΓòÉΓòÉΓòÉ 8.1. DCE Access Control List API ΓòÉΓòÉΓòÉ
The ACL facility uses the data types and constant values that are detailed in
the following sections:
Data Types
Constants
The two parts of the ACL API are:
Client-Side API (sec_acl_xxx) Enables clients to browse or edit DCE ACLs.
Rdacl Routines (rdacl_xxx) Enables servers that manage access control (such
as sec_acl_mgr-based ACL managers) to
communicate with sec_acl-based clients.
ΓòÉΓòÉΓòÉ 8.1.1. Client-Side API ΓòÉΓòÉΓòÉ
The client-side API is a local interface consisting of a set of routines that
are prefixed sec_acl. An application that needs to replace dcecp with a DCE ACL
editor or browser of its own calls this interface.
Any operation performed on an ACL uses an ACL handle of type handle_t to
identify the target of the operation. The handle is bound to the server that
manages the object protected by the ACL, not to the ACL itself. Because an
object can be protected by more than one ACL manager type, the ACL itself can
only be uniquely identified by the ACL handle in combination with the manager
type that manages it. ACL editing routines must also specify the ACL type to be
read or otherwise manipulated (the object, default container, or default object
ACL types).
The sec_acl_xxx routines are listed alphabetically as follows:
sec_acl_bind Gets an ACL handle. This handle is opaque
to the calling program.
sec_acl_bind_to_addr Binds to a network address rather than a
cell namespace entry. Use this routine if
a Cell Directory Service is absent.
sec_acl_calc_mask Calculates a new sec_acl_e_type_mask_obj
entry type.
sec_acl_get_access Lists the access (permission set) that the
caller has for an object.
sec_acl_get_error_info Returns the error code last stored in the
handle.
sec_acl_get_manager_types Returns a list of UUIDs of the manager
types protecting an object.
sec_acl_get_mgr_types_semantics Returns a list of UUIDs corresponding to
the manager types and the POSIX semantics
supported by each manager type. The output
of this routine is used by the
sec_acl_calc_mask routine.
sec_acl_get_printstring Receives a print string for displaying the
permissions of the ACL in a human-readable
form.
sec_acl_lookup Returns a copy of an object's ACL.
sec_acl_release Frees the memory occupied by an ACL, and
returns it to the pool. This is a local
operation only.
sec_acl_release_handle Releases an ACL handle.
sec_acl_replace Replaces an ACL. To change an ACL, an
editor must read the entire ACL into a
sec_acl_t structure, modify it, and
replace it entirely using this routine.
sec_acl_test_access Allows a server to test whether a client
has access to an object to perform the
requested operation.
sec_acl_test_access_on_behalf Allows an application to check an ACL on
behalf of a principal other than the one
represented by the calling process.
Within the server, the sec_acl_mgr_xxx routines are a local interface into the
ACL routines used by the server itself and by the rdacl_xxx routines as
necessary.
Following is a summary of ACL manager routines:
sec_acl_mgr_configure Creates an ACL database and
returns a handle to it.
sec_acl_mgr_get_access Returns a principal's
permissions to an object.
sec_acl_mgr_get_manager_types Returns a list of manager types
protecting the object.
sec_acl_mgr_get_types_semantics Returns the types of ACLs and
the POSIX semantics that are
protecting an object.
sec_acl_mgr_get_printstring Returns human-readable
representations of permissions.
sec_acl_mgr_is_authorized Takes a principal's PAC and the
requested permission set and
returns TRUE if the permission
set is granted.
sec_acl_mgr_lookup Returns a copy of the object's
ACL.
sec_acl_mgr_replace Replaces the specified ACL.
ΓòÉΓòÉΓòÉ 8.1.2. Rdacl Routines ΓòÉΓòÉΓòÉ
The DCE ACL network interface, consisting of routines with a prefix of rdacl,
enables servers that manage access control (such as sec_acl_mgr-based ACL
managers) to communicate with sec_acl-based clients.
Applications never call the rdacl_xxx routines. They call the sec_acl_xxx
routines. This arrangement relieves the client application from some details of
managing server bindings.
The sec_acl_xxx routines use an ACL handle to specify the object whose ACL is
to be accessed. The sec_acl_bind routine must always be called to obtain this
handle, even if the client is already bound to the object's server.
The rdacl_xxx interface consists of the following routines:
rdacl_get_access Returns a principal's
permissions to an object. This
is useful for implementing
operations such as the
conventional UNIX system access
routine and in OS/2, the GUI
(Graphical User Interface)
interface.
rdacl_get_manager_types Returns a list of manager types
protecting the object.
rdacl_get_mgr_types_semantics Lists the ACL manager types
protecting an object and the
POSIX semantics supported by
each manager type.
rdacl_get_printstring Obtains human-readable
representations of permissions.
rdacl_get_referral Returns a referral to an ACL
update site. This routine
enables a client that attempts
to modify an ACL at a read-only
site to recover from the error
and rebind to an update site.
rdacl_lookup Retrieves a copy of the object's
ACL.
rdacl_replace Replaces the specified ACL.
rdacl_test_access Determines whether the calling
principal has the requested
permissions.
rdacl_test_access_on_behalf Determines whether the principal
represented by the calling
principal has the requested
permissions. This routine
returns TRUE if both the
principal and the calling
principal acting as its agent
have the requested permissions.
ΓòÉΓòÉΓòÉ 8.1.3. Data Types ΓòÉΓòÉΓòÉ
The following data types are used in the ACL API routines:
sec_acl_handle_t A pointer to an opaque handle bound to an ACL that is the
subject of a test or examination. The handle is bound to the ACL
with sec_acl_bind. An unbound handle has the value
sec_acl_default_handle.
sec_acl_posix_semantics_t A flag that indicates which, if any, POSIX ACL
semantics an ACL manager supports. The following constants are
defined for use with the sec_acl_posix_semantics_t data type:
sec_acl_posix_no_semantics The manager type does not support
POSIX semantics.
sec_acl_posix_mask_obj The manager type supports the mask_obj
entry type and POSIX 1003.6 Draft 12 ACL mask entry
semantics.
sec_acl_t This data type is the fundamental type for the ACL manager
interfaces. The sec_acl_t type contains a complete access control
list, made up of a list of entry fields (type sec_acl_entry_t). The
default cell identifies the authentication authority for simple ACL
entries (foreign entries identify their own foreign cells). The
sec_acl_manager_type identifies the manager to interpret this ACL.
The sec_acl_t type is a structure containing the following fields:
default_realm A structure of type sec_acl_id_t that identifies
the UUID and (optionally) the name of the default
cell.
sec_acl_manager_type Contains the UUID of the ACL manager type.
num_entries An unsigned 32-bit integer containing the number of
ACL entries in this ACL.
sec_acl_entries An array containing num_entries pointers to
different ACL entries, each of type sec_acl_entry_t.
sec_acl_p_t This data type, a pointer to a sec_acl_t, is for use with the
sec_acl_list_t data type.
sec_acl_list_t This data type is a structure containing two members:
num_acls An unsigned 32-bit integer that describes the
number of ACLs indicated by sec_acls.
sec_acls An array of pointers of type sec_acl_p_t.
sec_acl_entry_t The sec_acl_entry_t type is a structure made up of the
following components:
perms A set of flags of type sec_acl_permset_t that
describes the permissions granted for the principals
identified by this ACL entry. Note that if a
principal matches more than one ACL entry, the
effective permissions will be the most restrictive
combination of all the entries.
entry_info A structure containing two members:
entry_type A flag of type sec_acl_entry_type_t,
indicating the type of ACL entry.
tagged_union A tagged union whose contents
depend on the type of the entry. The
types of entries indicated by entry_type can be the
following:
sec_acl_e_type_user_obj The entry contains
permissions for the implied user
object. This type is described in the
POSIX 1003.6 standard.
sec_acl_e_type_group_obj The entry contains
permissions for the implied group
object. This type is described in the
POSIX 1003.6 standard.
sec_acl_e_type_other_obj The entry contains
permissions for principals not
otherwise named through user or group
entries. This type is described in the
POSIX 1003.6 standard.
sec_acl_e_type_user The entry contains a key
identifying a user. This type is
described in the POSIX 1003.6
standard.
sec_acl_e_type_group The entry contains a key
identifying a group. This type is
described in the POSIX 1003.6
standard.
sec_acl_e_type_mask_obj The entry contains the
maximum permissions for all entries
other than mask_obj, unauthenticated,
user_obj, and other_obj.
sec_acl_e_type_foreign_user The entry contains a
key identifying a user and the foreign
realm.
sec_acl_e_type_foreign_group The entry contains
a key identifying a group and the
foreign realm.
sec_acl_e_type_foreign_other The entry contains
a key identifying a foreign realm.
Any user that can authenticate to the
foreign realm is allowed access.
sec_acl_e_type_any_other The entry contains
permissions to be applied to any
accessor who can authenticate to any
realm, but is not identified in any
other entry (except
sec_acl_e_type_unauthenticated).
sec_acl_e_type_unauthenticated The entry
contains permissions to be applied
when the accessor does not pass
authentication procedures. A
privilege attribute certificate will
indicate that the caller's identity is
not authenticated. The identity is
used to match against the standard
entries, but the access rights are
masked by this mask. If this mask does
not exist in an ACL, the ACL is
assumed to grant no access and all
unauthenticated access attempts will
be denied.
Great care should be exercised when
allowing unauthenticated access to an
object. Almost by definition,
unauthenticated access is very easy to
spoof. The presence of this mask on
an ACL essentially means that anyone
can get at least as much access as
allowed by the mask.
sec_acl_e_type_extended The entry contains
additional pickled data. This kind of
entry cannot be interpreted, but it
can be used by an out-of-date client
when copying an ACL from one manager
to another (assuming that both
managers understand the data).
The contents of the tagged union depend on the entry
type.
For the following types, the union contains a UUID
and an optional print string (called
entry_info.tagged_union.id with type sec_id_t) for an
identified local principal, or for an identified
foreign realm.
o sec_acl_e_type_user
o sec_acl_e_type_group
o sec_acl_e_type_foreign_other. For the following
entry types, the union contains two UUIDs and
optional print strings (called entry_info.foreign_id
with type sec_id_foreign_t) for an identified foreign
principal and its realm.
o sec_acl_e_type_foreign_user
o sec_acl_e_type_foreign_group. For an extended
entry (sec_acl_e_type_extended), the union contains
entry_info.tagged_union.extended_info, a pointer to
an information block of type sec_acl_extend_info_t.
sec_acl_permset_t A 32-bit set of permission flags. The flags currently
represent the conventional file system permissions (read, write,
execute) and the extended DFS permissions (owner, insert, delete).
The unused flags represent permissions that can only be interpreted
by the manager for the object. For example,
sec_acl_perm_unused_00000080 can mean to one ACL manager that
withdrawals are allowed, and to another ACL manager that rebooting
is allowed.
The following constants are defined for use with the
sec_acl_permset_t data type:
sec_acl_perm_read The ACL allows read access to the protected
object.
sec_acl_perm_write The ACL allows write access to the protected
object.
sec_acl_perm_execute The ACL allows execute access to the
protected object.
sec_acl_perm_control The ACL allows the ACL itself to be
modified.
sec_acl_perm_insert The ACL allows insert access to the
protected object.
sec_acl_perm_delete The ACL allows delete access to the
protected object.
sec_acl_perm_test The ACL allows access to the protected object
only to the extent of being able to test for
existence. The bits from 0x00000080 to 0x80000000 are
not used by the conventional ACL permission set. Constants of the
form sec_acl_perm_unused_00000080 have been defined so application
programs can easily use these bits for extended ACLs.
sec_acl_extend_info_t This is an extended information block, provided for
future extensibility. Primarily this allows an out-of-date client to
read an ACL from a newer manager and apply it to another
(up-to-date) manager. The data cannot be interpreted by the
out-of-date client without access to the appropriate pickling
routines (that presumably are unavailable to such a client).
In general, ACL managers should not accept ACLs that contain entries
the manager does not understand. The manager clearly cannot perform
the security service requested by an uninterpretable entry and it is
considered a security breach to lead a client to believe that the
manager is performing a particular class of service if the manager
cannot do so.
The data structure is made up of the following components:
extension_type The UUID of the extension type.
format_label The format of the label, in ndr_format_t form.
num_bytes An unsigned 32-bit integer indicating the number of
bytes containing the pickled data.
pickled_data The byte array containing the pickled data.
sec_acl_type_t The sec_acl_type_t type differentiates between the various
types of ACLs an object can possess. Most file system objects have
only one ACL, controlling the access to that object, but objects
that control the creation of other objects (sometimes referred to as
containers) can have more. For example, a directory can have three
different ACLs: the directory ACL, controlling access to the
directory; the initial object (or default object) ACL, which serves
as a mask when creating new objects in the directory; and the
initial directory (or default directory) ACL, which serves as a mask
when creating new directories (containers).
The sec_acl_type_t data type is an enumerated set containing one of
the following values:
sec_acl_type_object The ACL refers to the specified object.
sec_acl_type_default_object The ACL is to be used when creating
objects in the container.
sec_acl_type_default_container The ACL is to be used when
creating nested containers. The following values are
defined but not currently used. They are available for application
programs that can create an application-specific ACL definition.
o sec_acl_type_unspecified_3
o sec_acl_type_unspecified_4
o sec_acl_type_unspecified_5
o sec_acl_type_unspecified_6
o sec_acl_type_unspecified_7.
sec_acl_printstring_t A sec_acl_printstring_t structure contains a printable
representation for a permission in a sec_acl_permset_t permission
set. This allows a generic ACL editing tool to be used for
application-specific ACLs. The tool need not know the printable
representation for each permission bit in a given permission set.
The sec_acl_get_printstring routine queries an ACL manager for the
print strings of the permissions it supports.
The structure consists of three components:
printstring A character string of maximum length
sec_acl_printstring_len describing the printable
representation of a specified permission.
helpstring A character string of maximum length
sec_acl_printstring_help_len containing some text
that can be used to describe the specified
permission.
permissions A sec_acl_permset_t permission set describing the
permissions that will be represented with the
specified print string.
sec_acl_component_name_t This type is a pointer to a character string, to be
used to specify the entity a given ACL is protecting.
ΓòÉΓòÉΓòÉ 8.1.4. Constants ΓòÉΓòÉΓòÉ
The following constants are used in sec_acl_xxx routines:
sec_acl_default_handle The value of an unbound ACL manager handle.
sec_rgy_pname_t_size The maximum number of characters in a sec_rgy_pname_t.
sec_acl_printstring_len The maximum length of the printable representation of
an ACL permission. (See sec_acl_printstring_t.)
sec_acl_printstring_help_len The maximum length of a help message to be
associated with a supported ACL permission. (See
sec_acl_printstring_t.
The following 32-bit integer constants are used with the sec_rgy_acct_key_t
data type:
sec_rgy_acct_key_none The key is not valid.
sec_rgy_acct_key_person The person name alone is enough.
sec_rgy_acct_key_group The person and group names are both necessary for the
account abbreviation.
sec_rgy_acct_key_org The person, group and organization names are all
necessary.
sec_rgy_acct_key_last Key values must be less than this constant.
The following constants are defined for use with the sec_acl_permset_t data
type:
sec_acl_perm_read The ACL allows read access to the protected object.
sec_acl_perm_write The ACL allows write access to the protected object.
sec_acl_perm_execute The ACL allows execute access to the protected object.
sec_acl_perm_owner The ACL allows owner-level access to the protected object.
sec_acl_perm_insert The ACL allows insert access to the protected object.
sec_acl_perm_delete The ACL allows delete access to the protected object.
sec_acl_perm_test The ACL allows access to the protected object only to the
extent of being able to test for existence.
sec_acl_perm_unused_00000080 - sec_acl_perm_unused_0x80000000 The bits from
0x00000080 to 0x80000000 are not used by the conventional ACL
permission set. Constants have been defined so application programs
can easily use these bits for extended ACLs.
ΓòÉΓòÉΓòÉ 8.1.5. sec_acl_bind ΓòÉΓòÉΓòÉ
Purpose
Returns a handle for an object's ACL.
Library
\lib\dceos2.lib
Format
#include <dce/daclif.h>
void sec_acl_bind(
unsigned_char_p_t entry_name,
boolean32 bind_to_entry,
sec_acl_handle_t *h,
error_status_t *status);
Parameters
Input
entry_name The name of the target object. Subsequent ACL
operations using the returned handle will affect the
ACL of this object.
bind_to_entry Bind indicator, for use when entry_name identifies both
an entry in the global namespace and an actual object.
A TRUE value binds the handle to the entry in the
namespace, while FALSE binds the handle to the actual
object.
Output
h A pointer to a sec_acl_handle_t type to receive the
returned ACL handle. The other sec_acl_xxx routines use
this handle to refer to the ACL for the object
specified with entry_name.
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns one of the following errors:
sec_acl_object_not_found The requested object
could not be found.
sec_acl_no_acl_found There is no ACL associated
with the specified object.
Usage
The sec_acl_bind routine returns a handle bound to the indicated
object's ACL. This routine is central to all the other sec_acl_xxx
routines, each of which requires this handle to identify the ACL on
which to operate.
Notes
If the specified name is both an actual object and an entry in the
global namespace, there are two ACLs associated with it. For
example, in addition to the ACL normally attached to file system
objects, the root directory of a file system has an ACL corresponding
to its entry in the global namespace. This controls access by
outsiders to the entire file system, whereas the resident ACL for the
root directory only controls access to the directory and, by
inheritance, its subdirectories. The ambiguity must be resolved with
the bind_to_entry parameter.
Related Information
Files:
\include\dce\daclif.idl - The idl file that dce\daclif.h was derived
from.
ΓòÉΓòÉΓòÉ 8.1.6. sec_acl_bind_to_addr ΓòÉΓòÉΓòÉ
Purpose
Returns a handle to an object identified by its network address.
Library
\lib\dceos2.lib
Format
#include <dce/daclif.h>
void sec_acl_bind_to_addr(
unsigned_char_p_t site_addr,
sec_acl_component_name_t component_name,
sec_acl_handle_t *h,
error_status_t *status);
Parameters
Input
site_addr An RPC string binding to the fully qualified network
address of the target object.
component_name The name of the target object. Subsequent ACL
operations using the returned handle will affect the
ACL of this object.
Output
h A pointer to a sec_acl_handle_t type to receive the
returned ACL handle. The other sec_acl_xxx routines use
this handle to refer to the ACL for the object
specified with entry_name.
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns one of the following errors:
sec_acl_bind_error The routine could not bind
to the requested site.
sec_acl_invalid_site_name The site_addr parameter
is not valid.
sec_acl_cant_allocate_memory Memory allocation
failure.
Usage
The sec_acl_bind_to_addr routine returns a handle bound to the
indicated object's ACL manager. This routine and the sec_acl_bind
routine are central to all the other sec_acl_xxx routines, each of
which requires a handle to identify the ACL on which to operate.
This routine differs from sec_acl_bind in that it binds to the
network address of the target object, rather than to a cell namespace
entry.
Therefore, unlike sec_acl_bind, it is possible to pass
sec_acl_bind_to_addr a null string as a component name and to bind
with a non-existent name. The purpose of this routine is to
eliminate the necessity of looking up an object's name. To validate
the name, use sec_acl_bind.
Related Information
Routines:
sec_acl_bind
Files:
\include\dce\daclif.idl - The idl file that dce\daclif.h was derived
from.
ΓòÉΓòÉΓòÉ 8.1.7. sec_acl_calc_mask ΓòÉΓòÉΓòÉ
Purpose
Returns the sec_acl_type_mask_obj entry for the specified ACL list.
Library
\lib\dceos2.lib
Format
#include <dce/daclif.h>
void sec_acl_calc_mask(
sec_acl_list_t *sec_acl_list,
error_status_t *status);
Parameters
Input/Output
sec_acl_list A pointer to a sec_acl_type_t data type that specifies
the number of ACLs of each ACL type. The sec_acl_type_t
data type distinguishes between the various types of
ACLs an object can posses for a given manager. In the
file system, for example, most objects have only one
ACL controlling the access to that object, but objects
that control the creation of other objects (sometimes
referred to as containers) can have more. A directory,
for example, can have ACLs to be used as initial values
when member objects are created.
Do not confuse ACL types with the permissions
corresponding to different ACL manager types or with
the ACL manager types themselves.
Output
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns the following error:
sec_acl_cant_allocate_memory The requested
operation requires more
memory than is available.
Usage
The sec_acl_calc_mask routine calculates and sets the
sec_acl_e_type_mask_obj entry of the specified ACL list. The value of
the sec_acl_e_type_mask_obj entry is the union of the permissions of
all ACL entries that refer to members of the file group class.
This operation is performed locally, within the client. The routine
does not check to determine if the manager to which the specified ACL
list will be submitted supports the sec_acl_e_type_mask_obj entry
type. The calling application must determine whether to call this
routine, after obtaining the required POSIX semantics, if any, by
means of the sec_acl_get_mgr_types_semantics routine.
Notes
This routine is provided in source code form.
Related Information
Routines:
sec_acl_get_mgr_types_semantics
Files:
\include\dce\daclif.idl - The idl file that dce\daclif.h was derived
from.
ΓòÉΓòÉΓòÉ 8.1.8. sec_acl_get_access ΓòÉΓòÉΓòÉ
Purpose
Lists the access (permission set) that the caller has for an object.
Library
\lib\dceos2.lib
Format
#include <dce/daclif.h>
void sec_acl_get_access(
sec_acl_handle_t h,
uuid_t *manager_type,
sec_acl_permset_t *net_rights,
error_status_t *status);
Parameters
Input
h A handle referring to the object whose ACL is to be
accessed. Use sec_acl_bind to create this handle.
manager_type A pointer to the UUID identifying the manager type of
the ACL in question. There can be more than one type
of ACL manager protecting the object whose ACL is bound
to the input handle. Use this parameter to distinguish
them. Use sec_acl_get_manager_types to acquire a list
of the manager types protecting a given object.
Output
net_rights The output list of access rights, in sec_acl_permset_t
form. This is a 32-bit set of permission flags
supported by the manager type.
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns an error.
Usage
The sec_acl_get_access routine determines the complete extent of
access to the specified object by the calling process. Although the
sec_acl_test_access and sec_acl_test_access_on_behalf routines are
the preferred method of testing access, this routine is useful for
implementing operations like the conventional UNIX access routine.
Permissions Required
The sec_acl_get_access routine requires at least one permission of
any kind on the object for which the access is to be returned.
Related Information
Routines: sec_acl_test_access
sec_acl_test_access_on_behalf
Files:
\include\dce\daclif.idl - The idl file that dce\daclif.h was derived
from.
ΓòÉΓòÉΓòÉ 8.1.9. sec_acl_get_error_info ΓòÉΓòÉΓòÉ
Purpose
Returns error information from an ACL handle.
Library
\lib\dceos2.lib
Format
#include <dce/daclif.h>
error_status_t sec_acl_get_error_info(
sec_acl_handle_t h);
Parameters
Input
h A handle referring to the target ACL. The handle is
bound to the ACL with the sec_acl_bind routine, which
also specifies the name of the object to which the
target ACL belongs.
Usage
The sec_acl_get_error_info routine returns error information from the
specified ACL handle.
During a call to a routine in the sec_acl_xxx API, error codes
received from the RPC runtime or other APIs are saved in the ACL
handle and a corresponding error code from the sec_acl_xxx set is
passed back by the ACL API. The sec_acl_get_error_info routine
returns the last error code stored in the ACL handle, for those
clients who need to know exactly what went wrong.
Return Codes
This routine returns a value of type error_status_t, indicating the
cause of the last error issued by the RPC runtime. The routine can
also return sec_acl_invalid_acl_handle, which indicated that the ACL
handle specified by h is not valid.
Related Information
Routines: sec_acl_bind
sec_acl_lookup
Files:
\include\dce\daclif.idl - The idl file that dce\daclif.h was derived
from.
ΓòÉΓòÉΓòÉ 8.1.10. sec_acl_get_manager_types ΓòÉΓòÉΓòÉ
Purpose
Lists the manager types of the ACLs protecting an object.
Library
\lib\dceos2.lib
Format
#include <dce/daclif.h>
void sec_acl_get_manager_types(
sec_acl_handle_t h,
sec_acl_type_t sec_acl_type,
unsigned32 size_avail,
unsigned32 *size_used,
unsigned32 *num_types,
uuid_t manager_types[],
error_status_t *status);
Parameters
Input
h A handle referring to the target object. Use
sec_acl_bind to create this handle.
sec_acl_type The ACL type. The sec_acl_type_t data type
distinguishes the various types of ACLs an object can
possess for a given manager type. Possible values are:
o sec_acl_type_object
o sec_acl_type_default_object
o sec_acl_type_default_container
size_avail An unsigned 32-bit integer containing the allocated
length of the manager_types array.
Output
size_used An unsigned 32-bit integer containing the number of
output entries returned in the manager_types array.
num_types An unsigned 32-bit integer containing the number of
types returned in the manager_types array. This can be
greater than size_used if there was not enough space
allocated in the manager_types array for all the
manager types.
manager_types An array of length size_avail to contain UUIDs (of type
uuid_t) identifying the different types of ACL managers
protecting the target object.
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns an error.
Usage
The sec_acl_get_manager_types routine returns a list of the manager
types of ACLs of type sec_acl_type that are protecting the object
identified by h. For example, in addition to the regular file system
ACL, a file representing the stable storage of some database could
have an ACL manager that supported permissions allowing database
updates only on certain days of the week.
ACL editors and browsers can use this operation to determine the ACL
manager types that a particular reference monitor is using to protect
a selected entity. Then, using the sec_acl_get_printstring routine,
they can determine how to format for display the permissions
supported by a specific manager.
Permissions Required
The sec_acl_get_manager_types routine requires at least one
permission of any kind on the object for which the ACL manager types
are to be returned.
Related Information
Routines: sec_acl_bind
sec_acl_get_printstring
Files:
\include\dce\daclif.idl - The idl file that dce\daclif.h was derived
from.
ΓòÉΓòÉΓòÉ 8.1.11. sec_acl_get_mgr_types_semantics ΓòÉΓòÉΓòÉ
Purpose
Lists the manager types of the ACLs protecting an object.
Library
\lib\dceos2.lib
Format
#include <dce/daclif.h>
void sec_acl_get_mgr_types_semantics(
sec_acl_handle_t h,
sec_acl_type_t sec_acl_type,
unsigned32 size_avail,
unsigned32 *size_used,
unsigned32 *num_types,
uuid_t manager_types[],
sec_acl_posix_semantics_t posix_semantics[],
error_status_t *status);
Parameters
Input
h A handle referring to the target object. Use
sec_acl_bind to create this handle.
sec_acl_type The ACL type. The sec_acl_type_t data type
distinguishes the various types of ACLs an object can
possess for a given manager type. Possible values are:
o sec_acl_type_object
o sec_acl_type_default_object
o sec_acl_type_default_container
size_avail An unsigned 32-bit integer containing the allocated
length of the manager_types array.
Output
size_used An unsigned 32-bit integer containing the number of
output entries returned in the manager_types array.
num_types An unsigned 32-bit integer containing the number of
types returned in the manager_types array. This might
be greater than size_used if there was not enough space
allocated in the manager_types array for all the
manager types.
manager_types An array of length size_avail to contain UUIDs (of type
uuid_t) identifying the different types of ACL managers
protecting the target object.
posix_semantics An array of POSIX semantics supported by each manager
type with entries of type sec_acl_posix_semantics_t.
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns an error.
Usage
The sec_acl_get_mgr_types_semantics routine returns a list of the
manager types of ACLs of type sec_acl_type that are protecting the
object identified by h. For example, in addition to the regular file
system ACL, a file representing the stable storage of some database
could have an ACL manager that supported permissions allowing
database updates only on certain days of the week.
ACL editors and browsers can use this operation to determine the ACL
manager types that a particular reference monitor is using to protect
a selected entity. Then, using the sec_acl_printstring routine, they
can determine how to format for display the permissions supported by
a specific manager.
Permissions Required
The sec_acl_get_mgr_types_semantics routine requires at least one
permission of any kind on the object for which the ACL manager types
are to be returned.
Related Information
Routines:
sec_acl_bind
sec_acl_get_printstring Files:
\include\dce\daclif.idl - The idl file from which dce\daclif.h was
derived.
ΓòÉΓòÉΓòÉ 8.1.12. sec_acl_get_printstring ΓòÉΓòÉΓòÉ
Purpose
Returns printable ACL strings.
Library
\lib\dceos2.lib
Format
#include <dce/daclif.h>
void sec_acl_get_printstring(
sec_acl_handle_t h,
uuid_t *manager_type,
unsigned32 size_avail,
uuid_t *manager_type_chain,
sec_acl_printstring_t *manager_info,
boolean32 *tokenize,
unsigned32 *total_num_printstrings,
unsigned32 *size_used,
sec_acl_printstring_t *printstrings,
error_status_t *status);
Parameters
Input
h A handle referring to the target object. Use
sec_acl_bind to create this handle.
manager_type A pointer to the UUID identifying the type of the ACL
manager in question. There may be more than one type of
ACL manager protecting the object whose ACL is bound to
the input handle. Use this parameter to distinguish
them. Use sec_acl_get_manager_types to acquire a list
of the manager types protecting a given object.
size_avail An unsigned 32-bit integer containing the allocated
length of the printstrings array.
Output
manager_type_chain If the target object ACL contains more than 32
permission bits, multiple manager types are used, one
for each 32-bit wide slice of permissions. The UUID
returned in manager_type_chain refers to the next ACL
manager in the chain. If there are no more ACL
managers for this ACL, uuid_nil is returned.
manager_info Provides a name and help string for the given ACL
manager.
tokenize When FALSE this parameter indicates that the returned
permission print strings are unambiguous and therefore
may be concatenated when printed without confusion.
When TRUE, however, this property does not hold and
the strings need to be separated when printed or
passed.
total_num_printstrings A pointer to an unsigned 32-bit integer
containing the total number of permission print strings
supported by this ACL manager type.
size_used A pointer to an unsigned 32-bit integer containing the
number of permission entries returned in the
printstrings array.
printstrings A pointer to a structure of permission print strings of
type sec_acl_printstring_t. Each structure contains the
following three components:
printstring A character string of maximum length
sec_acl_printstring_len describing
the printable representation of a
specified permission.
helpstring A character string of maximum length
sec_acl_printstring_help_len
containing some text that can be
used to describe the specified
permission.
permissions A sec_acl_permset_t permission set
describing the permissions that are
represented with the companion print
string.
There is one such entry for each
permission supported by the ACL
manager identified by manager_type.
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns one of the following errors:
sec_acl_unknown_manager_type The manager type
selected is not among those
referenced by the input
handle.
sec_acl_invalid_acl_handle The ACL handle
specified by h is not valid.
Usage
The sec_acl_get_printstring routine returns an array of printable
representations (print strings) for each permission bit or
combination of permission bits the specified ACL manager supports.
The ACL manager type specified must be one of the types protecting
the object indicated by h.
In addition to returning the print strings, this routine also returns
instructions about how to print the strings. When the tokenize
parameter is set to FALSE, a print string might be r or w, which
could be concatenated in the display as rw without any confusion.
However, when the tokenize parameter is TRUE, it implies the print
strings might be of a form like read or write, which must be
displayed separated by spaces or colons or some other delimiter.
In any list of permission print strings, there may seem to be some
redundancy. ACL managers often define aliases for common permission
combinations. By convention, however, simple entries should begin the
printstrings array, and combinations should end it.
Related Information
Routines:
sec_acl_bind
sec_acl_get_manager_types
Files:
\include\dce\daclif.idl - The idl file from which dce\daclif.h was
derived.
ΓòÉΓòÉΓòÉ 8.1.13. sec_acl_lookup ΓòÉΓòÉΓòÉ
Purpose
Returns the ACL for an object.
Library
\lib\dceos2.lib
Format
#include <dce/daclif.h>
void sec_acl_lookup(
sec_acl_handle_t h,
uuid_t *manager_type,
sec_acl_type_t sec_acl_type,
sec_acl_list_t *sec_acl_list,
error_status_t *status);
Parameters
Input
h A handle referring to the target object. Use
sec_acl_bind to create this handle.
manager_type A pointer to the UUID identifying the type of the ACL
manager in question. There may be more than one type
of ACL manager protecting the object whose ACL is bound
to the input handle. Use this parameter to distinguish
them. Use sec_acl_get_manager_types to acquire a list
of the manager types protecting a given object.
sec_acl_type The ACL type. The sec_acl_type_t data type
distinguishes the various types of ACLs an object can
possess for a given manager type. Possible values are:
o sec_acl_type_object
o sec_acl_type_default_object
o sec_acl_type_default_container
Output
sec_acl_list A pointer to the sec_acl_list_t structure to receive
the complete access control list. An ACL contains a
list of ACL entries, the UUID of the default cell where
authentication takes place (foreign entries in the ACL
contain the name of their home cell), and the UUID of
the ACL manager to interpret the list.
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns one of the following errors:
sec_acl_unknown_manager_type The manager type
selected is not an available
option.
sec_acl_cant_allocate_memory The requested
operation requires more
memory than is available.
sec_acl_invalid_acl_handle The ACL handle
specified by h is not valid.
Usage
The sec_acl_lookup routine loads into memory a copy of an object's
ACL corresponding to the specified manager type. The routine returns
a pointer to the ACL. This routine is only used by ACL editors and
browsers; an application would use sec_acl_test_access or
sec_acl_test_access_on_behalf to process the contents of an ACL.
Permissions Required
The sec_acl_lookup routine requires at least one permission of any
kind on the object for which the ACL is to be returned.
Notes
The memory containing the sec_acl_t structure for each ACL is
dynamically allocated. Use the sec_acl_release routine to return the
memory block from each ACL to the pool when an application is
finished with the ACLs.
Related Information
Routines:
sec_acl_bind
sec_acl_get_manager_types
sec_acl_release
sec_acl_test_access
sec_acl_test_access_on_behalf
Files:
\include\dce\daclif.idl - The idl file from which dce\daclif.h was
derived.
ΓòÉΓòÉΓòÉ 8.1.14. sec_acl_mgr_configure ΓòÉΓòÉΓòÉ
Purpose
Configures an ACL manager.
Library
None; provided with the acl_mgr example program.
Format
#include <dce/daclmgr.h>
void sec_acl_mgr_configure(
sec_acl_mgr_config_t config_info,
unsigned_char_p_t db_name,
sec_acl_mgr_handle_t *sec_acl_mgr,
error_status_t *status);
Parameters
Input
config_info An unsigned 32-bit set of flags containing
miscellaneous information about how to treat the
specified ACL database. Currently, only the following
two flags are used:
sec_acl_mgr_config_create Create a new database
with the given name. If one
with the input name already
exists, an error is returned.
sec_acl_mgr_config_stable Provide stable storage
for the database state. If
not set,
sec_acl_mgr_configure assumes
that the calling program
takes care of storing the ACL
database, and does not save
it.
db_name Identifies the ACL database to use. The name generally
refers to the file system object that represents the
persistent storage for the database.
Output
sec_acl_mgr A pointer to a handle for an ACL manager and the
storage configuration chosen with the config_info
parameter. Having a distinct handle for the combination
of ACL manager and configuration allows the application
to use different storage strategies for different types
of objects.
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Usage
The sec_acl_mgr_configure routine provides a handle to refer to the
particular ACL database in use and which is necessary for all other
ACL manager operations.
The only storage model supported by the current ACL manager interface
is one with a separate stable storage file.
Notes
This routine is not intended to be used by application programs. The
sec_acl Application Programming Interface (API) provides all the
functions necessary to use the ACL facility. This reference page is
provided for programmers who wish to write an ACL manager. In order
to write an ACL manager, a programmer must implement the entire rdacl
interface. The sec_acl_mgr reference pages are provided as an
example of a successful implementation.
Examples
Here is an example of the common usage of the ACL manager routines.
The application uses rpc_binding_inq_auth_client to acquire a
privilege attribute certificate.
application_op(handle_t h, ...) {
...
sec_acl_mgr_configure(<configuration info>,
<name of acl file system object>,
&sec_acl_mgr_handle, &status);
...
rpc_binding_inq_auth_client(h, PAC, &server_name, &lvl,
&authn_svc, &authz_svc, &status);
rpc_binding_inq_object(h, &object, &status);
if (sec_acl_mgr_is_authorized(acl_mgr_handle,
<needed permissions>,
PAC, (sec_acl_key_t) &object,
sec_acl_type_object, NULL, NULL, &status)) {
/* Application code to perform operation */
} else {
/* Caller is not authorized to have the desired permissions
* over the indicated object. Act accordingly...
*/
...
}
}
Related Information
Files:
\include\dce\daclmgr.idl - The idl file from which dce\daclmgrf.h was
derived.
ΓòÉΓòÉΓòÉ 8.1.15. sec_acl_mgr_get_access ΓòÉΓòÉΓòÉ
Purpose
Reads a privilege attribute certificate.
Library
None; provided with the acl_mgr example program.
Format
#include <dce/daclmgr.h>
void sec_acl_mgr_get_access(
sec_acl_mgr_handle_t sec_acl_mgr,
rpc_authz_cred_handle_t *accessor_info,
sec_acl_key_t sec_acl_key,
uuid_t *manager_type,
sec_id_t *user_obj,
sec_id_t *group_obj,
sec_acl_permset_t *net_rights,
error_status_t *status);
Parameters
Input
sec_acl_mgr A pointer to a handle for an ACL manager and the
storage configuration chosen with sec_acl_configure.
Having a distinct handle for the combination of ACL
manager and configuration allows the application to use
different storage strategies for different types of
objects.
accessor_info The accessor_info parameter refers to the privilege
attribute certificate (PAC) of the calling process. The
PAC contains the identity and group membership of the
calling process, which can then be compared with
entries in the ACL to determine whether it is
authorized to have indicated desired privileges. Use
rpc_binding_inq_auth_client to acquire a certificate
for the caller process.
sec_acl_key A pointer indicating the object whose ACL is in
question. The type of the pointer is dependent on the
ACL manager involved. For file system ACLs, it points
to a uuid_t parameter, containing the UUID and name of
the file system object.
manager_type A pointer to the UUID identifying the type of the ACL
manager in question. There may be more than one type of
ACL manager protecting the object whose ACL is bound to
the input handle. Use this parameter to distinguish
them. Use sec_acl_get_manager_types to acquire a list
of the manager types protecting a given object.
user_obj Contains the identity of the caller. This is to be used
when the ACL manager encounters a USER_OBJ field in an
ACL. The identity used is generally the person field
of the caller account. This parameter may be NULL,
although this produces an error and denial of access to
the object if the ACL contains a USER_OBJ entry.
group_obj Identical in use to the user_obj parameter, except this
refers to the group of the caller account and any
potential GROUP_OBJ entry in the target object's ACL.
Output
net_rights The output list of access rights, in sec_acl_permset_t
form. This is a 32-bit set of permission flags. The
flags may represent the conventional file system
permissions (read, write, execute), the extended AFS
permissions (owner, insert, delete), or some other
permissions supported only by the specific ACL manager.
For example, a bit that is unused for file system
permissions may mean withdrawals are allowed for a bank
ACL manager, while it may mean rebooting is allowed for
a CPU ACL manager.
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Usage
The sec_acl_mgr_get_access routine determines the complete extent of
access to the specified object by the process described in the input
privilege attribute certificate (called a PAC and referred to in the
accessor_info parameter). Although the sec_acl_mgr_is_authorized
routine is the preferred method of testing access, this routine is
useful for implementing operations like the conventional UNIX access
function.
The actual ACL to be compared against the input PAC is not passed
directly to this routine, but is referred to by the sec_acl_key and
the sec_acl_mgr parameters.
Notes
This routine is not intended to be used by application programs. The
sec_acl Application Programming Interface (API) provides all the
functions necessary to use the ACL facility. This reference page is
provided for programmers who wish to write an ACL manager. In order
to write an ACL manager, a programmer must implement the entire rdacl
interface. The sec_acl_mgr reference pages are provided as an example
of a successful implementation.
Related Information
Routines:
rpc_binding_inq_auth_client
sec_acl_mgr_configure
sec_acl_mgr_is_authorized
Files:
\include\dce\daclmgr.idl - The idl file from which dce\daclmgrf.h was
derived.
ΓòÉΓòÉΓòÉ 8.1.16. sec_acl_mgr_get_manager_types ΓòÉΓòÉΓòÉ
Purpose
Returns the types of ACLs that are protecting an object.
Library
None; provided with the acl_mgr example program.
Format
#include <dce/daclmgr.h>
void sec_acl_mgr_get_manager_types(
sec_acl_mgr_handle_t sec_acl_mgr,
sec_acl_key_t sec_acl_key,
sec_acl_type_t sec_acl_type,
unsigned32 size_avail,
unsigned32 *size_used,
unsigned32 *num_types,
uuid_t manager_types[],
error_status_t *status);
Parameters
Input
sec_acl_mgr A pointer to a handle for an ACL manager and the
storage configuration chosen with
sec_acl_mgr_configure. Having a distinct handle for the
combination of ACL manager and configuration allows the
application to use different storage strategies for
different types of objects.
sec_acl_key A pointer indicating the object whose ACL is in
question. The type of the pointer is dependent on the
ACL manager involved. For file system ACLs, it points
to a uuid_t parameter, containing the UUID and name of
the file system object.
sec_acl_type The ACL type. It is generally sec_acl_type_object.
The sec_acl_type_t data type distinguishes between the
various types of ACLs an object can possess for a given
manager. In the file system, for example, most objects
have only one ACL controlling the access to that
object, but objects that control the creation of other
objects (sometimes referred to as containers) may have
more. A directory, for example, can have ACLs to be
used as initial values when member objects are created.
Do not confuse ACL types with the permissions
corresponding to different ACL manager types or with
the ACL manager types themselves.
size_avail An unsigned 32-bit integer containing the allocated
length of the manager_types array.
Output
size_used An unsigned 32-bit integer containing the actual length
of the manager_types array.
num_types An unsigned 32-bit integer containing the actual number
of manager types returned in the manager_types array.
manager_types An array of manager types in which each entry is of
type uuid_t.
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns the following error:
sec_acl_cant_allocate_memory Requested operation
requires more memory than is
available.
Usage
The sec_acl_mgr_get_manager_types routine returns the types of ACLs
that are protecting an object. ACL editors and browsers can use this
routine to determine the ACL manager types that a particular
reference monitor is using to manage the ACLs of sec_acl_type on the
object identified by sec_acl_key.
The number of the ACL manager types supported by the object for the
specified sec_acl_type is returned in num_types. The actual ACL
manager types are returned as entries in the manager_types array.
If the returned size is greater than the specified size_avail, invoke
the routine again with a buffer large enough to hold the returned
information.
Note that if num_types is greater than 1, it means that the object is
polymorphic and supports ACL manager types for each of its forms.
File
\include\dce\daclmgr.idl The idl file that dce\daclmgrf.h was derived
from.
Related Information
Routines:
sec_acl_mgr_configure
sec_acl_mgr_get_access
sec_acl_mgr_is_authorized
ΓòÉΓòÉΓòÉ 8.1.17. sec_acl_mgr_get_types_semantics ΓòÉΓòÉΓòÉ
Purpose
Returns the types of ACLs and the POSIX semantics that are protecting
an object.
Library
None; provided with the acl_mgr example program.
Format
#include <dce/daclmgr.h>
void sec_acl_mgr_get_types_semantics(
sec_acl_handle_t sec_acl_mgr,
sec_acl_key_t sec_acl_key,
sec_acl_type_t sec_acl_type,
unsigned32 size_avail,
unsigned32 *size_used,
unsigned32 *num_types,
uuid_t manager_types[],
sec_acl_posix_semantics posix_semantics[],
error_status_t *status);
Parameters
Input
sec_acl_mgr A pointer to a handle for an ACL manager and the
storage configuration chosen with
sec_acl_mgr_configure. Having a distinct handle for the
combination of ACL manager and configuration allows the
application to use different storage strategies for
different types of objects.
sec_acl_key A pointer indicating the object whose ACL is in
question. The type of the pointer depends on the ACL
manager involved. For file system ACLs, it points to a
uuid_t parameter, containing the UUID and name of the
system object.
sec_acl_type The ACL type. It is generally sec_acl_type_object. The
sec_acl_type_t data type distinguishes between the
various types of ACLs an object can possess for a given
manager. In the file system, for example, most objects
have only one ACL controlling the access to that
object, but objects that control the creation of other
objects (sometimes referred to as "containers") may
have more. A directory, for example, can have ACLs to
be used as initial values when member objects are
created.
Do not confuse ACL types with the permissions
corresponding to different ACL manager types or with
the ACL manager types themselves.
size_avail An unsigned 32-bit integer containing the allocated
length of the manager_types array.
Output
size_used An unsigned 32-bit integer containing the actual length
of the manager_types array.
num_types An unsigned 32-bit integer containing the actual number
of manager types returned in the manager_types array.
manager_types An array of manager types in which each entry is of
type uuid_t.
posix_semantics An array of POSIX semantics supported by each manager
type with entries of type sec_acl_posix_semantics.
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns the following error:
sec_acl_cant_allocate_memory The requested
operation requires more memory than
is available.
Usage
The sec_acl_mgr_get_types_semantics routine returns the types of ACLs
that are protecting an object. ACL editors and browsers can use this
routine to determine the ACL manager types that a particular
reference monitor is using to manage the ACLs of sec_acl_type on the
object identified by sec_acl_key.
The number of the ACL manager types supported by the object for the
specified sec_acl_type is returned in num_types. The actual ACL
manager types are returned as entries in the manager_types array.
If the returned size is greater than the specified size_avail, invoke
the routine again, with a buffer large enough to hold the returned
information.
Note that if num_types is greater than 1, it means that the object is
polymorphic and supports ACL manager types for each of its forms.
This routine is provided in source code form.
File
\include\dce\daclmgr.idl The idl file that dce\daclmgrf.h was derived
from.
Related Information
routines:
sec_acl_mgr_configure
sec_acl_mgr_get_access
sec_acl_mgr_is_authorized
ΓòÉΓòÉΓòÉ 8.1.18. sec_acl_mgr_get_printstring ΓòÉΓòÉΓòÉ
Purpose
Returns printable ACL strings.
Library
None; provided with the acl_mgr example program.
Format
#include <dce/daclmgr.h>
void sec_acl_mgr_get_printstring(
sec_acl_mgr_handle_t sec_acl_mgr,
uuid_t *manager_type,
unsigned32 size_avail,
uuid_t *manager_type_chain,
sec_acl_printstring_t *manager_info,
boolean32 *tokenize,
unsigned32 *total_num_printstrings,
unsigned32 *size_used,
sec_acl_printstring_t printstrings[],
error_status_t *status);
Parameters
Input
sec_acl_mgr A pointer to a handle for an ACL manager and the
storage configuration chosen with sec_acl_configure.
Having a distinct handle for the combination of ACL
manager and configuration allows the application to use
different storage strategies for different types of
objects.
manager_type The ACL manager type.
size_avail An unsigned 32-bit integer containing the allocated
length of the printstrings array.
Output
manager_type_chain If the target object ACL contains more than 32
permission bits, multiple manager types are used, one
for each 32-bit wide slice of permissions. The UUID
returned in manager_type_chain refers to the next ACL
manager in the chain. If there are no more ACL
managers for this ACL, uuid_nil is returned.
manager_info A print string providing a name and help string for the
given ACL manager.
tokenize When FALSE this parameter indicates that the returned
permission print strings are unambiguous and therefore
may be concatenated when printed without confusion.
When TRUE, however, this property does not hold, and
the strings need to be separated when printed or
passed.
total_num_printstrings An output pointer to an unsigned 32-bit
integer indicating the total number of print strings
supported by this ACL manager. If size_avail is
smaller than total_num_printstrings, multiple calls to
sec_acl_mgr_get_printstring are necessary to retrieve
all the supported print strings.
size_used An unsigned 32-bit integer containing the number of
permission entries returned in the printstrings array.
printstrings An array of permission print strings of type
sec_acl_printstring_t. Each entry of the array is a
structure containing three components:
printstring A character string of maximum length
sec_acl_printstring_len describing
the printable representation of a
specified permission.
helpstring A character string of maximum length
sec_acl_printstring_help_len
containing some text that can be
used to describe the specified
permission.
permissions A sec_acl_permset_t permission set
describing the permissions that are
represented with the companion print
string. The array consists of one
such entry for each permission supported by the target
ACL manager.
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Usage
The sec_acl_mgr_get_printstring routine returns an array of printable
representations (print strings) for each permission bit or
combination of permission bits the ACL manager will support.
In addition to returning the print strings, this routine also returns
instructions about how to print the strings. When the tokenize
parameter is set to FALSE, a print string might be r or w, which
could be concatenated in the display as rw without any confusion.
However, when the tokenize parameter is TRUE, it implies the print
strings might be of a form like read or write, which must be
displayed separated by spaces or colons or some other separator.
In any list of permission print strings, there may appear to be some
redundancy. ACL managers often define aliases for common permission
combinations. By convention, however, simple entries should appear
at the beginning of the printstrings array, and combinations should
appear at the end.
Notes
This routine is not intended to be used by application programs. The
sec_acl Application Programming Interface (API) provides all the
functions necessary to use the ACL facility. This reference page is
provided for programmers who wish to write an ACL manager. In order
to write an ACL manager, a programmer must implement the entire rdacl
interface. The sec_acl_mgr reference pages are provided as an
example of a successful implementation.
File
\include\dce\daclmgr.idl The idl file that dce\daclmgrf.h was derived
from.
Related Information
Routines:
sec_acl_mgr_configure
ΓòÉΓòÉΓòÉ 8.1.19. sec_acl_mgr_is_authorized ΓòÉΓòÉΓòÉ
Purpose
Compares a privilege attribute certificate with an ACL.
Library
None; provided with the acl_mgr example program.
Format
#include <dce/daclmgr.h>
boolean32 sec_acl_mgr_is_authorized(
sec_acl_mgr_handle_t sec_acl_mgr,
sec_acl_permset_t desired_access,
rpc_authz_cred_handle_t *accessor_info,
sec_id_pac_t *pac,
sec_acl_key_t sec_acl_key,
uuid_t *manager_type,
sec_id_t *user_obj,
sec_id_t *group_obj,
error_status_t *status);
Parameters
Input
sec_acl_mgr A pointer to a handle for an ACL manager and the
storage configuration chosen with sec_acl_configure.
Having a distinct handle for the combination of ACL
manager and configuration allows the application to use
different storage strategies for different types of
objects.
desired_access A permission set in sec_acl_permset_t form containing
the desired privileges. This is a 32-bit set of
permission flags. The flags can represent the
conventional file system permissions (read, write,
execute), the extended file system permissions (insert,
delete), or some other permissions supported only by
the specific ACL manager. For example, a bit that is
unused for file system permissions may mean withdrawals
are allowed for a bank ACL manager, while it may mean
rebooting is allowed for a CPU ACL manager.
accessor_info The accessor_info parameter refers to the privilege
attribute certificate (PAC) of the calling process. The
PAC contains the identity and group membership of the
calling process, which can then be compared with
entries in the ACL to determine whether it is
authorized to have indicated desired privileges. Use
rpc_binding_inq_auth_client to acquire a certificate
for the calling process.
sec_acl_key A pointer indicating the object whose ACL is in
question. The type of the pointer is dependent on the
ACL manager involved. For file system ACLs, it points
to a uuid_t parameter, containing the UUID and name of
the file system object.
manager_type The ACL manager type.
user_obj Contains the identity of the caller. This is to be used
when the ACL manager encounters a USER_OBJ field in an
ACL. The identity used is generally the person field of
the caller account. This parameter may be NULL,
although this produces an error and denial of access to
the object if the ACL contains a USER_OBJ entry.
group_obj Identical in use to the user_obj parameter, except this
refers to the group of the caller account and any
potential GROUP_OBJ entry in the target object's ACL.
Output
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Usage
The sec_acl_mgr_is_authorized routine interprets an ACL, compares it
to a privilege attribute certificate (called a PAC and referred to in
the accessor_info parameter) for a process, and declares whether that
process is permitted to have the access implied by the privileges in
desired_access. This is the basic function of an ACL manager.
Applications that provide controlled access to objects must acquire a
PAC and submit that certificate to the ACL manager through this
function.
The actual ACL to be compared against the input PAC is not passed
directly to this routine, but is referred to by the sec_acl_key and
the manager_type parameters.
Notes
This routine is not intended to be used by application programs. The
sec_acl Application Programming Interface (API) provides all the
functions necessary to use the ACL facility. This reference page is
provided for programmers who wish to write an ACL manager. In order
to write an ACL manager, a programmer must implement the entire rdacl
interface. The sec_acl_mgr reference pages are provided as an
example of a successful implementation.
Return Codes
The routine returns TRUE if the caller process is authorized to
perform the operations implied by the privileges specified in
desired_permset.
Examples
Following is an example of the common usage of the ACL manager
routines. The application uses rpc_binding_inq_auth_client to acquire
a PAC and sec_acl_mgr_configure to acquire the ACL manager handle.
application_op(handle_t h, ...{
...
sec_acl_mgr_configure(<configuration info>,
<name of acl file system object>,
&sec_acl_mgr_handle, &status);
...
rpc_binding_inq_auth_client(h, PAC, &server_name,
&lvl, &authn_svc, &authz_svc, &status);
rpc_binding_inq_object(h, &object, &status);
if (sec_acl_mgr_is_authorized(acl_mgr_handle,
<needed permissions>,
PAC, (sec_acl_key_t) &object,
sec_acl_type_object, NULL, NULL, &status)) {
/* Application code to perform operation */
} else {
/* Caller is not authorized to have the desired permissions over
* the indicated object. Act accordingly...
*/
...
}
}
Related Information
Routines:
sec_acl_mgr_configure
sec_acl_mgr_get_access
Files:
\include\dce\daclmgr.idl - The idl file from which dce\daclmgrf.h was
derived.
ΓòÉΓòÉΓòÉ 8.1.20. sec_acl_mgr_lookup ΓòÉΓòÉΓòÉ
Purpose
Finds an ACL using its key.
Library
None; provided with the acl_mgr example program.
Format
#include <dce/daclmgr.h>
void sec_acl_mgr_lookup(
sec_acl_mgr_handle_t sec_acl_mgr,
sec_acl_key_t sec_acl_key,
uuid_t *manager_type,
sec_acl_type_t sec_acl_type,
sec_acl_list_t **sec_acl_list,
error_status_t *status);
Parameters
Input
sec_acl_mgr A pointer to a handle for an ACL manager and the
storage configuration chosen with
sec_acl_mgr_configure. Having a distinct handle for the
combination of ACL manager and configuration allows the
application to use different storage strategies for
different types of objects.
sec_acl_key A pointer indicating the object whose ACL is in
question. The type of the pointer is dependent on the
ACL manager involved. For file system ACLs, it points
to a uuid_t parameter, containing the UUID and name of
the file system object.
manager_type The ACL manager type.
sec_acl_type The ACL type. It is generally sec_acl_type_object. The
sec_acl_type_t data type distinguishes between the
various types of ACLs an object can possess for a given
manager. In the file system, for example, most objects
have only one ACL controlling the access to that
object, but objects that control the creation of other
objects (sometimes referred to as containers) may have
more. A directory, for example, can have ACLs to be
used as initial values when member objects are created.
Do not confuse ACL types with the permissions
corresponding to different ACL manager types or with
the ACL manager types themselves.
Output
sec_acl_list A pointer to the sec_acl_list_t structure to receive
the complete access control list. An ACL contains a
list of ACL entries, the UUID of the default cell where
authentication takes place (foreign entries in the ACL
contain the name of their parent cell), and the UUID of
the ACL manager to interpret the list.
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns sec_acl_cant_allocate_memory,
which indicates that the requested operation requires
more memory than is available.
Usage
The sec_acl_mgr_lookup routine loads into memory a copy of the ACL
corresponding to the sec_acl_key. The routine returns a pointer to
the ACL. This routine is only used by ACL editors and browsers; an
application uses sec_acl_mgr_get_access or sec_acl_mgr_is_authorized
to process the contents of an ACL.
Notes
This routine is not intended to be used by application programs. The
sec_acl Application Programming Interface (API) provides all the
functions necessary to use the ACL facility. This reference page is
provided for programmers who want to write an ACL manager. In order
to write an ACL manager, a programmer must implement the entire rdacl
interface. The sec_acl_mgr reference pages are provided as an
example of a successful implementation.
File
\include\dce\daclmgr.idl The idl file that dce\daclmgrf.h was derived
from.
Related Information
Routines:
sec_acl_mgr_configure
sec_acl_mgr_get_access
sec_acl_mgr_is_authorized
ΓòÉΓòÉΓòÉ 8.1.21. sec_acl_mgr_replace ΓòÉΓòÉΓòÉ
Purpose
Replaces an ACL.
Library
None; provided with the acl_mgr example program.
Format
#include <dce/daclmgr.h>
void sec_acl_mgr_replace(
sec_acl_mgr_handle_t sec_acl_mgr,
sec_acl_key_t sec_acl_key,
uuid_t *manager_type,
sec_acl_type_t sec_acl_type,
sec_acl_list_t *sec_acl_list,
error_status_t *status);
Parameters
Input
sec_acl_mgr A pointer to a handle for an ACL manager and the
storage configuration chosen with
sec_acl_mgr_configure. Having a distinct handle for the
combination of ACL manager and configuration allows the
application to use different storage strategies for
different types of objects.
sec_acl_key A pointer indicating the object whose ACL is in
question. The type of the pointer depends on the ACL
manager involved. For file system ACLs, it points to a
uuid_t parameter, containing the UUID and name of the
file system object.
manager_type A pointer indicating the ACL manager type.
sec_acl_type The ACL type. It is generally sec_acl_type_object. The
sec_acl_type_t data type distinguishes between the
various types of ACLs an object can possess for a given
manager. In the file system, for example, most objects
will have only one ACL controlling the access to that
object, but objects that control the creation of other
objects (sometimes referred to as containers) may have
more. A directory, for example, can have ACLs to be
used as initial values when member objects are created.
Do not confuse ACL types with the permissions
corresponding to different ACL manager types or with
the ACL manager types themselves.
sec_acl_list The new ACL to use for the target object. This is
represented by a pointer to the sec_acl_list_t
structure containing the complete access control list.
An ACL contains a list of ACL entries, the UUID of the
default cell where authentication will take place
(foreign entries in the ACL contain the name of their
parent cell), and the UUID of the ACL manager to
interpret the list.
Output
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns sec_acl_cant_allocate_memory,
which indicates that the requested operation requires
more memory than is available.
Usage
The sec_acl_mgr_replace routine replaces the ACL indicated by the
input handle with the information in the sec_acl_list parameter. This
package treats ACLs as immutable, and in order to modify them an
editing application must read an entire ACL (using
sec_acl_mgr_lookup), modify it as needed, and replace it using this
routine.
Cautions
There is no authorization checking performed on this operation; it is
strictly local. The application needs to call
sec_acl_mgr_is_authorized with desired_permset set to something
indicating permission to set the ACL before actually attempting the
replace.
Notes
The data type that stores an ACL has a limited size. Attempting to
add too many entries generates a sec_acl_cant_allocate_memory error.
This routine is not intended to be used by application programs. The
sec_acl Application Programming Interface (API) provides all the
functions necessary to use the ACL facility. This reference page is
provided for programmers who wish to write an ACL manager. In order
to write an ACL manager, a programmer must implement the entire rdacl
interface. The sec_acl_mgr reference pages are provided as an
example of a successful implementation.
File
\include\dce\daclmgr.idl The idl file that dce\daclmgrf.h was derived
from.
Related Information
Routines:
sec_acl_mgr_configure
sec_acl_mgr_is_authorized
sec_acl_mgr_lookup
ΓòÉΓòÉΓòÉ 8.1.22. sec_acl_release ΓòÉΓòÉΓòÉ
Purpose
Releases ACL storage.
Library
\lib\dceos2.lib
Format
#include <dce/daclif.h>
void sec_acl_release(
sec_acl_handle_t h,
sec_acl_t *sec_acl,
error_status_t *status);
Parameters
Input
h A handle referring to the target object. Use
sec_acl_bind to create this handle.
sec_acl A pointer to the complete ACL associated with the
target object.
Output
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns an error.
Usage
The sec_acl_release routine releases any local storage associated
with the ACL object, returning it to the pool. This is strictly a
local operation (since the storage in question is local), and has no
effect on the remote object or its ACL. The ACL handle is in the
argument list only for consistency with other sec_acl_xxx routines.
File
\include\dce\daclmgr.idl The idl file that dce\daclmgrf.h was derived
from.
Related Information
Routines:
sec_acl_bind
sec_acl_lookup
ΓòÉΓòÉΓòÉ 8.1.23. sec_acl_release_handle ΓòÉΓòÉΓòÉ
Purpose
Removes an ACL handle.
Library
\lib\dceos2.lib
Format
#include <dce/daclif.h>
void sec_acl_release_handle(
sec_acl_handle_t *h,
error_status_t *status);
Parameters
Input
h The handle to be removed. The handle is bound to the
object to which the ACL belongs with the sec_acl_bind
routine.
Output
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns an error.
Usage
The sec_acl_release_handle routine removes the specified handle.
This is strictly a local operation, and has no effect on the remote
object or its ACL.
File
\include\dce\daclmgr.idl The idl file that dce\daclmgrf.h was derived
from.
Related Information
Routines:
sec_acl_bind
ΓòÉΓòÉΓòÉ 8.1.24. sec_acl_replace ΓòÉΓòÉΓòÉ
Purpose
Replaces an ACL.
Library
\lib\dceos2.lib
Format
#include <dce/daclif.h>
void sec_acl_replace(
sec_acl_handle_t h,
uuid_t *manager_type,
sec_acl_type_t sec_acl_type,
sec_acl_list_t *sec_acl_list,
error_status_t *status);
Parameters
Input
h A handle referring to the target object. Use
sec_acl_bind to create this handle.
manager_type A pointer to the UUID identifying the type of the ACL
manager in question. There may be more than one type
of ACL manager protecting the object whose ACL is bound
to the input handle. Use this parameter to distinguish
them. Use sec_acl_get_manager_types to acquire a list
of the manager types protecting a given object.
sec_acl_type The ACL type. The sec_acl_type_t data type
distinguishes the various types of ACLs an object can
possess for a given manager type. The possible values
are
o sec_acl_type_object
o sec_acl_type_default_object
o sec_acl_type_default_container
sec_acl_list The new ACL to use for the target object. This is
represented by a pointer to the sec_acl_list_t
structure containing the complete access control list.
An ACL contains a list of ACL entries, the UUID of the
default cell where authentication will take place
(foreign entries in the ACL contain the name of their
parent cell), and the UUID of the ACL manager to
interpret the list.
Output
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns one of the following errors:
sec_acl_cant_allocate_memory The requested
operation requires more memory than
is available.
sec_acl_unknown_manager_type The manager type
selected is not an available option.
Usage
The sec_acl_replace routine replaces the ACL indicated by the input
handle with the information in the sec_acl_list parameter. ACLs are
thought of as immutable, and in order to modify them, an editing
application must read an entire ACL (using sec_acl_lookup), modify it
as needed, and replace it using this routine.
The data type that stores an ACL has a limited size. Attempting to
add too many entries generates a sec_acl_cant_allocate_memory error.
Permissions Required
The sec_acl_replace routine requires the c (control) permission on
the object for which the ACL is to be replaced.
File
\include\dce\daclif.idl The idl file that dce\daclif.h was derived
from.
Related Information
Routines:
sec_acl_bind
sec_acl_get_manager_types
sec_acl_lookup
ΓòÉΓòÉΓòÉ 8.1.25. sec_acl_test_access ΓòÉΓòÉΓòÉ
Purpose
Tests access to an object.
Library
\lib\dceos2.lib
Format
#include <dce/daclif.h>
boolean32 sec_acl_test_access(
sec_acl_handle_t h,
uuid_t *manager_type,
sec_acl_permset_t desired_permset,
error_status_t *status);
Parameters
Input
h A handle referring to the target object. Use
sec_acl_bind to create this handle.
manager_type A pointer to the UUID identifying the type of the ACL
manager in question. There may be more than one type
of ACL manager protecting the object whose ACL is bound
to the input handle. Use this parameter to distinguish
them. Use sec_acl_get_manager_types to acquire a list
of the manager types protecting a given object.
desired_permset A permission set in sec_acl_permset_t form containing
the desired privileges. This is a 32-bit set of
permission flags supported by the manager type.
Output
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns the following error:
sec_acl_unknown_manager_type The manager type
selected is not an available
option.
Usage
The sec_acl_test_access routine determines if the specified ACL
contains entries granting privileges to the calling process matching
those in desired_permset. An application generally only inquires
after the minimum set of privileges needed to accomplish a specific
task.
Permissions Required
The sec_acl_test_access routine requires at least one permission of
any kind on the object for which the privileges are to be tested.
Return Codes
The routine returns TRUE if the calling application is authorized to
access the target object with the privileges in desired_permset.
File
\include\dce\daclif.idl The idl file that dce\daclif.h was derived
from.
Related Information
Routines:
sec_acl_bind
sec_acl_get_manager_types
sec_acl_test_access_on_behalf
ΓòÉΓòÉΓòÉ 8.1.26. sec_acl_test_access_on_behalf ΓòÉΓòÉΓòÉ
Purpose
Tests access to an object on behalf of another process.
Library
\lib\dceos2.lib
Format
#include <dce/daclif.h>
boolean32 sec_acl_test_access_on_behalf(
sec_acl_handle_t h,
uuid_t *manager_type,
sec_id_pac_t *subject,
sec_acl_permset_t desired_permset,
error_status_t *status);
Parameters
Input
h A handle referring to the target object. Use
sec_acl_bind to create this handle.
manager_type A pointer to the UUID identifying the type of the ACL
manager in question. There may be more than one type
of ACL manager protecting the object whose ACL is bound
to the input handle. Use this parameter to distinguish
them. Use sec_acl_get_manager_types to acquire a list
of the manager types protecting a given object.
subject A privilege attribute certificate (PAC) for the subject
process. The PAC contains the name and UUID of the
principal and cell of the subject process, as well as a
list of any groups to which it belongs. The PAC also
contains a flag (named authenticated). When set, it
indicates that the certificate was obtained from an
authenticated source. When not set, the certificate
must not be trusted. (The field is FALSE when it was
obtained from the rpc_auth layer and the protect level
was set to rpc_c_protect_level_none. This indicates
that no authentication protocol was actually used in
the remote procedure call; the identity was simply
transmitted from the caller to the procedure being
called. If an authentication protocol was used, then
the flag is set to TRUE.)
If a null PAC is passed, the subject is treated as an
anonymous user, matching only the any_other and
unauthenticated entries (if they exist) on the ACL.
A server uses rpc_binding_inq_auth_client to acquire a
certificate for the client process.
desired_permset A permission set in sec_acl_permset_t form containing
the desired privileges. This is a 32-bit set of
permission flags supported by the manager type.
Output
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns the following error:
sec_acl_unknown_manager_type The manager type
selected is not an available
option.
Usage
The sec_acl_test_access_on_behalf routine determines if the specified
ACL contains entries that grant the privileges specified in
desired_permset to the subject process. An application generally
inquires about only the minimum set of privileges needed to
accomplish a specific task.
Permissions Required
The sec_acl_test_access_on_behalf routine requires at least one
permission of any kind on the object for which the privileges are to
be tested. Both the calling process and the identified subject must
have permission on the object.
Return Codes
If the routine completes successfully (with a completion status of
error_status_ok), it returns a value of:
o TRUE if the caller has any access (at least one permission of
any kind) and the subject has the desired_permset privileges.
o FALSE if both the caller and the subject have any access, but
the subject does not have the desired_permset privileges.
If the routine does not complete successfully, it returns a bad
completion status code and a return value of FALSE.
File
\include\dce\daclif.idl The idl file that dce\daclif.h was derived
from.
Related Information
Routines:
rpc_binding_inq_auth_client
sec_acl_bind
sec_acl_get_manager_types
sec_acl_test_access
ΓòÉΓòÉΓòÉ 8.1.27. rdacl_get_access ΓòÉΓòÉΓòÉ
Purpose
Reads a privilege attribute certificate.
Library
None. This network interface is called on the client side by the
sec_acl local interface. Developers are responsible for implementing
the server side of this interface. Test server code is included as a
sample implementation in the acl_mgr example program.
Format
#include <dce/rdaclif.h>
void rdacl_get_access(
handle_t h,
sec_acl_component_name_t component_name,
uuid_t *manager_type,
sec_acl_permset_t *net_rights,
error_status_t *status);
Parameters
Input
h A handle referring to the object whose ACL is to be
accessed. Use sec_acl_bind to create this handle.
component_name A character string containing the name of the target
object.
manager_type A pointer to the UUID identifying the type of the ACL
manager in question. There may be more than one type
of ACL manager protecting the object whose ACL is bound
to the input handle. Use this parameter to distinguish
them. Use sec_acl_get_manager_types to acquire a list
of the manager types protecting a given object.
Output
net_rights The output list of access rights, in sec_acl_permset_t
form. This is a 32-bit set of permission flags
supported by the manager type.
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns one of the following errors:
sec_acl_invalid_manager_type The manager type is
not valid.
sec_acl_invalid_acl_type The ACL type is not
valid.
sec_acl_not_authorized The requested operation is
not allowed.
sec_acl_object_not_found The requested object
could not be found.
Usage
The rdacl_get_access routine determines the complete extent of access
to the specified object by the calling process. Although the
rdacl_test_access routines are the preferred method of testing
access, this routine is useful for implementing operations like the
conventional UNIX access function.
Notes
This routine is not intended to be used by application programs. The
sec_acl Application Programming Interface (API) provides all the
routines necessary to use the ACL facility. This reference page is
provided for programmers who want to write an ACL manager. To write
an ACL manager, a programmer must implement the entire rdacl
interface.
This network interface is called on the client side by sec_acl local
interface. Developers are responsible for implementing the server
side of this interface. Test server code is included as a sample
implementation.
File
\include\dce\rdaclif.idl The idl file that dce\rdaclif.h was derived
from.
Related Information
Routines:
rdacl_test_access
sec_acl_get_manager_types
ΓòÉΓòÉΓòÉ 8.1.28. rdacl_get_manager_types ΓòÉΓòÉΓòÉ
Purpose
Lists the types of ACLs protecting an object.
Library
None. This network interface is called on the client side by the
sec_acl local interface. Developers are responsible for implementing
the server side of this interface. Test server code is included as a
sample implementation in the acl_mgr example program.
Format
#include <dce/rdaclif.h>
void rdacl_get_manager_types(
handle_t h ,
sec_acl_component_name_t component_name,
sec_acl_type_t sec_acl_type,
unsigned32 size_avail,
unsigned32 *size_used,
unsigned32 *num_types,
uuid_t manager_types[],
error_status_t *status);
Parameters
Input
h A handle referring to the target object. Use
sec_acl_bind to create this handle.
component_name A character string containing the name of the target
object.
sec_acl_type The ACL type. The sec_acl_type_t data type
distinguishes the various types of ACLs an object can
possess for a given manager type. Possible values are
o sec_acl_type_object
o sec_acl_type_default_object
o sec_acl_type_default_container
size_avail An unsigned 32-bit integer containing the allocated
length of the manager_types array.
Output
size_used An unsigned 32-bit integer containing the number of
output entries returned in the manager_types array.
num_types An unsigned 32-bit integer containing the number of
types returned in the manager_types array. This is
always equal to size_used.
manager_types An array of length size_avail to contain UUIDs (of type
uuid_t) identifying the different types of ACL managers
protecting the target object.
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns an error.
Usage
The rdacl_get_manager_types routine returns a list of the types of
ACLs protecting an object. For example, in addition to the regular
file system ACL, a file representing the stable storage of some
database could have an ACL manager that supported permissions
allowing database updates only on certain days of the week.
ACL editors and browsers can use this operation to determine the ACL
manager types that a particular reference monitor is using to protect
a selected entity. Using the rdacl_get_printstring routine, they can
determine how to format for display the permissions supported by a
specific manager.
Notes
This routine is not intended to be used by application programs. The
sec_acl Application Programming Interface (API) provides all the
routines necessary to use the ACL facility. This reference page is
provided for programmers who want to write an ACL manager. To write
an ACL manager, a programmer must implement the entire rdacl
interface.
This network interface is called on the client side by the sec_acl
local interface. Developers are responsible for implementing the
server side of this interface. Test server code is included as a
sample implementation.
File
\include\dce\rdaclif.idl The idl file that dce\rdaclif.h was derived
from.
Related Information
Routines:
rdacl_get_printstring
ΓòÉΓòÉΓòÉ 8.1.29. rdacl_get_mgr_types_semantics ΓòÉΓòÉΓòÉ
Purpose
Lists the ACL manager types protecting an object and the POSIX
semantics supported by each manager type.
Library
None. This network interface is called on the client side by the
sec_acl local interface. Developers are responsible for implementing
the server side of this interface. Test server code is included as a
sample implementation in the acl_mgr example program.
Format
#include <dce/rdaclif.h>
void rdacl_get_mgr_types_semantics(
handle_t h,
sec_acl_component_name_t component_name,
sec_acl_type_t sec_acl_type,
unsigned32 size_avail,
unsigned32 *size_used,
unsigned32 *num_types,
uuid_t manager_types[],
sec_acl_posix_semantics_t posix_semantics[]
error_status_t *status);
Parameters
Input
h A handle referring to the target object.
component_name A character string containing the name of the target
object.
sec_acl_type The ACL type used to limit the routine's output to ACL
managers that control the specified types of ACLs. The
possible values are as follows:
o sec_acl_type_object
o sec_acl_type_default_object
o sec_acl_type_default_container
size_avail An unsigned 32-bit integer containing the allocated
length of the manager_types and the posix_semantics
arrays.
Output
size_used An unsigned 32-bit integer containing the number of
output entries returned in the manager_types array.
num_types An unsigned 32-bit integer containing the number of
types returned in the manager_types array. This is
always equal to size_used.
manager_types An array of length size_avail containing the returned
UUIDs (of type uuid_t) identifying the different ACL
manager types protecting the target object.
posix_semantics An array of length size_avail containing the POSIX
semantics (of type sec_acl_posix_semantics_t that are
supported by each returned ACL manager type.
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns an error.
Usage
The rdacl_get_mgr_types_semantics routine returns a list of the ACL
manager types protecting an object and a list of the POSIX semantics
supported by those ACL manager types. Access to an object can be
controlled by multiple ACL manager types. For example, access to a
file representing the stable storage of a database can be controlled
by two ACL manager types each with completely different sets of
permissions: one to provide standard file system access (read, write,
run, and so forth) and one to provide access that allows database
updates only on certain days of the week.
ACL editors and browsers can use this operation to determine the ACL
manager types that a particular reference monitor is using to protect
a selected entity. Using the rdacl_get_printstring routine, they can
determine how to format for display the permissions supported by a
specific manager.
Notes
This routine is not intended to be used by application programs. The
sec_acl Application Programming Interface (API) provides all the
routines necessary to use the ACL facility. This section is provided
for programmers who want to write an ACL manager. To write an ACL
manager, a programmer must implement the entire rdacl interface.
This network interface is called on the client side by the sec_acl
local interface. Developers are responsible for implementing the
server side of this interface. Test server code is included as a
sample implementation.
File
\include\dce\rdaclif.idl The idl file that dce\rdaclif.h was derived
from.
Related Information
Routines:
rdacl_get_printstring
ΓòÉΓòÉΓòÉ 8.1.30. rdacl_get_printstring ΓòÉΓòÉΓòÉ
Purpose
Returns printable ACL strings.
Library
None. This network interface is called on the client side by the
sec_acl local interface. Developers are responsible for implementing
the server side of this interface. Test server code is included as a
sample implementation in the acl_mgr example program.
Format
#include <dce/rdaclif.h>
void rdacl_get_printstring(
handle_t h,
uuid_t *manager_type,
unsigned32 size_avail,
uuid_t *manager_type_chain,
sec_acl_printstring_t *manager_info,
boolean32 *tokenize,
unsigned32 *total_num_printstrings,
unsigned32 *size_used,
sec_acl_printstring_t printstrings[],
error_status_t *status);
Parameters
Input
h A handle referring to the target object. Use
sec_acl_bind to create this handle.
manager_type A pointer to the UUID identifying the type of the ACL
manager in question. There can be more than one type
of ACL manager protecting the object whose ACL is bound
to the input handle. Use this parameter to distinguish
them. Use rdacl_get_manager_types to acquire a list of
the manager types protecting a given object.
size_avail An unsigned 32-bit integer containing the allocated
length of the printstrings array.
Output
manager_type_chain If the target object ACL contains more than 32
permission bits, multiple manager types are used, one
for each 32-bit-wide slice of permissions. The UUID
returned in manager_type_chain refers to the next ACL
manager in the chain. If there are no more ACL
managers for this ACL, uuid_nil is returned.
manager_info Provides a name and help string for the given ACL
manager.
tokenize When FALSE, this parameter indicates that the returned
permission print strings are unambiguous and therefore
can be concatenated when printed without confusion.
When TRUE, however, this property does not hold, and
the strings need to be separated when printed or
passed.
total_num_printstrings An unsigned 32-bit integer containing the
total number of permission print strings supported by
this ACL manager type.
size_used An unsigned 32-bit integer containing the number of
permission entries returned in the printstrings array.
printstrings An array of permission print strings of type
sec_acl_printstring_t. Each entry of the array is a
structure containing three components:
printstring A character string of maximum
length sec_acl_printstring_len
containing the printable
representation of a specified
permission.
helpstring A character string of maximum
length
sec_acl_printstring_help_len
containing some text that can be
used to describe the specified
permission.
permissions A sec_acl_permset_t permission set
describing the permissions that
are be represented with the
companion print string.
The array consists of one entry
for each permission supported by
the ACL manager identified by
manager_type.
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns the following error:
sec_acl_unknown_manager_type The manager type
selected is not among those
referenced by the input
handle.
Usage
The rdacl_get_printstring routine returns an array of printable
representations (printstrings) for each permission bit or combination
of permission bits the specified ACL manager will support. The ACL
manager type specified must be one of the types indicated by the ACL
handle.
In addition to returning the print strings, this routine also returns
instructions about how to print the strings. When the tokenize
parameter is set to FALSE, a print string may be r or w, which could
be concatenated in the display as rw without any confusion. However,
when the tokenize parameter is TRUE, it implies the print strings may
be of a form such as read or write, which must be displayed separated
by spaces, colons, or some other character.
In any list of permission print strings, there may seem to be some
redundancy. ACL managers often define aliases for common permission
combinations. By convention, however, simple entries are placed at
the beginning of the printstrings array, and combinations are placed
at the end.
Notes
This routine is not intended to be used by application programs. The
sec_acl Application Programming Interface (API) provides all the
routines necessary to use the ACL facility. This reference page is
provided for programmers who want to write an ACL manager. To write
an ACL manager, a programmer must implement the entire rdacl
interface.
This network interface is called on the client side by the sec_acl
local interface. Developers are responsible for implementing the
server side of this interface. Test server code is included as a
sample implementation.
File
\include\dce\rdaclif.idl The idl file that dce\rdaclif.h was derived
from.
Related Information
Routines:
sec_acl_bind
rdacl_get_manager_types
ΓòÉΓòÉΓòÉ 8.1.31. rdacl_get_referral ΓòÉΓòÉΓòÉ
Purpose
Gets a referral to an ACL update site.
Library
None. This network interface is called on the client side by the
sec_acl local interface. Developers are responsible for implementing
the server side of this interface. Test server code is included as a
sample implementation in the acl_mgr example program.
Format
#include <dce/rdaclif.h>
void rdacl_get_referral(
handle_t h,
sec_acl_component_name_t component_name,
uuid_t *manager_type,
sec_acl_type_t sec_acl_type,
sec_acl_tower_set_t *towers,
error_status_t *status);
Parameters
Input
h A handle referring to the target object. Use
sec_acl_bind to create this handle.
component_name A character string containing the name of the target
object.
manager_type A pointer to the UUID identifying the type of the ACL
manager in question. There may be more than one type
of ACL manager protecting the object whose ACL is bound
to the input handle. Use this parameter to distinguish
them. Use sec_acl_get_manager_types to acquire a list
of the manager types protecting a given object.
sec_acl_type The ACL type. The sec_acl_type_t data type
distinguishes the various types of ACLs an object can
possess for a given manager type. Possible values are:
o sec_acl_type_object
o sec_acl_type_default_object
o sec_acl_type_default_container.
Output
towers A pointer to address information indicating an ACL
update site. This information, obtained from the RPC
runtime, is used by the client-side code to construct a
new ACL binding handle indicating a site that will not
return the sec_acl_site_readonly error.
The sec_acl_tower_set_t structure contains an array of
towers (called towers) and an unsigned 32-bit integer
indicating the number of array elements (called count).
This type enables the client to pass in an unallocated
array of towers and have the server allocate the
correct amount.
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns sec_acl_unknown_manager_type,
which indicates that the manager type selected is not
an available option.
Usage
The rdacl_get_referral routine obtains a referral to an ACL update
site. This routine is used when the current ACL site yields a
sec_acl_site_readonly error. Some replication managers require all
updates for a given object to be directed to a given replica. If
clients of the generic ACL interface know they are dealing with an
object that is replicated in this way, this routine allows them to
recover from the problem and rebind to the proper update site. The
DCE network registry, for example, is replicated this way.
Notes
This routine is not intended to be used by application programs. The
sec_acl Application Programming Interface (API) provides all the
functions necessary to use the ACL facility. This reference page is
provided for programmers who want to write an ACL manager. To write
an ACL manager, a programmer must implement the entire rdacl
interface.
This network interface is called on the client side by the sec_acl
local interface. Developers are responsible for implementing the
server side of this interface. Test server code is included as a
sample implementation.
File
\include\dce\rdaclif.idl The idl file that dce\rdaclif.h was derived
from.
Related Information
Routines:
sec_acl_bind
sec_acl_get_manager_types
ΓòÉΓòÉΓòÉ 8.1.32. rdacl_lookup ΓòÉΓòÉΓòÉ
Purpose
Returns the ACL for an object.
Library
None. This network interface is called on the client side by the
sec_acl local interface. Developers are responsible for implementing
the server side of this interface. Test server code is included as a
sample implementation in the acl_mgr example program.
Format
#include <dce/rdaclif.h>
void rdacl_lookup(
handle_t h,
sec_acl_component_name_t component_name,
uuid_t *manager_type,
sec_acl_type_t sec_acl_type,
sec_acl_result_t *result);
Parameters
Input
h A handle referring to the target object. Use
sec_acl_bind to create this handle.
component_name A character string containing the name of the target
object.
manager_type A pointer to the UUID identifying the type of the ACL
manager in question. There may be more than one type
of ACL manager protecting the object whose ACL is bound
to the input handle. Use this parameter to distinguish
them. Use sec_acl_get_manager_types to acquire a list
of the manager types protecting a given object.
sec_acl_type The ACL type. The sec_acl_type_t data type
distinguishes the various types of ACLs an object can
possess for a given manager type. Possible values are:
o sec_acl_type_object
o sec_acl_type_default_object
o sec_acl_type_default_container
Output
result A pointer to a tagged union of type sec_acl_result_t.
The tag is the completion status, result.st. If
result.st is equal to error_status_ok, the union
contains an ACL. Otherwise, the completion status
indicates an error, and the union is empty.
If the routine returned successfully, the
result.tagged_union.sec_acl_list_t structure contains a
sec_acl_list_t. This data type is an array of pointers
to sec_acl_ts that define ACLs. If the permission set
of the returned ACL is 32 bits or smaller,
sec_acl_list_t points to only one sec_acl_t. If the
permission set of the returned ACL is larger than 32
bits, multiple sec_acl_ts are used to hold them, and
the sec_acl_list_t points to multiple sec_acl_ts.
Usage
The rdacl_lookup routine loads into memory a copy of an object's ACL
corresponding to the specified manager type. The routine returns a
pointer to the ACL. This routine is only used by ACL editors and
browsers; an application would use sec_acl_test_access or
sec_acl_test_access_on_behalf to process the contents of an ACL.
Notes
This routine is not intended to be used by application programs. The
sec_acl Application Programming Interface (API) provides all the
functions necessary to use the ACL facility. This reference page is
provided for programmers who want to write an ACL manager. To write
an ACL manager, a programmer must implement the entire rdacl
interface.
This network interface is called on the client side by the sec_acl
local interface. Developers are responsible for implementing the
server side of this interface. Test server code is included as a
sample implementation.
File
\include\dce\rdaclif.idl The idl file that dce\rdaclif.h was derived
from.
Related Information
Routines:
sec_acl_bind
sec_acl_get_manager_types
sec_acl_test_access
sec_acl_test_access_on_behalf
ΓòÉΓòÉΓòÉ 8.1.33. rdacl_replace ΓòÉΓòÉΓòÉ
Purpose
Replaces an ACL.
Library
None. This network interface is called on the client side by the
sec_acl local interface. Developers are responsible for implementing
the server side of this interface. Test server code is included as a
sample implementation in the acl_mgr example program.
Format
#include <dce/rdaclif.h>
void rdacl_replace(
handle_t h,
sec_acl_component_name_t component_name,
uuid_t *manager_type,
sec_acl_type_t sec_acl_type,
sec_acl_list_t *sec_acl_list,
error_status_t *status);
Parameters
Input
h A handle referring to the target object. Use
sec_acl_bind to create this handle.
component_name A character string containing the name of the target
object.
manager_type A pointer to the UUID identifying the type of the ACL
manager in question. There can be more than one type
of ACL manager protecting the object whose ACL is bound
to the input handle. Use this parameter to distinguish
them. Use sec_acl_get_manager_types to acquire a list
of the manager types protecting a given object.
sec_acl_type The ACL type. The sec_acl_type_t data type
distinguishes the various types of ACLs an object can
possess for a given manager type. Possible values are:
o sec_acl_type_object
o sec_acl_type_default_object
o sec_acl_type_default_container
sec_acl_list The new ACL to use for the target object. This is
represented by a pointer to the sec_acl_list_t
structure containing the complete access control list.
An ACL contains a list of ACL entries, the UUID of the
default cell where authentication takes place (foreign
entries in the ACL contain the name of their parent
cell), and the UUID of the ACL manager to interpret the
list.
Output
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns sec_acl_unknown_manager_type,
which indicates that the manager type selected is not
an available option.
Usage
The rdacl_replace routine replaces the ACL indicated by the input
handle with the information in the sec_acl_list parameter. ACLs are
assumed to be immutable, but they can be modified if an editing
application reads an entire ACL (using sec_acl_lookup), modifies it
as needed, and replaces it using this routine.
Notes
The data type that stores an ACL has a limited size. Attempting to
add too many entries generates a sec_acl_cant_allocate_memory error.
This routine is not intended to be used by application programs. The
sec_acl Application Programming Interface (API) provides all the
functions necessary to use the ACL facility. This reference page is
provided for programmers who want to write an ACL manager. To write
an ACL manager, a programmer must implement the entire rdacl
interface.
This network interface is called on the client side by the sec_acl
local interface. Developers are responsible for implementing the
server side of this interface. Test server code is included as a
sample implementation.
File
\include\dce\rdaclif.idl The idl file that dce\rdaclif.h was derived
from.
Related Information
Routines:
sec_acl_bind
sec_acl_lookup
ΓòÉΓòÉΓòÉ 8.1.34. rdacl_test_access ΓòÉΓòÉΓòÉ
Purpose
Tests access to an object.
Library
None. This network interface is called on the client side by the
sec_acl local interface. Developers are responsible for implementing
the server side of this interface. Test server code is included as a
sample implementation in the acl_mgr example program.
Format
#include <dce/rdaclif.h>
boolean32 rdacl_test_access(
handle_t h,
sec_acl_component_name_t component_name,
uuid_t *manager_type,
sec_acl_permset_t desired_permset,
error_status_t *status);
Parameters
Input
h A handle referring to the target object. Use
sec_acl_bind to create this handle.
component_name A character string containing the name of the target
object.
manager_type A pointer to the UUID identifying the type of the ACL
manager in question. There may be more than one type
of ACL manager protecting the object whose ACL is bound
to the input handle. Use this parameter to distinguish
them. Use sec_acl_get_manager_types to acquire a list
of the manager types protecting a given object.
desired_permset A permission set in sec_acl_permset_t form containing
the desired privileges. This is a 32-bit set of
permission flags supported by the manager type.
Output
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns sec_acl_unknown_manager_type,
which indicates that the manager type selected is not
an available option.
Usage
The rdacl_test_access routine determines if the specified ACL
contains entries granting privileges to the calling process matching
those in desired_permset. An application generally only inquires
after the minimum set of privileges needed to accomplish a specific
task.
Notes
This routine is not intended to be used by application programs. The
sec_acl Application Programming Interface (API) provides all the
functions necessary to use the ACL facility. This reference page is
provided for programmers who want to write an ACL manager. To write
an ACL manager, a programmer must implement the entire rdacl
interface.
This network interface is called on the client side by the sec_acl
local interface. Developers are responsible for implementing the
server side of this interface. Test server code is included as a
sample implementation.
File
\include\dce\rdaclif.idl The idl file that dce\rdaclif.h was derived
from.
Related Information
Routines:
sec_acl_bind
sec_acl_get_manager_types
rdacl_test_access_on_behalf
ΓòÉΓòÉΓòÉ 8.1.35. rdacl_test_access_on_behalf ΓòÉΓòÉΓòÉ
Purpose
Tests access to an object on behalf of another process.
Library
None. This network interface is called on the client side by the
sec_acl local interface. Developers are responsible for implementing
the server side of this interface. Test server code is included as a
sample implementation in the acl_mgr example program.
Format
#include <dce/rdaclif.h>
boolean rdacl_test_access_on_behalf(
handle_t h,
sec_acl_component_name_t component_name,
uuid_t *manager_type,
sec_id_pac_t *subject,
sec_acl_permset_t desired_permset,
error_status_t *status);
Parameters
Input
h A handle referring to the target object. Use
sec_acl_bind to create this handle.
component_name A character string containing the name of the target
object.
manager_type A pointer to the UUID identifying the type of the ACL
manager in question. There may be more than one type
of ACL manager protecting the object whose ACL is bound
to the input handle. Use this parameter to distinguish
them. Use sec_acl_get_manager_types to acquire a list
of the manager types protecting a given object.
subject A privilege attribute certificate (PAC) for the subject
process. The PAC contains the name and UUID of the
principal and parent cell of the subject process, as
well as a list of any groups to which it belongs. The
PAC also contains a flag (named authenticated). When
set it indicates that the certificate was obtained from
an authenticated source. When not set, the certificate
must not be trusted. (The field is FALSE when it was
obtained from the rpc_auth layer and the protect level
was set to rpc_c_protect_level_none. This indicates
that no authentication protocol was actually used in
the remote procedure call; the identity was simply
transmitted from the caller to the receiver. If an
authentication protocol was used, then the flag is set
to TRUE.) A server uses rpc_binding_inq_auth_client to
acquire a certificate for the client process.
desired_permset A permission set in sec_acl_permset_t form containing
the desired privileges. This is a 32-bit set of
permission flags supported by the manager type.
Output
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns sec_acl_unknown_manager_type,
which indicates that the manager type selected is not
an available option.
Usage
The rdacl_test_access_on_behalf routine determines if the specified
ACL contains entries granting privileges to the subject, a process
besides the calling process, matching those in desired_permset. This
routine succeeds only if the access is available to both the caller
process as well as the subject identified in the call. An
application will generally only inquire after the minimum set of
privileges needed to accomplish a specific task.
Notes
This routine is not intended to be used by application programs. The
sec_acl Application Programming Interface (API) provides all the
functions necessary to use the ACL facility. This reference page is
provided for programmers who want to write an ACL manager. To write
an ACL manager, a programmer must implement the entire rdacl
interface.
This network interface is called on the client side by the sec_acl
local interface. Developers are responsible for implementing the
server side of this interface. Test server code is included as a
sample implementation.
File
\include\dce\rdaclif.idl The idl file that dce\rdaclif.h was derived
from.
Related Information
Routines:
rdacl_test_access
rpc_binding_inq_auth_client
sec_acl_bind
sec_acl_get_manager_types
ΓòÉΓòÉΓòÉ 8.2. DCE Extended Privilege Attribute API ΓòÉΓòÉΓòÉ
This section describes the Extended Privilege Attribute (EPA) API. The EPA
facility addresses the requirements of complex distributed systems by allowing
clients and servers to run secure operations using one or more intermediate
servers.
To handle these cases, the EPA API provides routines that allow principals to
operate on objects on behalf of (as delegates of) an initiating principal. The
collection of the delegation initiator and the intermediaries is referred to as
a delegation chain.
The EPA interface consists of the Security credential routines (with the prefix
sec_cred_) that extract privilege attributes and authorization data from an
opaque binding handle to authenticated credentials. In addition, several of
the sec_login_xxx routines from the Login API are used to establish delegation
chains and to perform other delegation-related functions. See DCE Login API for
more information on the Login API.
The EPA API sec_cred and Login API sec_login_cred routines extract privilege
attribute information. These routines return information associated with an
opaque handle to an authenticated identity.
See the following subtopics for more information:
Format
Data Types
Constants
Extended Privilege Attribute Routines
Files
ΓòÉΓòÉΓòÉ 8.2.1. Extended Privilege Attribute Routines ΓòÉΓòÉΓòÉ
The sec_cred routines are used by servers that have been called by a client
with authenticated credentials. The routines are as follows:
o sec_cred_free_attr_cursor
o sec_cred_free_cursor
o sec_cred_free_pa_handle
o sec_cred_get_authz_session_info
o sec_cred_get_client_princ_name
o sec_cred_get_deleg_restrictions
o sec_cred_get_delegate
o sec_cred_get_delegation_type
o sec_cred_get_extended_attrs
o sec_cred_get_initiator
o sec_cred_get_opt_restrictions
o sec_cred_get_pa_data
o sec_cred_get_req_restrictions
o sec_cred_get_tgt_restrictions
o sec_cred_get_v1_pac
o sec_cred_initialize_attr_cursor
o sec_cred_initialize_cursor
o sec_cred_inq_auth_service_info
o sec_cred_is_authenticated
The sec_login_cred routines are used by clients that are part of a delegation
chain.
ΓòÉΓòÉΓòÉ 8.2.2. Format ΓòÉΓòÉΓòÉ
#include <dce/id_epac.h>
#include <dce/nbase.h>
ΓòÉΓòÉΓòÉ 8.2.3. Data Types ΓòÉΓòÉΓòÉ
The following data types are used in Extended Privilege Attribute routines and
in the sec_login_cred routines that implement extended privilege attributes.
sec_cred_cursor_t A structure that provides an input/output cursor used to
iterate through a set of delegates in the sec_cred_get_delegate or
sec_login_cred_get_delegate routines. This cursor is initialized by
the sec_cred_initialize_cursor or sec_login_cred_init_cursor
routine.
sec_cred_attr_cursor_t A structure that provides an input/output cursor used
to iterate through a set of extended attributes in the
sec_cred_get_extended_attributes routine. This cursor is initialized
by the sec_cred_initialize_attr_cursor routine.
sec_id_opt_req_t A structure that specifies application-defined optional
restrictions. The sec_id_opt_req_t data type is composed of the
following elements:
restriction_len An unsigned 16-bit integer that defines the
size of the restriction data.
restrictions A pointer to a idl_byte that contains the
restriction data.
sec_rstr_entry_type_t An enumerator that specifies the entry types for
delegate and target restrictions. This data type is used in
conjunction with the sec_id_restriction_t data type where the
specific UUIDs, if appropriate, are supplied. It consists of the
following components:
sec_rstr_e_type_user The target is a local principal identified
by UUID. This type conforms with the POSIX 1003.6
standard.
sec_rstr_e_type_group The target is a local group identified by
UUID. This type conforms with the POSIX 1003.6
standard.
sec_rstr_e_type_foreign_user The target is a foreign principal
identified by principal and cell UUID.
sec_rstr_e_type_foreign_group The target is a foreign group
identified by group and cell UUID.
sec_rstr_e_type_foreign_other The target is any principal that
can authenticate to the foreign cell identified by
UUID.
sec_rstr_e_type_any_other The target is any principal that can
authenticate to any cell, but is not identified in
any other type entry.
sec_rstr_e_type_no_other No principal can act as a target or
delegate.
sec_id_restriction_t A discriminated union that defines delegate and target
restrictions. The union, which is used in conjunction with the
sec_restriction_set_t data type, consists of the following elements:
entry_info A structure containing two members:
entry_type A sec_rstr_entry_type_t containing
one of the enumerated values listed
for that type that defines the ACL
entry types for delegate and target
restrictions. The value of
tagged_union depends on the value of
entry_type.
tagged_union A tagged union whose contents
depend on entry_type as follows:
If entry_type is...
Tagged_union
is...
sec_rstr_e_type_any_other An
id
of
type
sec_id_t.
sec_rstr_e_type_foreign_other A
foreign_id
that
identifies
the
foreign
cell.
sec_rstr_e_type_user An
id,
a
sec_id_t
that
identifies
the
user.
sec_rstr_e_type_group An
id,
a
sec_id_t
that
identifies
the
group.
sec_rstr_e_type_foreign_user A
foreign_id,
a
sec_id_foreign_t
that
identifies
the
foreign
user.
sec_rstr_e_type_foreign_group A
foreign_id,
a
sec_id_foreign_t
that
identifies
the
foreign
group.
sec_id_restriction_set_t A structure that supplies delegate and target
restrictions. The structure consists of:
num_restrictions A 16-bit unsigned integer that defines the
number of restrictions in restrictions.
restrictions An array containing num_restrictions pointers to
restrictions, each of type sec_id_restriction_t.
sec_id_compatibility_mode_t A unsigned 16-bit integer that defines the
compatibility between current and pre-1.1 servers. The data type
uses the following constants:
sec_id_compat_mode_none Compatibility mode is off.
sec_id_compat_mode_initiator Compatibility mode is on. The 1.0
PAC data is extracted from the EPAC of the chain
initiator.
sec_id_compat_mode_caller Compatibility mode is on. The 1.0 PAC
data is extracted from the last delegate in the
delegation chain.
sec_id_delegation_type_t An unsigned 16-bit integer that defines the
delegation type. The data type uses the following constants:
sec_id_deleg_type_none Delegation is not allowed.
sec_id_deleg_type_traced Traced delegation is allowed.
sec_id_deleg_type_impersonation Simple (impersonation)
delegation is allowed.
sec_id_pa_t A structure that contains pre-1.1 PAC data extracted from an EPAC
of a current version server. This data type, which is used for
compatibility with pre-1.1 servers, consists of the following
elements:
realm A value of type sec_id_t that contains the UUID that
identifies the cell in which the principal associated
with the PAC exists.
principal A value of type sec_id_t that contains the UUID of
the principal.
group A value of type sec_id_t that contains the UUID of
the principal's primary group.
num_groups An unsigned 16-bit integer that specifies the number
of groups in the principal's group set.
groups An array of pointers to sec_id_t structures that
contain the UUIDs of each group in the principal's
group set.
num_foreign_groupsets An unsigned 16-bit integer that specifies
the number of foreign groups for the principal's
group set.
foreign_groupsets An array of pointers to sec_id_t structures
that contain the UUIDs of each group in the
principal's group set.
sec_id_pac_t A structure that contains a pre-1.1 PAC. This data type, which is
used as output for the sec_cred_get_v1_pac routine, consists of the
following elements:
pac_type A value of type sec_id_pac_format_t that can be used
to describe the PAC format.
authenticated A boolean field that indicates whether the PAC is
authenticated (obtained from an authenticated
source). FALSE indicates that the PAC is not
authenticated. No authentication protocol was used in
the RPC that transmitted the identity of the caller.
TRUE indicates that the PAC is authenticated.
realm A value of type sec_id_t that contains the UUID that
identifies the cell in which the principal associated
with the PAC exists.
principal A value of type sec_id_t that contains the UUID of
the principal.
group For local principals, a value of type sec_id_t that
contains the UUID of the principal's primary group.
num_groups An unsigned 16-bit integer that specifies the number
of groups in the principal's group set.
groups An array of pointers to sec_id_t structures that
contain the UUIDs of each group in the principal's
group set.
num_foreign_groups An unsigned 16-bit integer that specifies
the number of foreign groups for the principal's
group set.
foreign_groups An array of pointers to sec_id_t structures that
contain the UUIDs of each foreign group in the
principal's group set.
sec_id_pac_format_t An enumerator that can be used to describe the PAC format.
sec_id_t A structure that contains UUIDs for principals, groups, or
organizations and an optional print string name. Because a UUID is a
handle for the object's identity, the sec_id_t data type is the
basic unit for identifying principals, groups, and organizations.
Because the print string name is dynamically allocated, this data
type requires a freeing routine. Generally, however, the sec_id_t is
embedded in other data types (ACLs, for example), and these data
types have a freeing routine to release the print string storage.
The sec_id_t data type is composed of the following elements:
uuid A value of type uuid_t, the UUID of the principal,
group, or organization.
name A pointer to a character string containing the name
of the principal, group, or organization.
sec_id_foreign_t A structure that contains UUIDs for principals, groups, or
organizations for objects in a foreign cell and the UUID that
identifies the foreign cell. The sec_id_foreign_t data type is
composed of the following elements:
id A value of type sec_id_t that contains the UUIDs of
the objects from the foreign cell.
realm A value of type sec_id_t that contains the UUID of
the foreign cell.
sec_id_foreign_groupset_t A structure that contains UUIDs for a set of groups
in a foreign cell and the UUID that identifies the foreign cell. The
sec_id_foreign_groupset_t data type is composed of the following
elements:
realm A value of type sec_id_t that contains the UUID of
the foreign cell.
num_groups An unsigned 16-bit integer specifying the number of
group UUIDs in groups.
groups A pointer to a sec_id_t that contains the UUIDs of
the group set from the foreign cell.
ΓòÉΓòÉΓòÉ 8.2.4. Constants ΓòÉΓòÉΓòÉ
The following constants are used in the EPA routines and in the sec_login
routines that implement extended privilege attributes:
sec_id_compat_mode_none Compatibility mode is off.
sec_id_compat_mode_initiator Compatibility mode is on. The 1.0 PAC data
extracted from the EPAC of the chain initiator.
sec_id_compat_mode_caller Compatibility mode is on. The 1.0 PAC data extracted
from the last delegate in the delegation chain.
sec_id_deleg_type_none Delegation is not allowed.
sec_id_deleg_type_traced Traced delegation is allowed.
sec_id_deleg_type_impersonation Simple (impersonation) delegation is allowed.
sec_rstr_e_type_user The delegation target is a local principal identified by
UUID. This type conforms with the POSIX 1003.6 standard.
sec_rstr_e_type_group The delegation target is a local group identified by
UUID. This type conforms with the POSIX 1003.6 standard.
sec_rstr_e_type_foreign_user The delegation target is a foreign principal
identified by principal and cell UUID.
sec_rstr_e_type_foreign_group The delegation target is a foreign group
identified by group and cell UUID.
sec_rstr_e_type_foreign_other The delegation target is any principal that can
authenticate to the foreign cell identified by UUID.
sec_rstr_e_type_any_other The delegation target is any principal that can
authenticate to any cell, but is not identified in any other type
entry.
sec_rstr_e_type_no_other No principal can act as a target or delegate.
ΓòÉΓòÉΓòÉ 8.2.5. Files ΓòÉΓòÉΓòÉ
\usr\include\dce\sec_cred.idl The idl file from which sec_cred.h was derived.
\usr\include\dce\sec_epac.idl The idl file from which sec_epac.h was derived.
\usr\include\dce\sec_nbase.idl The idl file from which sec_nbase.h was
derived.
ΓòÉΓòÉΓòÉ 8.2.6. sec_cred_free_attr_cursor ΓòÉΓòÉΓòÉ
Purpose
Frees the local resources allocated to a sec_attr_cursor_t used by
the sec_cred_get_extended_attrs routine.
Format
#include <dce/sec_cred.h>
void sec_cred_free_attr_cursor (
sec_cred_attr_cursor_t *cursor,
error_status_t *status);
Parameters
Input/Output
cursor As input, a pointer to a sec_cred_attr_cursor_t whose
resources are to be freed. As output, a pointer to an
initialized sec_cred_attr_cursor_t with allocated
resources freed.
Output
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns an error.
Usage
The sec_cred_free_attr_cursor routine frees the resources associated
with a cursor of type sec_cred_attr_cursor_t used by the
sec_cred_get_extended_attrs routine.
Related Information
Routines:
sec_cred_get_extended_attrs
sec_cred_initialize_cursor
ΓòÉΓòÉΓòÉ 8.2.7. sec_cred_free_cursor ΓòÉΓòÉΓòÉ
Purpose
Releases local resources allocated to a sec_cred_cursor_t used by the
sec_cred_get_delegate routine.
Format
#include <dce/sec_cred.h>
void sec_cred_free_cursor (
sec_cred_cursor_t *cursor,
error_status_t *status);
Parameters
Input/Output
cursor As input, a sec_cred_cursor_t whose resources are to be
freed. As output, a sec_cred_cursor_t whose resources
are freed.
Output
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns sec_login_s_no_memory.
Usage
The sec_cred_free_cursor routine releases local resources allocated
to a sec_cred_cursor_t used by the sec_cred_get_delegate routine.
Related Information
Routines:
sec_cred_get_delegate
sec_cred_initialize_cursor
ΓòÉΓòÉΓòÉ 8.2.8. sec_cred_free_pa_handle ΓòÉΓòÉΓòÉ
Purpose
Frees the local resources allocated to a privilege attribute handle
of type sec_cred_pa_handle_t used by the sec_cred_get_initiator and
sec_cred_get_delegate routines.
Format
#include <dce/sec_cred.h>
void sec_cred_free_pa_handle (
sec_cred_pa_handle_t *pa_handle,
error_status_t *status);
Parameters
Input/Output
pa_handle As input, a pointer to a sec_cred_pa_handle_t whose
resources are to be freed. As output a pointer to a
sec_cred_pa_handle_t with allocated resources freed.
Output
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns an error.
Usage
The sec_cred_free_pa_handle routine frees the resources associated
with a privilege attribute handle of type sec_cred_pa_handle_t used
by the sec_cred_get_initiator and sec_cred_get_delegate routines.
Related Information
Routines:
sec_cred_get_delegate
sec_cred_get_initiator
ΓòÉΓòÉΓòÉ 8.2.9. sec_cred_get_authz_session_info ΓòÉΓòÉΓòÉ
Purpose
Returns session-specific information that represents an authenticated
client's credentials.
Format
#include <dce/sec_cred.h>
void sec_cred_get_authz_session_info(
rpc_authz_cred_handle_t callers_identity,
uuid_t *session_id,
sec_timeval_t *session_expiration,
error_status_t *status );
Parameters
Input
callers_identity A credential handle of type rpc_authz_cred_handle_t.
This handle is supplied as output of the
rpc_binding_inq_auth_caller routine.
Output
session_ID A pointer to a uuid_t that identifies the client's DCE
authorization session.
session_expiration A pointer to a sec_timeval_t that specifies the
expiration time of the authenticated client's
credentials.
status A pointer to the completion status. On successful
completion, status is assigned error_status_ok.
Otherwise, it returns sec_cred_s_authz_cannot_comply.
Usage
The sec_cred_get_authz_session_info routine retrieves
session-specific information that represents the credentials of an
authenticated client specified by callers_identity. If the client is
a member of a delegation chain, the information represents the
credentials of all members of the chain.
The information can aid application servers in the construction of
identity-based caches. For example, it could be used as a key into a
cache of previously allocated delegation contexts and thus avoid the
overhead of allocating a new login context on every remote operation.
It could also be used as a key into a table of previously computed
authorization decisions.
Before you run this routine, you must run the
rpc_binding_inq_auth_caller routine to obtain an
rpc_authz_cred_handle_t for the callers_identity parameter.
Related Information
Routines:
rpc_binding_inq_auth_caller
ΓòÉΓòÉΓòÉ 8.2.10. sec_cred_get_client_princ_name ΓòÉΓòÉΓòÉ
Purpose
Returns the principal name associated with a credential handle.
Format
#include <dce/sec_cred.h>
void sec_cred_get_client_princ_name(
rpc_authz_cred_handle_t callers_identity,
unsigned_char_p_t *client_princ_name,
error_status_t *status);
Parameters
Input
callers_identity A handle of type rpc_authz_cred_handle_t to the
credentials for which to return the principal name.
This handle is supplied as output of the
rpc_binding_inq_auth_caller routine.
Output
client_princ_name A pointer to the principal name of the server's RPC
client.
status A pointer to the completion status. On successful
completion, status is assigned error_status_ok.
Otherwise, it returns sec_cred_s_authz_cannot_comply.
Usage
The sec_cred_get_client_princ_name routine extracts the principal
name associated with the credentials identified by callers_identity.
This routine can only be called for a non-standard form of
authorization that is based on the client principal name.
To use this routine, call the rpc_binding_set_auth_info routine and
specify rpc_c_authz_name for the authorization service (the authz_svc
parameter). The server receives no PAC or EPAC as part of the RPC, so
the server does not use a standard authorization. You must then get a
handle by using the rpc_binding_inq_auth_caller routine. Use the
rpc_authz_cred_handle_t returned in the privs parameter of that
routine as the input for the callers_identity parameter in
sec_cred_get_client_princ_name.
Related Information
Routines:
rpc_binding_inq_auth_caller
ΓòÉΓòÉΓòÉ 8.2.11. sec_cred_get_deleg_restrictions ΓòÉΓòÉΓòÉ
Purpose
Returns delegate restrictions from a privilege attribute handle.
Format
#include <dce/sec_cred.h>
sec_id_restriction_set_t *sec_cred_get_deleg_restrictions(
sec_cred_pa_handle_t callers_pas,
error_status_t *status);
Parameters
Input
callers_pas A value of type sec_cred_pa_handle_t that provides a
handle to a principal's privilege attributes. This
handle is supplied as output of the
sec_cred_get_initiator routine, the
sec_cred_get_delegate routine, and the
sec_login_cred_xxx routines.
Output
status A pointer to the completion status. On successful
completion, status is assigned error_status_ok.
Otherwise, it returns sec_cred_s_invalid_pa_handle.
Usage
The sec_cred_get_deleg_restrictions routine extracts delegate
restrictions from the privilege attribute handle identified by
callers_pas. The restrictions are returned in a
sec_id_restriction_set_t.
Before you run sec_cred_get_pa_data, you must run the
sec_cred_get_initiator or sec_cred_get_delegate routine to obtain a
sec_cred_pa_handle_t for the callers_pas parameter.
Related Information
Routines:
sec_cred_get_delegate
sec_cred_get_initiator
ΓòÉΓòÉΓòÉ 8.2.12. sec_cred_get_delegate ΓòÉΓòÉΓòÉ
Purpose
Returns a handle to the privilege attributes of an intermediary in a
delegation chain.
Format
#include <dce/sec_cred.h>
sec_cred_pa_handle_t sec_cred_get_delegate(
rpc_authz_cred_handle_t callers_identity,
sec_cred_cursor_t *cursor,
error_status_t *status);
Parameters
Input
callers_identity A handle of type rpc_authz_cred_handle_t. This
handle is supplied as output of the
rpc_binding_inq_auth_caller routine.
Input/Output
cursor As input, a pointer to a cursor of type
sec_cred_cursor_t that has been initialized by the
sec_cred_initialize_cursor routine. As an output
parameter, cursor is a pointer to a cursor of type
sec_attr_srch_cursor_t that is positioned past the
principal whose privilege attributes have been returned
in this routine.
Output
status A pointer to the completion status. On successful
completion, status is assigned error_status_ok.
Otherwise, it returns one of the following errors:
sec_cred_s_invalid_auth_handle
sec_cred_s_invalid_cursor
sec_cred_s_no_more_entries
Usage
The sec_cred_get_delegate routine returns a handle to the privilege
attributes of an intermediary in a delegation chain that performed an
authenticated RPC operation.
This routine is used by servers. Clients use the
sec_login_cred_get_delegate routine to return the privilege attribute
handle of an intermediary in a delegation chain.
The credential handle identified by callers_identity contains
authentication and authorization information for all delegates in the
chain. This routine returns a handle (sec_cred_pa_handle_t) to the
privilege attributes of one of the delegates in the binding handle.
The sec_cred_pa_handle_t returned by this routine is used in other
sec_cred_get_xxx routines to obtain privilege attribute information
for a single delegate.
To obtain the privilege attributes of each delegate in the credential
handle identified by callers_identity, run this routine until the
message sec_cred_s_no_more_entries is returned.
Before you run sec_cred_get_delegate, you must run:
o The rpc_binding_inq_auth_caller routine to obtain an
rpc_authz_cred_handle_t for the callers_identity parameter
o The sec_cred_initialize_cursor routine to initialize a cursor of
type sec_cred_cursor_t
Use the sec_cred_free_pa_handle routine to free the resources
associated with the sec_cred_pa_handle_t.
Related Information
Routines:
rpc_binding_inq_auth_caller
sec_cred_free_pa_handle
sec_cred_initialize_cursor
sec_cred_get_deleg_restrictions
sec_cred_get_delegation_type
sec_cred_get_extended_attrs
sec_cred_get_opt_restrictions
sec_cred_get_pa_data
sec_cred_get_req_restrictions
sec_cred_get_tgt_restrictions
sec_cred_get_v1_pac
ΓòÉΓòÉΓòÉ 8.2.13. sec_cred_get_delegation_type ΓòÉΓòÉΓòÉ
Purpose
Returns the delegation type from a privilege attribute handle.
Format
#include <dce/sec_cred.h>
sec_id_delegation_type_t *sec_cred_get_delegation_type(
sec_cred_pa_handle_t callers_pas,
error_status_t *status);
Parameters
Input
callers_pas A value of type sec_cred_pa_handle_t that provides a
handle to a principal's privilege attributes. This
handle is supplied as output of either the
sec_cred_get_initiator routine or sec_cred_get_delegate
routine.
Output
status A pointer to the completion status. On successful
completion, status is assigned error_status_ok.
Otherwise, it returns sec_cred_s_invalid_pa_handle.
Usage
The sec_cred_get_delegation_type routine extracts the delegation type
from the privilege attribute handle identified by callers_pas and
returns it in a sec_id_delegation_type_t.
Before you run sec_cred_get_delegation_type, you must run the
sec_cred_get_initiator or sec_cred_get_delegate routine to obtain a
sec_cred_pa_handle_t for the callers_pas parameter.
Related Information
Routines:
sec_cred_get_delegate
sec_cred_get_initiator
ΓòÉΓòÉΓòÉ 8.2.14. sec_cred_get_extended_attrs ΓòÉΓòÉΓòÉ
Purpose
Returns extended attributes from a privilege handle.
Format
#include <dce/sec_cred.h>
void sec_cred_get_extended_attrs(
sec_cred_pa_handle_t callers_pas,
sec_cred_attr_cursor_t *cursor
sec_attr_t *attr
error_status_t *status);
Parameters
Input
callers_pas A handle of type sec_cred_pa_handle_t to the caller's
privilege attributes. This handle is supplied as output
of either the sec_cred_get_initiator or the
sec_cred_get_delegate routine.
Input/Output
cursor A cursor of type sec_cred_attr_cursor_t that has been
initialized by the sec_cred_initialize_attr_cursor
routine. As input, cursor must be initialized. As
output, cursor is positioned at the first attribute
after the returned attribute.
Output
attr A pointer to a value of sec_attr_t type that contains
extended registry attributes.
status A pointer to the completion status. On successful
completion, status is assigned error_status_ok.
Otherwise, it returns one of the following errors:
sec_cred_s_invalid_pa_handle
sec_cred_s_invalid_cursor
sec_cred_s_no_more_entries
Usage
The sec_cred_get_extended_attrs routine extracts extended registry
initialized from the privilege attribute handle identified by
callers_pas.
Before you run the sec_cred_get_extended_attrs routine, you must run:
o The sec_cred_get_initiator or sec_cred_get_delegate routine to
obtain a sec_cred_pa_handle_t for the callers_pas parameter
o The sec_cred_initialize_attr_cursor routine to initialize attr
To obtain all the extended registry attributes in the privilege
attribute handle, repeat the sec_cred_get_extended_attrs routine
until the status message sec_cred_s_no_more_entries is returned.
Related Information
Routines:
sec_cred_get_delegate
sec_cred_get_initiator
sec_cred_initialize_attr_cursor
ΓòÉΓòÉΓòÉ 8.2.15. sec_cred_get_initiator ΓòÉΓòÉΓòÉ
Purpose
Returns the privilege attributes of the initiator of a delegation
chain.
Format
#include <dce/sec_cred.h>
sec_cred_pa_handle_t sec_cred_get_initiator(
rpc_authz_cred_handle_t callers_identity,
error_status_t *status);
Parameters
Input
callers_identity A credential handle of type rpc_authz_cred_handle_t.
This handle is supplied as output of the
rpc_binding_inq_auth_caller routine.
Output
status A pointer to the completion status. On successful
completion, status is assigned error_status_ok.
Otherwise, it returns sec_cred_s_invalid_auth_handle.
Usage
The sec_cred_get_initiator routine returns a handle to the privilege
attributes of the initiator of a delegation chain that performed an
authenticated RPC operation.
The credential handle identified by callers_identity contains
authentication and authorization information for all delegates in the
chain. This routine returns a handle (sec_cred_pa_handle_t) to the
privilege attributes of the client that initiated the delegation
chain. The sec_cred_pa_handle_t returned by this routine is used in
other sec_cred_get_xxx routines to obtain privilege attribute
information for the initiator.
Before you run sec_cred_get_initiator, you must run the
rpc_binding_inq_auth_caller routine to obtain an
rpc_authz_cred_handle_t for the callers_identity parameter.
Related Information
Routines:
rpc_binding_inq_auth_caller
sec_cred_free_pa_handle
sec_cred_initialize_cursor
sec_cred_get_deleg_restrictions
sec_cred_get_delegation_type
sec_cred_get_extended_attrs
sec_cred_get_opt_restrictions
sec_cred_get_pa_data
sec_cred_get_req_restrictions
sec_cred_get_tgt_restrictions
sec_cred_get_v1_pac
ΓòÉΓòÉΓòÉ 8.2.16. sec_cred_get_opt_restrictions ΓòÉΓòÉΓòÉ
Purpose
Returns optional restrictions from a privilege handle.
Format
#include <dce/sec_cred.h>
sec_id_opt_req_t *sec_cred_get_opt_restrictions
sec_cred_pa_handle_t callers_pas,
error_status_t *status);
Parameters
Input
callers_pas A handle of type sec_cred_pa_handle_t to a principal's
privilege attributes. This handle is supplied as output
of either the sec_cred_get_initiator routine or the
sec_cred_get_delegate routine.
Output
status A pointer to the completion status. On successful
completion, status is assigned error_status_ok.
Otherwise, it returns the following error:
sec_cred_s_invalid_pa_handle
Usage
The sec_cred_get_opt_restrictions routine extracts optional
restrictions from the privilege attribute handle identified by
callers_pas and returns them in a sec_id_restriction_set_t.
Before you run sec_cred_get_pa_data, you must run the
sec_cred_get_initiator or sec_cred_get_delegate routine to obtain a
sec_cred_pa_handle_t for the callers_pas parameter.
Related Information
Routines:
sec_cred_get_delegate
sec_cred_get_initiator
ΓòÉΓòÉΓòÉ 8.2.17. sec_cred_get_pa_data ΓòÉΓòÉΓòÉ
Purpose
Returns identity information from a privilege attribute handle.
Format
#include <dce/sec_cred.h>
sec_id_pa_t *sec_cred_get_pa_data(
sec_cred_pa_handle_t callers_pas,
error_status_t *status);
Parameters
Input
callers_pas A handle of type sec_cred_pa_handle_t to a principal's
privilege attributes. This handle is supplied as output
of either the sec_cred_get_initiator routine or the
sec_cred_get_delegate routine.
Output
status A pointer to the completion status. On successful
completion, status is assigned error_status_ok.
Otherwise, it returns sec_cred_s_invalid_pa_handle.
Usage
The sec_cred_get_pa_data routine extracts identity information from
the privilege attribute handle specified by callers_pas and returns
it in a sec_id_pa_t. The identity information includes an identifier
of the principal's local cell and the principal's local and foreign
group sets.
Before you run sec_cred_get_pa_data, you must run a
sec_cred_get_initiator or sec_cred_get_delegate routine to obtain a
sec_cred_pa_handle_t for the callers_pas parameter.
Related Information
Note that, for this release, only the uuid field of the sec_id_t
structures pointed to by the realm, principal, and group attributes
of the sec_id_pa_t structure is set. To get the name of any of these
three items, you must use the sec_rgy_pgo_id_to_name routine.
Routines:
sec_cred_get_delegate
sec_cred_get_initiator
ΓòÉΓòÉΓòÉ 8.2.18. sec_cred_get_req_restrictions ΓòÉΓòÉΓòÉ
Purpose
Returns required restrictions from a privilege attribute handle.
Format
#include <dce/sec_cred.h>
sec_id_opt_req_t *sec_cred_get_req_restrictions(
sec_cred_pa_handle_t callers_pas,
error_status_t *status);
Parameters
Input
callers_pas A handle of type sec_cred_pa_handle_t to a principal's
privilege attributes. This handle is supplied as output
of either the sec_cred_get_initiator routine or
sec_cred_get_delegate routine.
Output
status A pointer to the completion status. On successful
completion, status is assigned error_status_ok.
Otherwise, it returns sec_cred_s_invalid_pa_handle.
Usage
The sec_cred_get_req_restrictions routine extracts required
restrictions from the privilege attribute handle identified by
callers_pas and returns them in a sec_id_opt_req_t.
Before you run sec_cred_get_req_restrictions, you must run the
sec_cred_get_initiator or sec_cred_get_delegate routine to obtain a
sec_cred_pa_handle_t for the callers_pas parameter.
Related Information
Routines:
sec_cred_get_delegate
sec_cred_get_initiator
ΓòÉΓòÉΓòÉ 8.2.19. sec_cred_get_tgt_restrictions ΓòÉΓòÉΓòÉ
Purpose
Returns target restrictions from a privilege attribute handle.
Format
#include <dce/sec_cred.h>
sec_id_restriction_set_t *sec_cred_get_tgt_restrictions(
sec_cred_pa_handle_t callers_pas,
error_status_t *status);
Parameters
Input
callers_pas A handle of type sec_cred_pa_handle_t to a principal's
privilege attributes. This handle is supplied as output
of either the sec_cred_get_initiator routine or the
sec_cred_get_delegate routine.
Output
status A pointer to the completion status. On successful
completion, status is assigned error_status_ok.
Otherwise, it returns sec_cred_s_invalid_pa_handle.
Usage
The sec_cred_get_tgt_restrictions routine extracts target
restrictions from the privilege attribute handle identified by
callers_pas and returns them in a sec_id_restriction_set_t.
Before you run sec_cred_get_tgt_restrictions, you must run the
sec_cred_get_initiator or sec_cred_get_delegate routine to obtain a
sec_cred_pa_handle_t for the callers_pas parameter.
Related Information
Routines:
sec_cred_get_delegate
sec_cred_get_initiator
ΓòÉΓòÉΓòÉ 8.2.20. sec_cred_get_v1_pac ΓòÉΓòÉΓòÉ
Purpose
Returns pre-1.1 PAC privilege attributes from a privilege attribute
handle.
Format
#include <dce/sec_cred.h>
sec_id_pac_t *sec_cred_get_v1_pac(
sec_cred_pa_handle_t callers_pas,
error_status_t *status);
Parameters
Input
callers_pas A handle of type sec_cred_pa_handle_t to the
principal's privilege attributes. This handle is
supplied as output of either the sec_cred_get_initiator
routine or the sec_cred_get_delegate routine.
Output
status A pointer to the completion status. On successful
completion, status is assigned error_status_ok.
Usage
The sec_cred_get_v1_pac routine extracts the privilege attributes
from a pre-1.1 PAC for the privilege attribute handle specified by
callers_pas and returns them in a sec_id_pac_t.
Before you run sec_cred_get_v1_pac, you must run the
sec_cred_get_initiator or sec_cred_get_delegate routine to obtain a
sec_cred_pa_handle_t for the callers_pas parameter.
Related Information
Routines:
sec_cred_get_delegate
sec_cred_get_initiator
ΓòÉΓòÉΓòÉ 8.2.21. sec_cred_initialize_attr_cursor ΓòÉΓòÉΓòÉ
Purpose
Initialize a sec_cred_attr_cursor_t used by the
sec_cred_get_extended_attrs routine.
Format
#include <dce/sec_cred.h>
void sec_cred_initialize_attr_cursor (
sec_cred_attr_cursor_t *cursor,
error_status_t *status);
Parameters
Input/Output
cursor As input, a pointer to a sec_cred_attr_cursor_t to be
initialized. As output, a pointer to an initialized
sec_cred_attr_cursor_t.
Output
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns sec_login_s_no_memory.
Usage
The sec_cred_initialize_attr_cursor routine allocates and initializes
a cursor of type sec_cred_attr_cursor_t for use with the
sec_cred_get_extended_attrs routine. Use the
sec_cred_free_attr_cursor routine to free the resources allocated to
cursor.
Related Information
Routines:
sec_cred_get_extended_attrs
sec_cred_free_attr_cursor
ΓòÉΓòÉΓòÉ 8.2.22. sec_cred_initialize_cursor ΓòÉΓòÉΓòÉ
Purpose
Initializes a sec_cred_cursor_t for use with the
sec_cred_get_delegate routine.
Format
#include <dce/sec_cred.h>
void sec_cred_initialize_cursor (
sec_cred_cursor_t *cursor,
error_status_t *status);
Parameters
Input/Output
cursor As input, a sec_cred_cursor_t to be initialized. As
output, an initialized sec_cred_cursor_t.
Output
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns the following error:
sec_login_s_no_memory
Usage
The sec_cred_initialize_cursor routine initializes a cursor of type
sec_cred_cursor_t for use with the sec_cred_get_delegate routine. Use
the sec_cred_free_cursor routine to free the resources allocated to
cursor.
Related Information
Routines:
sec_cred_get_delegate
sec_cred_free_cursor
ΓòÉΓòÉΓòÉ 8.2.23. sec_cred_inq_auth_service_info ΓòÉΓòÉΓòÉ
Purpose
Returns information regarding the authentication and authorization
services used in an authenticated RPC.
Format
#include <sec_cred.h>
void sec_cred_inq_auth_service_info (
rpc_authz_cred_handle_t callers_identity,
unsigned_char_p_t *server_princ_name,
unsigned32 *authn_svc,
unsigned32 *authz_svc,
error_status_t *error_status);
Parameters
Input
callers_identity A credential handle of type rpc_authz_cred_handle_t.
This parameter specifies the identity of the server's
RPC client as obtained from the RPC runtime. This
handle is supplied as output of the
rpc_binding_inq_auth_caller call.
Output
server_princ_name A pointer of type unsigned_char_p_t to the server
name to which the caller authenticated.
authn_svc A pointer to the authentication service.
authz_svc A pointer to the authorization service.
error_status A pointer to the completion status. On successful
completion, error_status_ok is returned. Otherwise, an
error is returned.
Usage
The sec_cred_inquire_auth_service_info routine returns information
regarding the authentication and authorization services used in an
authenticated RPC. Before you execute this call, you must execute a
call to rpc_binding_inq_auth_caller to obtain an rpc_authz_handle_t
for the callers_identity parameter.
Related Information
Routines:
rpc_binding_inq_auth_caller
ΓòÉΓòÉΓòÉ 8.2.24. sec_cred_is_authenticated ΓòÉΓòÉΓòÉ
Purpose
Indicates whether credentials are authenticated.
Format
#include <dce/sec_cred.h>
boolean32 sec_cred_is_authenticated(
rpc_authz_cred_handle_t callers_identity,
error_status_t *status);
Parameters
Input
callers_identity A handle of type rpc_authz_cred_handle_t to the
credentials to check for authentication. This handle is
supplied as output of the rpc_binding_inq_auth_caller
routine.
Output
status A pointer to the completion status. On successful
completion, status is assigned error_status_ok.
Otherwise, it returns sec_login_s_no_memory.
Usage
The sec_cred_is_authenticated routine returns TRUE if the credentials
identified by callers_identity are authenticated or FALSE if they are
not.
Before you run this call, you must run an rpc_binding_inq_auth_caller
call to obtain an rpc_authz_cred_handle_t for the callers_identity
parameter.
Return Values
The routine returns TRUE if the credentials are authenticated; FALSE
if they are not.
Related Information
Routines:
rpc_binding_inq_auth_caller
ΓòÉΓòÉΓòÉ 8.3. DCE Extended Registry Attribute API ΓòÉΓòÉΓòÉ
There are two application programming interfaces that manipulate extended
attributes: the DCE Attribute interface that creates attributes in a database
of your choice and the extended registry attribute (ERA) interface that creates
attributes in the registry database.
The ERA interface (consisting of sec_rgy_attr routines) provides facilities for
extending the Registry database by creating, maintaining, and viewing attribute
types and instances, and providing information to and receiving it from outside
attribute servers known as attribute triggers. ERA is the preferred API for
Security schema and attribute manipulations. Application servers that manage
legacy Security attributes or provide third-party processing of attributes
stored in the registry database can export and implement the sec_attr_trig
interface. Trigger servers are accessed through the sec_attr_trig interface by
the Security client agent during certain sec_rgy_attr routines. The extended
registry attribute interface uses the same binding mechanism as the Registry
API.
The DCE Attribute interface (consisting of dce_attr_sch routines) is provided
for schema and attribute manipulation of data repositories other than the
registry. Although similar to the ERA interface, the function of the DCE
Attribute interface is limited to creating schema entries (attribute types).
The interface does not provide routines to create and manipulate attribute
instances or to access trigger servers. This interface is described in The DCE
Routines.
The Registry is a repository for principal, group, organization, and account
data. It stores the network privilege attributes used by DCE and the account
data used by local operating systems. This local account data, however, is
appropriate only for UNIX operating systems. The Extended Registry Attribute
Facility provides a mechanism for extending the Registry schema to include data
(attributes) required by or useful to operating systems other than UNIX.
The ERA API provides the ability to define attribute types and to attach
attribute instances to registry objects. Registry objects are nodes in the
Registry database; access to them is controlled by an ACL manager type. The
Registry objects are:
o Principal
o Group
o Organization
o Policy
o Directory
o Replist
o Attr_schema
The ERA API also provides a trigger interface that application servers use to
integrate their attribute services with the ERA services.
See the following subtopics for more information:
Format
Data Types
Constants
Extended Registry Attribute Routines
Related Information
ΓòÉΓòÉΓòÉ 8.3.1. Format ΓòÉΓòÉΓòÉ
#include <dce/sec_attr_base.h>
ΓòÉΓòÉΓòÉ 8.3.2. Data Types ΓòÉΓòÉΓòÉ
The following data types are used in sec_rgy_attr routines:
sec_attr_twr_ref_t A pointer to a tower. This data type is used with the
sec_attr_twr_set_t data type to allow a client to pass an
unallocated array of towers, which the server must allocate. Both
data types are used in conjunction with the sec_attr_bind_type_t
data type.
sec_attr_twr_set_t A structure that defines an array of towers. This data type
is used with the sec_attr_twr_ref_t data type to allow a client to
pass an unallocated array of towers, which the server must allocate.
Both data types are used in conjunction with the
sec_attr_bind_type_t data type. The sec_attr_twr_set_t structure
consists of the following elements:
count An unsigned 32-bit integer specifying the number of
towers in the array.
towers[] An array of pointers (of type sec_attr_twr_ref_t) to
towers.
sec_attr_bind_type_t A 32-bit integer that specifies the type of binding used
by an attribute interface. The data type, which is used in
conjunction with the sec_attr_binding_t data type, uses the
following constants:
sec_attr_bind_type_string An RPC string binding.
sec_attr_bind_type_twrs A DCE protocol tower representation of
a binding.
sec_attr_bind_type_svrname A name in rpc_c_ns_syntax format
that identifies a CDS entry containing the server's
binding information. This constant has the following
structure:
name_syntax Must be rpc_c_ns_syntax_dce to
specify that DCE naming rules are used
to specify name.
name A pointer to a name of a CDS entry in
rpc_c_ns_syntax_dce syntax.
sec_attr_binding_t A discriminated union that supplies information to generate
a binding handle for an attribute trigger. This data type, which is
used in conjunction with the sec_attr_bind_info_t data type, is
composed of the following elements:
bind_type A value of type sec_attr_bind_type_t that defines the
type of binding used by an attribute interface. The
contents of tagged union depend on the value of
sec_attr_bind_type_t.
tagged_union A tagged union specifying the binding handle. The
contents of the tagged union depend on the value of
bind_type as follows:
If bind_type is... Tagged_union is...
sec_attr_bind_type_string A pointer to an
unsigned 32-bit
character string
specifying the
attribute's RPC
string binding.
sec_attr_bind type_twrs The attribute's
tower binding
representation of
type
sec_attr_twr_set_t.
sec_attr_bind_svrname A pointer to a
name of type
sec_attr_bind_type_t
that specifies a
Cell Directory
Service entry
containing the
attribute
trigger's binding
information.
sec_attr_binding_p_t A pointer to a sec_attr_binding_t union.
sec_attr_bind_auth_info_type_t An enumeration that defines whether the binding
is authenticated. This data type is used in conjunction with the
sec_attr_bind_auth_info_t data type to set up the authorization
method and parameters for an RPC binding. The
sec_attr_bind_auth_info_type_t type consists of the following
elements:
sec_attr_bind_auth_none The binding is not authenticated.
sec_attr_bind_auth_dce The binding uses DCE shared-secret key
authentication.
sec_attr_bind_auth_info_t A discriminated union that defines authorization and
authentication parameters for a binding. This data type is used in
conjunction with the sec_attr_bind_auth_info_type_t data type to set
up the authorization method and parameters for an RPC binding. The
sec_attr_bind_auth_info_t data type consists of the following
elements:
info_type A sec_attr_bind_auth_info_type_t data type that
specifies whether the binding is authenticated. The
contents of tagged_union depend on the value of
sec_attr_bind_auth_info_type_t.
tagged_union A tagged union specifying the method of
authorization and the authorization parameters. For
unauthenticated bindings
(sec_attr_bind_auth_info_type_t =
sec_attr_bind_auth_none), no parameters are supplied.
For authenticated bindings
(sec_attr_bind_auth_info_type_t =
sec_attr_bind_auth_dce), the following union is
supplied:
svr_princ_name A pointer to a character string
that specifies the principal name of
the server referenced by the binding
handle.
protect_level An unsigned 32-bit integer
indicating the protection level for
RPC calls made using the server
binding handle. The protection level
determines the degree that
authenticated communications between
the client and the server are
protected by the authentication
service specified by authn_svc.
If the RPC runtime or the RPC protocol
in the bound protocol sequence does
not support a specified level, the
level is automatically upgraded to the
next higher supported level. The
possible protection levels are as
follows:
rpc_c_protect_level_default Uses
the default protection
level for the specified
authentication service.
The default protection
level for DCE
shared-secret key
authentication is
rpc_c_protect_level_pkt_value.
rpc_c_protect_level_none Performs
no authentication:
tickets are not
exchanged, session keys
are not established,
client PACs or names
are not certified, and
transmissions are in
the clear. Note that
although uncertified
PACs should not be
trusted, they can be
useful for debugging,
tracing, and measuring
purposes.
rpc_c_protect_level_connect
Authenticates only when
the client establishes
a relationship with the
server.
rpc_c_protect_level_call
Authenticates only at
the beginning of each
remote procedure call
when the server
receives the request.
This level does not
apply to remote
procedure calls made
over a connection-based
protocol sequence (that
is, ncacn_ip_tcp). If
this level is specified
and the binding handle
uses a connection-based
protocol sequence, the
routine uses the
rpc_c_protect_level_pkt
level instead.
rpc_c_protect_level_pkt Ensures
that all data received
is from the expected
client.
rpc_c_protect_level_pkt_integ
Ensures and verifies
that none of the data
transferred between
client and server has
been modified. This is
the highest protection
level that is
guaranteed as present
in the RPC runtime.
rpc_c_protect_level_pkt_privacy
Authenticates as
specified by all of the
previous levels and
also encrypts each RPC
argument value. This
is the highest
protection level, but
is not guaranteed as
present in the RPC
runtime.
authn_svc Specifies the authentication service
to use. The exact level of protection
provided by the authentication service
is specified by protect_level. The
supported authentication services are
as follows:
rpc_c_authn_none No
authentication: no
tickets are exchanged,
no session keys
established, client
PACs or names are not
transmitted, and
transmissions are in
the clear. Specify
rpc_c_authn_none to
turn authentication off
for remote procedure
calls made using this
binding.
rpc_c_authn_dce_secret DCE
shared-secret key
authentication.
rpc_c_authn_default Default
authentication service.
The current default
authentication service
is DCE shared-secret
key; therefore,
specifying
rpc_c_authn_default is
equivalent to
specifying
rpc_c_authn_dce_secret.
rpc_c_authn_dce_public DCE public
key authentication
(reserved for future
use).
authz_svc Specifies the authorization service
implemented by the server for the
interface. The validity and
trustworthiness of authorization data,
as with any application data, is
dependent on the authentication
service and protection level
specified. The supported authorization
services are:
rpc_c_authz_none Server performs
no authorization. This
is valid only if
authn_svc is set to
rpc_c_authn_none,
specifying that no
authentication is being
performed.
rpc_c_authz_name Server performs
authorization based on
the client principal
name. This value cannot
be used if authn_svc is
rpc_c_authn_none.
rpc_c_authz_dce Server performs
authorization using the
client's DCE PAC sent
to the server with each
remote procedure call
made with this binding.
Generally, access is
checked against DCE
ACLs.
sec_attr_bind_info_t A structure that specifies attribute trigger binding
information. This data type, which is used in conjunction with the
sec_attr_schema_entry_t data type, contains the following elements:
auth_info The binding authorization information of type
sec_attr_bind_auth_info_t.
num_bindings An unsigned 32-bit integer specifying the number
of binding handles in the bindings array.
bindings[] An array of sec_attr_binding_t data types that
specify binding handles.
sec_attr_bind_info_p_t A pointer to a sec_attr_bind_info_t union.
sec_attr_encoding_t An enumerator that contains attribute encoding tags used
to define the legal encodings for attribute values. The data type,
which is used in conjunction with the sec_attr_value_t and
sec_attr_schema_entry_t data types, consists of the following
elements:
sec_attr_enc_any The attribute value can be of any legal
encoding type. This encoding tag is legal in a schema
entry only. An attribute entry must contain a
concrete encoding type.
Note: This encoding type is not implemented in this
release.
sec_attr_enc_void The attribute has no value. It is a marker
that is either present or absent.
sec_attr_enc_printstring The attribute value is a printable IDL
string in the DCE Portable Character Set.
sec_attr_enc_printstring_array The attribute value is an array
of print strings.
sec_attr_enc_integer The attribute value is a signed 32-bit
integer.
sec_attr_enc_bytes The attribute value is a string of bytes.
The string is assumed to be a pickle or some other
self-describing type. (See also the
sec_attr_enc_bytes_t data type.)
sec_attr_enc_confidential_bytes The attribute value is a string
of bytes that have been encrypted in the key of the
principal object to which the attribute is attached.
The string is assumed to be a pickle or some other
self-describing type. This encoding type is useful
only when attached to a principal object, where it is
decrypted and encrypted each time the principal's
password changes. (See also the sec_attr_enc_bytes_t
data type.)
sec_attr_enc_i18n_data The attribute value is an
"internationalized" string of bytes with a tag
identifying the OSF-registered codeset used to encode
the data. (See also the sec_attr_i18n_data_t data
type.)
sec_attr_enc_uuid The attribute is a value of type uuid_t, a
DCE UUID.
sec_attr_enc_attr_set The attribute value is an attribute set,
a vector of attribute UUIDs used to associate
multiple related attribute instances that are members
of the set. (See also the sec_attr_enc_attr_set_t
data type.)
sec_attr_enc_binding The attribute value is a
sec_attr_bind_info_t data type that specifies DCE
server binding information.
sec_attr_enc_trig_binding This encoding type is returned by the
rs_attr_lookup routine. It informs the client agent
of the trigger binding information of an attribute
with a query trigger.
Unless sec_attr_enc_void or sec_attr_enc_any is specified, the
attribute values must conform to the attribute's encoding type.
sec_attr_enc_bytes_t A structure that defines the length of attribute encoding
values for attributes encoded as sec_attr_enc_bytes and
sec_attr_enc_confidential_bytes. The structure, which is used in
conjunction with the sec_attr_value_t data type, consists of:
length An unsigned 32-bit integer that defines the data
length.
data[] An array of bytes specifying the length of attribute
encoding data.
sec_attr_i18n_data_t A structure that defines the codeset used for attributes
encoded as sec_attr_enc_il8n_data and the length of the attribute
encoding values. The structure, which is used in conjunction with
the sec_attr_value_t data type, consists of:
codeset An unsigned 32-bit identifier of a codeset registered
with the Open Software Foundation.
length An unsigned 32-bit integer that defines the data
length.
data[] An array of bytes specifying the length of attribute
encoding data.
sec_attr_enc_attr_set_t A structure that supplies the UUIDs of each member of
an attribute set. The structure, which is used in conjunction with
the sec_attr_value_t data type, consists of:
num_members An unsigned 32-bit integer specifying the total
number of attributes in the set.
members[] An array containing values of type uuid_t, the UUID
of each member in the set.
sec_attr_enc_printstring_t A structure that contains a print string.
sec_attr_enc_printstring_p_t A pointer to a sec_attr_enc_printstring_t
structure.
sec_attr_enc_str_array_t A structure that defines a print string array. It
consists of:
num_strings An unsigned 32-bit integer specifying the number of
strings in the array.
strings[] An array of pointers (of type
sec_attr_enc_print_string_p_t) to print strings.
sec_attr_value_t A discriminated union that defines attribute values. The
union, which is used in conjunction with the sec_attr_t data type,
consists of the following elements:
attr_encoding A sec_attr_encoding_t data type that defines
attribute encoding. The contents of tagged union
depend on the value of sec_attr_encoding_t.
tagged_union A tagged union whose contents depend on
attr_encoding as follows:
If attr_encoding is... Tagged_union is...
sec_attr_enc_void NULL
sec_attr_enc_printstring A pointer to
printstring
sec_attr_enc_printstring_array A pointer to
string_array, an
array of print
strings
sec_attr_enc_integer signed_int, a
32-bit signed
integer
sec_attr_enc_bytes bytes, a pointer
to a structure of
type
sec_attr_enc_bytes_t
sec_attr_enc_confidential_bytes bytes, a pointer
to a structure of
type
sec_attr_enc_bytes_t
sec_attr_enc_i18n_data idata, a pointer
to a structure of
type
sec_attr_i18n_data_t
sec_attr_end_uuid uuid, a value of
type uuid_t
sec_attr_enc_attr_set attr_set, a
pointer to a
structure of type
sec_attr_enc_attr_set_t
sec_attr_enc_binding binding, a pointer
to a structure of
type
sec_attr_binding_info_t
sec_attr_t A structure that defines an attribute. The structure consists of:
attr_id A value of type uuid_t, the UUID of the attribute.
attr_value A value of type sec_attr_value_t.
sec_attr_acl_mgr_info_t A structure that contains the access control
information defined in a schema entry for an attribute. The
structure, which is used in conjunction with the
sec_attr_schema_entry_t data type, consists of the following
elements:
acl_mgr_type The value of type uuid_t that specifies the UUID
of the ACL manager type that supports the object type
to which the attribute can be attached. This field
provides a well defined context for evaluating the
permission bits needed to operate on the attribute.
The following table lists the ACL Manager types for
registry objects:
ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
Γöé REGISTRY OBJECT Γöé ACL MANAGER TYPE Γöé VALID PERMIS- Γöé
Γöé TYPE Γöé Γöé SIONS Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé principal Γöé 06ab9320-0191-11ca-a9e8-08001e039dΓöédrcDnfmaug Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé group Γöé 06ab9640-0191-11ca-a9e8-08001e039dΓöédrctDnfmM Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé organization Γöé 06ab9960-0191-11ca-a9e8-08001e039dΓöédrctDnfmM Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé directory Γöé 06ab9c80-0191-11ca-a9e8-08001e039dΓöédrcidDn Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé policy Γöé 06ab8f10-0191-11ca-a9e8-08001e039dΓöédrcma Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé replist Γöé 2ac24970-60c3-11cb-b261-08001e039dΓöédcidmAI Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
query_permset Data of type sec_acl_permset_t that defines the
permission bits needed to access the attribute's
value.
update_permset Data of type sec_acl_permset_t that defines the
permission bits needed to update the attribute's
value.
test_permset Data of type sec_acl_permset_t that defines the
permission bits needed to test the attribute's value.
delete_permset Data of type sec_acl_permset_t that defines the
permission bits needed to delete an attribute
instance.
sec_attr_acl_mgr_info_p_t A pointer to a sec_attr_acl_mgr_info_t structure.
sec_attr_acl_mgr_info_set_t A structure that defines the attribute's ACL
manager set. The structure consists of the following elements:
num_acl_mgrs An unsigned 32-bit integer that specifies the
number of ACL managers in the ACL manager set.
mgr_info[] An array of pointers of type sec_attr_mgr_info_p_t
that define the ACL manager types in the ACL manager
set and the permission sets associated with the ACL
manager type.
sec_attr_intercell_action_t An enumerator that specifies the action that
should be taken by the Privilege Service when it reads acceptable
attributes from a foreign cell. A foreign attribute is acceptable
only if there is either a schema entry for the foreign cell or if
sec_attr_intercell_act_accept is set to TRUE.
This enumerator, which is used in conjunction with the
sec_attr_schema_entry_t data type, is composed of the following
elements:
sec_attr_intercell_act_accept If the unique flag in the
sec_attr_schema_entry_t data type is not set on,
retain the attribute. If the unique flag is set on,
retain the attribute only if its value is unique
among all attribute instances of the same attribute
type within the cell.
sec_attr_intercell_act_reject Discard the input attribute.
sec_attr_intercell_act_evaluate Use the binding information in
the trig_binding field of this
sec_attr_schema_entry_t data type to make a
sec_attr_trig_query call to a trigger server. That
server determines whether to retain the attribute
value, discard the attribute value, or map the
attribute to another value or values).
sec_attr_trig_type_t Specifies the trigger type, a flag that determines
whether an attribute trigger should be used for query operations.
The data type, which is used in conjunction with the
sec_attr_schema_entry_t data type, uses the following constants:
sec_attr_trig_type_query The attribute trigger server is used
for query operations.
sec_attr_trig_type_update The attribute trigger server is used
for update operations.
sec_attr_trig_type_none The default. There is no attribute
trigger server associated with this schema entry.
sec_attr_schema_entry_t A structure that defines a complete attribute entry
for the schema catalog. The entry is identified by both a unique
string name and a unique attribute UUID. Although either can be used
as a retrieval key, the string name should be used for interactive
access to the attribute and the UUID for access by applications. The
attribute UUID is used to identify the semantics defined for the
attribute type in the schema.
The sec_attr_schema_entry_t data type consists of the following
elements:
attr_name A pointer to the attribute name.
attr_id A value of type uuid_t that identifies the attribute
type.
attr_encoding An enumerator of type sec_attr_encoding_t that
specifies the attribute's encoding.
acl_mgr_set A structure of type sec_attr_acl_mgr_info_set_t
that specifies the ACL manager types that support the
objects on which attributes of this type can be
created and the permission bits supported.
schema_entry_flags An unsigned integer of type
sec_attr_sch_entry_flags_t that defines bitsets for
the following flags:
unique When set to on, this flag indicates
that each instance of this attribute
type must have a unique value within
the cell for the object type implied
by the ACL Manager type. If this flag
is not set to on, uniqueness checks
are not performed for attribute
writes.
multi_valued When set to on, this flag indicates
that this attribute type can be
multivalued; in other words, multiple
instances of the same attribute type
can be attached to a single registry
object. If this flag is not set to on,
only one instance of this attribute
type can be attached to an object.
reserved When set to on, this flag prevents the
schema entry from being deleted
through any interface or by any user.
If this flag is not set to on, the
entry can be deleted by any authorized
principal.
use_defaults When set to on, the system-defined
default attribute value is returned on
a client query if an instance of this
attribute does not exist on the
queried object. If this flag is not
set to on, system defaults are not
used.
intercell_action An enumerator of type
sec_attr_intercell_action_t that specifies how the
Privilege Service handles attributes from a foreign
cell.
trig_types A flag of type sec_attr_trig_type_t that specifies
whether a trigger can perform update or query
operations.
trig_binding A pointer to a structure of type
sec_attr_bind_info_t that supplies the attribute
trigger binding handle.
scope A pointer to a string that defines the objects to
which the attribute can be attached.
comment A pointer to a string that contains general comments
about the attribute.
sec_attr_schema_entry_parts_t A 32-bit bitset containing flags that specify
the schema entry fields that can be modified on a schema entry
update operation. This data type contains the following flags:
sec_attr_schema_part_name If set, indicates that the attribute
name (attr_name) can be changed.
sec_attr_schema_part_reserved If set, indicates that the
setting of the reserved flag, which determines
whether the schema entry can be deleted, can be
changed.
sec_attr_schema_part_defaults If set, indicates that the
use_defaults flag, which determines whether a query
for a nonexistent attribute does not result in a
search for a system default, can be changed.
sec_attr_schema_part_trig_bind If set, indicates that the
trigger's binding information (trig_binding) can be
changed.
sec_attr_schema_part_comment If set, indicates whether comments
associated with the schema entry (comment) can be
changed.
sec_attr_component_name_t A pointer to a character string used to further
specify the object to which the attribute is attached. (Note that
this data type is analogous to the sec_acl_component_name_t data
type in the ACL interface.)
sec_attr_cursor_t A structure that provides a pointer into a registry database
and is used for multiple database operations.
This cursor must minimally represent the object indicated by
xattrschema in the schema interfaces, or component_name in the
attribute interfaces. The cursor can additionally represent an
entry within that schema or an attribute instance on that component.
sec_attr_srch_cursor_t A structure that provides a pointer into a registry
database and is used for multiple database operations. The cursor
must minimally represent the list of all objects managed by this
server that possess the search attributes specified in the
sec_attr_srch_cursor_init routine. It can additionally represent a
given object within this list, as well as attribute instances
possessed by that object.
sec_attr_trig_cursor_t A structure that provides an attribute trigger cursor
for interactive operations. The structure consists of the following
elements:
source A value of type uuid_t that provides a UUID to
identify the server that initialized the cursor.
object_handle A signed 32-bit integer that identifies the
object (specified by xattrschema in the schema
interface or component_name in the attribute
interface) upon which the operation is being
performed.
entry_handle A signed 32-bit integer that identifies the
current entry (schema_entry in the schema interface
or attribute instance in the attribute interface) for
the operation.
valid A boolean field with the following values:
TRUE (1) Indicates an initialized cursor.
FALSE (0) Indicates an uninitialized cursor.
sec_attr_trig_timeval_sec_t A 32-bit integer containing the seconds portion of
a UNIX timeval_t structure, to be used when expressing absolute
dates.
ΓòÉΓòÉΓòÉ 8.3.3. Constants ΓòÉΓòÉΓòÉ
The following constants are used in sec_attr calls:
sec_attr_bind_auth_dce The binding uses DCE shared-secret key authentication.
sec_attr_bind_auth_none The binding is not authenticated.
sec_attr_bind_type_string The attribute uses an RPC string binding.
sec_attr_bind_type_svrname The attribute uses a name in rpc_c_ns_syntax format
that identifies a CDS entry containing the server's binding
information. This constant has the following structure:
name_syntax Must be rpc_c_ns_syntax_dce to specify that DCE
naming rules are used to specify name.
name A pointer to a name of a CDS entry in
rpc_c_ns_syntax_dce syntax.
sec_attr_bind_type_twr The attribute uses a DCE protocol tower binding
representation.
ΓòÉΓòÉΓòÉ 8.3.4. Extended Registry Attribute Routines ΓòÉΓòÉΓòÉ
Following is a list of the ERA API routines:
priv_attr_trig_query
sec_attr_trig_update
sec_attr_util_alloc_copy
sec_attr_util_free
sec_attr_util_inst_free
sec_attr_util_inst_free_ptrs
sec_attr_util_sch_ent_free
sec_attr_util_sch_ent_free_ptrs
sec_attr_util_sch_free_acl_mgrs
sec_attr_util_sch_free_binding
sec_rgy_attr_cursor_alloc
sec_rgy_attr_cursor_init
sec_rgy_attr_cursor_release
sec_rgy_attr_cursor_reset
sec_rgy_attr_delete
sec_rgy_attr_get_effective
sec_rgy_attr_lookup_by_id
sec_rgy_attr_lookup_by_name
sec_rgy_attr_lookup_no_expand
sec_rgy_attr_sch_aclmgr_strings
sec_rgy_attr_sch_create_entry
sec_rgy_attr_sch_cursor_alloc
sec_rgy_attr_sch_cursor_init
sec_rgy_attr_sch_cursor_release
sec_rgy_attr_sch_cursor_reset
sec_rgy_attr_sch_delete_entry
sec_rgy_attr_sch_get_acl_mgrs
sec_rgy_attr_sch_lookup_by_id
sec_rgy_attr_sch_lookup_by_name
sec_rgy_attr_sch_scan
sec_rgy_attr_sch_update_entry
sec_rgy_attr_test_and_update
sec_rgy_attr_update
ΓòÉΓòÉΓòÉ 8.3.5. Related Information ΓòÉΓòÉΓòÉ
Files:
\usr\include\dce\sec_attr_base.idl - The idl file from which sec_attr_base.h
was derived.
ΓòÉΓòÉΓòÉ 8.3.6. priv_attr_trig_query ΓòÉΓòÉΓòÉ
Purpose
Retrieves attributes stored by a trigger server for a specified
principal for inclusion in the principal's EPAC.
Format
#include <dce/priv_attr_trig.h>
void priv_attr_trig_query (
handle_t h,
sec_id_foreign_t principal,
unsigned32 num_upstream_delegates,
sec_id_foreign_t upstream_delegates[],
priv_attr_trig_cursor_t *cursor,
unsigned32 num_attr_keys,
unsigned32 space_avail,
sec_attr_t attr_keys[],
unsigned32 *num_returned,
sec_attr_t attrs[],
priv_attr_trig_timeval_sec_t time_to_live[],
unsigned32 *num_left,
error_status_t *status);
Parameters
Input
h An opaque handle bound to a trigger server. Use the
trigger binding information specified in the attribute
encoding to acquire a bound handle.
principal A value of type sec_id_foreign_t that identifies the
UUID, name, and cell of the principals whose attributes
are to be retrieved.
num_upstream_delegates If principal is a member of a delegation
chain, an unsigned 32-bit integer that specifies the
number of delegates in the chain upstream from (before)
this principal. The upstream delegate chain ordering
reflects the sequence in which delegates were added to
the chain. For example, the delegation initiator is
always first in the chain.
upstream_delegates[] If the Privilege sever is adding principal to a
delegation chain, an array of values of type
sec_id_foreign_t that identify the UUID and cell of
each delegate in the upstream delegation chain. Note
that principal names are not provided.
num_attr_keys An unsigned 32-bit integer that specifies the number of
elements in the attr_keys array. Set this parameter to
0 to return all the principal's attributes that the
caller is authorized to see.
space_avail An unsigned 32-bit integer that specifies the size of
the attr_keys array.
attr_keys[] An array of values of type sec_attr_t that identify the
attribute type ID of the attribute instance(s) to be
looked up. The size of the attr_keys array is
determined by the num_attr_keys parameter.
Input/Output
cursor A pointer to a priv_attr_trig_cursor_t. As an input
parameter, cursor is a pointer to a
priv_attr_trig_cursor_t initialized by the
sec_rgy_attr_cursor_init routine. As an output
parameter, cursor is a pointer to a
priv_attr_trig_cursor_t that is positioned past the
components returned in this routine.
Output
num_returned A pointer to a 32-bit unsigned integer that specifies
the number of attribute instances returned in the attrs
array.
attrs[] An array of values of type sec_attr_t that contains the
attributes retrieved by UUID. The size of the array is
determined by space_avail and the length by
num_returned.
time_to_live[] An array of values of type
priv_attr_trig_timeval_sec_t that specifies, for each
attribute in the attrs array, the lifetime in seconds
for which the attribute can be safely cached. The size
of the array is determined by space_avail and the
length by num_returned.
num_left A pointer to a 32-bit unsigned integer that supplies
the number of attributes that were found but that could
not be returned because of space constraints in the
attrs buffer. To ensure that all the attributes are be
returned, increase the size of the attrs array by
increasing the size of space_avail and num_returned.
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok, or, if
the requested attributes were not available, it returns
the message not_all_available. Otherwise, it returns
one of the following errors:
unauthorized
registry server unavailable
trigger server unavailable
Usage
The priv_attr_trig_query routine is used by the Privilege server to
retrieve attributes for a principal specified by UUID and include
them in the principal's EPAC. The Privilege server calls this routine
when it gets a request for ERAs in an EPAC.
Although generally this routine is not called directly, this
reference section is provided for users who are writing the attribute
trigger servers that receive priv_attr_trig_query input and supply
its output.
If the num_attr_keys parameter is set to 0, all of the object's
attributes that the caller is authorized to see are returned. This
routine is useful for access by applications.
For multivalued attributes, the routine returns a sec_attr_t for each
value as an individual attribute instance. For attribute sets, the
routine returns a sec_attr_t for each member of the set; it does not
return the set instance.
The attr_keys array, which specifies the attributes to be returned,
contains values of type sec_attr_t. These values consist of:
attr_id, a UUID that identifies the attribute type
attr_value, values of sec_attr_value_t that specify the
attribute's encoding type and values.
Use the attr_id field of each attr_keys array element to specify the
UUID that identifies the attribute type to be returned.
If the attribute instance to be read is associated with a query
attribute trigger that requires additional information before it can
process the query request, use a sec_attr_value_t to supply the
requested information:
o Set the sec_attr_encoding_t to an encoding type that is
compatible with the information required by the query attribute
trigger.
o Set the sec_attr_value_t to hold the required information.
Note that if you set num_attr_keys to zero to return all the object's
attributes and that attribute is associated with a query attribute
trigger, the attribute trigger is called with no input attribute
information (that would normally have been passed in with the
attr_value field).
The cursor parameter specifies a cursor of type
priv_attr_trig_cursor_t initialized to the starting point in the
attribute list for processing the query. Use the
sec_rgy_attr_cursor_init routine to initialize cursor. If cursor is
uninitialized, the server begins processing the query at the first
attribute that satisfies the search criteria.
The num_left parameter contains the number of attributes that were
found but could not be returned because of space constraints of the
attrs array. (Note that this number may be inaccurate if the target
server allows updates between successive queries.) To obtain all of
the remaining attributes, set the size of the attrs array so that it
is large enough to hold the number of attributes listed in num_left.
Permissions Required
The priv_attr_trig_query routine requires the query permission set
for each attribute type identified in the attr_keys array. These
permissions are defined as part of the ACL manager set in the schema
entry of each attribute type.
Related Information
Routines: sec_rgy_attr_cursor_init
sec_attr_trig_update
Files:
\usr\include\dce\priv_attr_trig.idl - The idl file from which
dce\priv_attr_trig.h was derived.
ΓòÉΓòÉΓòÉ 8.3.7. sec_attr_trig_query ΓòÉΓòÉΓòÉ
Purpose
Reads attributes coded with an attribute trigger type of query.
Format
#include <dce/sec_attr_trig.h>
void sec_attr_trig_query (
handle_t h,
sec_attr_component_name_t cell_name,
sec_attr_component_name_t component_name,
sec_attr_trig_cursor_t *cursor,
unsigned32 num_attr_keys,
unsigned32 space_avail,
sec_attr_t attr_keys[],
unsigned32 *num_returned,
sec_attr_t attrs[],
sec_attr_trig_timeval_sec_t time_to_live[],
unsigned32 *num_left,
error_status_t *status);
Parameters
Input
h A handle referring to the trigger server to be
accessed. Use the trigger binding information specified
in the attribute encoding to acquire a bound handle.
cell_name A value of sec_attr_component_name_t that identifies
the cell where the object whose attribute is to be
accessed resides. Supply a NULL cell_name to specify
the local cell (\.:).
component_name A value of sec_attr_component_name_t that identifies
the name of the object whose attribute is to be
accessed. If cell_name specifies a foreign cell,
component_name is interpreted as a UUID in string
format because the caller of this interface knows only
the UUID, not the name, of the foreign principal.
num_attr_keys Specifies the number of elements in the attr_keys
array. This integer must be greater than 0.
space_avail Specifies the size of the attr_keys array.
attr_keys[] An array of values of type sec_attr_t. For each
attribute instance, the attr_keys array contains an
attr_id (a UUID of type uuid_t) to identify the
attribute to be queried and an attr_value. The
attr_value field can be used to pass in optional
information required by the attribute trigger query. If
no additional information is to be passed, set
attr_value to sec_attr_enc_void. This is actually
accomplished by setting the sec_attr_encoding_t data
type to sec_attr_enc_void.
Input/Output
cursor A pointer to a cursor of type sec_attr_trig_cursor_t.
As an input parameter, cursor can be initialized (by
the sec_rgy_attr_cursor_init routine) or uninitialized.
As an output parameter, cursor is positioned past the
attributes returned by this routine.
Output
num_returned A pointer to an unsigned 32-bit integer that specifies
the number of attribute instances returned in the
attr_keys array.
attrs[] An array of values of type sec_attr_t. The size of this
array is determined by the space_avail parameter and
the length by the num_returned parameter.
time_to_live[] An array of values of type
sec_attr_trig_timeval_sec_t. For each attribute in the
attrs array, the time_to_live array specifies the time
in seconds that the attribute can be safely cached.
num_left A pointer to an unsigned 32-bit integer that supplies
the number of attributes that were found but were not
returned because of space constraints in the attrs
buffer.
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns one of the following errors:
o not_all_available
o unauthorized
Usage
The sec_attr_trig_query routine reads attributes coded with an
attribute trigger type of query.
The sec_attr_trig_query routine is called by the DCE attribute lookup
code for all schema entries that specify a query attribute trigger
(sec_attr_trig_type_query specified with the
sec_attr_trig_type_flags_t data type). The attribute query code
passes the sec_attr_trig_query input parameters to a user-written
query attribute trigger server and receives the output parameters
back from the server. Although generally this routine is not called
directly, this reference page is provided for users who are writing
the attribute trigger servers that receive sec_attr_trig_query input
and supply its output.
Multivalued attributes are returned as independent attribute
instances sharing the same attribute UUID. A read of an attribute set
returns all instances of members of the set; the attribute set
instance is not returned.
For objects in the local cell, set the cell_name parameter to NULL,
and the component_name parameter to specify the object's name.
For objects in a foreign cell, set the cell_name parameter to
identify the name of the foreign cell, and the component_name
parameter to the UUID in string format that identifies the object in
the foreign cell.
The cursor parameter specifies a cursor of type
sec_attr_trig_cursor_t that establishes the starting point in the
attribute list for processing the query. Use the
sec_rgy_attr_cursor_init routine to initialize a list cursor. If
cursor is uninitialized, the server begins processing the query at
the first attribute that satisfies the search criteria. Note that,
generally, the sec_rgy_attr_cursor_init routine makes a remote call
to the specified server. To initialize the cursor without making this
remote call, set the valid parameter in the sec_attr_trig_cursor_init
routine to 0.
The num_left parameter contains the number of attributes that were
found but that could not be returned because of space constraints of
the attrs array. (Note that this number might be inaccurate if the
target server allows updates between successive queries.) To obtain
all of the remaining attributes, set the size of the attrs array so
that it is large enough to hold the number of attributes listed in
num_left.
Related Information
Routines: sec_attr_trig_update
sec_rgy_attr_cursor_init
Files:
dcelocal\include\dce\sec_attr_trig.idl - The idl file from which
dce\sec_attr_trig.h was derived.
ΓòÉΓòÉΓòÉ 8.3.8. sec_attr_trig_update ΓòÉΓòÉΓòÉ
Purpose
Passes attribute updates to an update attribute trigger server for
evaluation. This routine is for attributes coded with an attribute
trigger type of update.
Format
#include <dce/sec_attr_trig.h>
void sec_attr_trig_update (
handle_t h,
sec_attr_component_name_t cell_name,
sec_attr_component_name_t component_name,
unsigned32 num_to_write,
unsigned32 space_avail,
sec_attr_t in_attrs[],
unsigned32 *num_returned,
sec_attr_t out_attrs[],
unsigned32 *num_left,
signed32 *failure_index,
error_status_t *status);
Parameters
Input
h A handle referring to the trigger server to be
accessed. Use the trigger binding information specified
in the attribute encoding to acquire a bound handle.
cell_name A value of sec_attr_component_name_t that identifies
the cell where the object whose attribute is to be
accessed resides. Supply a NULL cell_name to specify
the local cell (\.:).
component_name A value of sec_attr_component_name_t that identifies
the name of the object whose attribute is to be
accessed. If cell_name specifies a foreign cell,
component_name is interpreted as a UUID in string
format because the caller of this interface knows only
the UUID, not the name, of the foreign principal.
num_to_write An unsigned 32-bit integer that specifies the number of
elements in the in_attrs array. This integer must be
greater than 0.
space_avail An unsigned 32-bit integer that specifies the size of
the out_attrs array.
in_attrs[] An array of values of type sec_attr_t that specifies
the attribute instances to be written. The size of the
in_attrs array is determined by num_to_write.
Output
num_returned A pointer to an unsigned 32-bit integer that specifies
the number of attribute instances returned in the
out_attrs array.
out_attrs[] An array of values of type sec_attr_t. These values,
supplied by the update attribute trigger server, are in
a form suitable for storage in the registry database.
num_left A pointer to an unsigned 32-bit integer that supplies
the number of attributes that were found but were not
returned because of space constraints in the out_attrs
buffer.
failure_index In the event of an error, failure_index is a pointer to
the element in the in_attrs array that caused the
update to fail. If the failure cannot be attributed to
a specific attribute, the value of failure_index is -1.
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns one of the following errors:
o database read only
o server unavailable
o invalid/unsupported attribute type
o invalid encoding type
o value not unique
o site read only
o unauthorized
Usage
The sec_attr_trig_update routine passes attributes coded with an
attribute trigger type of update to a user-written update attribute
trigger server for evaluation before the updates are made to the
registry.
Although generally this routine is not called directly, this
reference page is provided for users who are writing the attribute
trigger servers that receive sec_attr_trig_update input and supply
its output.
The sec_attr_trig_update routine is called by the DCE attribute
update code for all schema entries that specify an update attribute
trigger (sec_attr_trig_type_update specified with the
sec_attr_trig_type_flags_t data type). The attribute update code
passes the sec_attr_trig_update input parameters to a user-written
update attribute trigger server and receives the output parameters
back from the server. The attribute trigger server is responsible
for evaluating the semantics of the entry in order to reject or
accept it, and the attribute trigger server can even make changes in
the output it sends back to the update code to ensure that the entry
adheres to the semantics. The output received from the attribute
trigger server is in a form to be stored in the registry. (Note that
update attribute trigger servers do not store attribute values, which
are stored in the registry database.)
This is an atomic operation: if the update of any attribute in the
array fails to pass the evaluation, all updates are ended. The
attribute causing the update to fail is identified in failure_index.
If the failure cannot be attributed to a given attribute, the
failure_index parameter contains -1.
For objects in the local cell, set the cell_name parameter to NULL
and the component_name parameter to specify the object's name.
For objects in a foreign cell, set the cell_name parameter to the
name of the foreign cell, and the component_name parameter to specify
the UUID in string format that identifies the object in the foreign
cell.
Related Information
Files:
dcelocal\include\dce\sec_attr_trig.idl - The idl file from which
dce\sec_attr_trig.h was derived.
ΓòÉΓòÉΓòÉ 8.3.9. sec_attr_util_alloc_copy ΓòÉΓòÉΓòÉ
Purpose
Copies data from one attribute structure instance to another.
Format
#include <dce/sec_attr_util.h>
void sec_attr_util_alloc_copy(
idl_void_p_t *(*allocate) (unsigned32 size),
sec_attr_t *from,
sec_attr_t *to,
error_status_t *status);
Parameters
Input
allocate An allocation routine that returns a pointer of type
idl_void_p_t to a space of size size.
size A 32-bit unsigned integer, used as the parameter for
the allocate routine, that specifies the size of the
space to be allocated.
from A pointer to a sec_attr_t structure containing an
attribute instance that is to be copied.
Output
to A pointer to an allocated sec_attr_t structure that
contains the copied attribute instance.
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns an error.
Usage
The sec_attr_util_alloc_copy routine allocates the necessary
subfields of the destination sec_attr_t structure and copies the
corresponding data from the source sec_attr_t structure.
Related Information
Routines:
sec_attr_util_free
Files:
/usr/include/dce/sec_attr_util.idl - The idl file from which
dce/sec_attr_util.h was derived.
ΓòÉΓòÉΓòÉ 8.3.10. sec_attr_util_free ΓòÉΓòÉΓòÉ
Purpose
Frees the underlying storage in a sec_attr_t structure that was
allocated by the sec_attr_util_alloc_copy routine.
Format
#include <dce/sec_attr_util.h>
void sec_attr_util_free(
void (*deallocate) (void *ptr),
sec_attr_t *attr);
Parameters
Input
deallocate A memory deallocation routine that frees a sec_attr_t
function ptr to a structure allocated by the
sec_attr_util_alloc_copy routine.
Input/Output
attr A pointer to an attribute instance of sec_attr_t type.
Usage
The sec_attr_util_free routine frees a sec_attr_t structure that was
allocated by the sec_attr_util_alloc_copy routine.
Related Information
Routines:
sec_attr_util_alloc_copy
Files:
/usr/include/dce/sec_attr_util.idl - The idl file from which
dce/sec/attr_util.h was derived.
ΓòÉΓòÉΓòÉ 8.3.11. sec_attr_util_inst_free ΓòÉΓòÉΓòÉ
Purpose
Frees non-null pointers within an attribute instance, including the
pointer to the attribute structure.
Format
#include <dce/sec_attr_util.h>
void sec_attr_util_inst_free(
sec_attr_t **attr_ptr);
Parameters
Input/Output
attr_ptr A pointer to an allocated and partially or fully
initialized sec_attr_t structure. On output, this
pointer is NULL.
Usage
The sec_attr_util_inst_free routine frees every non-NULL pointer in
the attribute instance pointed to by attr_ptr and sets the attr_p
pointer to NULL. Note that this data structure might have been only
partially initialized.
Use this routine to free the space allocated by the following
routines:
sec_rgy_attr_lookup_by_id
sec_rgy_attr_lookup_by_name
sec_rgy_attr_lookup_no_expand
Related Information
Routines:
sec_attr_util_inst_free_ptrs
sec_attr_util_alloc_copy
sec_rgy_attr_lookup_by_id
sec_rgy_attr_lookup_by_name
sec_rgy_attr_lookup_no_expand
Files:
/urs/include/dce/sec_attr_util.idl - The idl file from which
dce/sec_attr_util.h was derived.
ΓòÉΓòÉΓòÉ 8.3.12. sec_attr_util_inst_free_ptrs ΓòÉΓòÉΓòÉ
Purpose
Frees pointers in a sec_attr_t structure.
Format
#include <dce/sec_attr_util.h>
void sec_attr_util_inst_free_ptrs(
sec_attr_t *attr_ptr);
Parameters
Input
attr_ptr A character string (type sec_attr_t) that points to an
allocated and potentially initialized sec_attr_t
structure.
Usage
The sec_attr_util_inst_free_ptrs routine frees every non-NULL pointer
in the attribute instance pointed to by attr_ptr but it does not free
itself.
Notes
1. Use this routine only in client applications.
2. Do not use this routine if you are using the
rpc_ss_enable_allocate routine.
3. This data structure might have been only partially initialized.
4. The attr_ptr pointer itself is NOT freed.
Related Information
Routines:
sec_attr_util_inst_free
sec_rgy_attr_lookup_by_id
sec_rgy_attr_lookup_by_name
sec_rgy_attr_lookup_no_expand
Files:
\usr\include\dce\sec_attr_util.idl - The idl file from which
dce/sec_attr_util.h was derived.
ΓòÉΓòÉΓòÉ 8.3.13. sec_attr_util_sch_ent_free ΓòÉΓòÉΓòÉ
Purpose
Frees non-null pointers within a schema entry, including the pointer
to the schema entry.
Format
#include <dce/sec_attr_util.h>
void sec_attr_util_sch_ent_free(
sec_attr_schema_entry_t **schema_ptr);
Parameters
Input/Output
schema_ptr A pointer to a partially or fully initialized
sec_attr_schema_entry_t structure. On output, the
internal pointers and the schema_ptr itself are freed.
Usage
The sec_attr_util_sch_ent_free routine frees every non-null pointer
in the schema entry pointed to by the schema_ptr as well as the
schema_ptr itself. Note that this data structure might have been only
partially initialized.
Use this routine to free the space allocated by the
sec_rgy_attr_sch_lookup_by_id and sec_rgy_attr_sch_lookup_by_name
routines.
Related Information
Routines:
sec_attr_util_inst_free_ptrs
sec_rgy_attr_sch_lookup_by_id
sec_rgy_attr_sch_lookup_by_name
ΓòÉΓòÉΓòÉ 8.3.14. sec_attr_util_sch_ent_free_ptrs ΓòÉΓòÉΓòÉ
Purpose
Frees non-null pointers in a schema entry.
Format
#include <dce/sec/attr_util.h>
void sec_attr_util_sch_ent_free_ptrs(
sec_attr_schema_entry_t *schema_ptr);
Parameters
Input/Output
schema_ptr A pointer to an allocated and potentially initialized
sec_attr_schema_entry_t structure. On output, internal
pointers are freed.
Usage
The sec_attr_util_sch_ent_free_ptrs routine frees every non-null
pointer in the schema entry pointed to by schema_ptr. The schema_ptr
pointer itself is not freed. Note that this data structure may have
been only partially initialized.
Use this routine to free the space allocated by the
sec_rgy_attr_sch_lookup_by_id and sec_rgy_attr_sch_lookup_by_name
routines.
Related Information
Routines:
sec_attr_util_inst_free_ptrs
sec_rgy_attr_sch_lookup_by_id
sec_rgy_attr_sch_lookup_by_name
sec_attr_util_sch_ent_free
Files:
/usr/include/dce/sec_attr_util.idl - The idl file from which
dce/sec_attr_util.h was derived.
ΓòÉΓòÉΓòÉ 8.3.15. sec_attr_util_sch_free_acl_mgrs ΓòÉΓòÉΓòÉ
Purpose
Frees non-null pointers in the acl_mgr_set field of a schema entry.
Format
#incude <dce/sec_attr_util.h>
void sec_attr_util_sch_free_acl_mgrs(
sec_attr_schema_entry_t *sec_sch_entry_p);
Parameters
Input/Output
sec_sch_entry_p On input, a pointer to an allocated and potentially
initialized sec_attr_shema_entry_t schema. On output,
acl_mgr_set pointers are freed and set to NULL.
Usage
The sec_attr_util_sch_free_acl_mgrs routine frees and sets to NULL
every non-null pointer in the acl_mgr_set field of the schema entry
pointed to by sec_sch_entry_p.
Related Information
Files:
\usr\include\dce\sec_attr_util.idl - The idl file from which
dce\sec_attr_util.h was derived.
ΓòÉΓòÉΓòÉ 8.3.16. sec_attr_util_sch_free_binding ΓòÉΓòÉΓòÉ
Purpose
Frees non-null pointers in the trig_binding field of the
sec_attr_schema_entry_t schema.
Format
#incude <dce/sec_attr_util.h>
void sec_attr_util_sch_free_binding(
sec_attr_schema_entry_t *sec_sch_entry_p);
Parameters
Input
sec_sch_entry_p On input, points to an allocated and potentially
initialized sec_attr_schema_entry_t schema. On output,
trig_binding pointers are freed and set to NULL.
Usage
The sec_attr_util_sch_free_binding routine frees and sets to NULL
every non-null pointer in the trig_binding field of the schema entry
pointed to by sec_sch_entry_p.
Related Information
Files:
\usr\include\dce\sec_attr_util.idl - The idl file from which
dce\sec_attr_util.h was derived.
ΓòÉΓòÉΓòÉ 8.3.17. sec_rgy_attr_cursor_alloc ΓòÉΓòÉΓòÉ
Purpose
Allocates resources to a cursor used by the sec_rgy_attr_lookup_by_id
routine.
Format
#include <dce/sec_rgy_attr.h>
void sec_rgy_attr_cursor_alloc(
sec_attr_cursor_t *cursor,
error_status_t *status);
Parameters
Output
cursor A pointer to a sec_attr_cursor_t
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns no such object.
Usage
The sec_rgy_attr_cursor_alloc routine allocates resources to a cursor
used with the sec_rgy_attr_lookup_by_id routine. This routine, which
is a local operation, does not initialize cursor.
The sec_rgy_attr_cursor_init routine, which makes a remote call and
allocates and initializes the cursor. In addition,
sec_rgy_attr_cursor_init returns the total number of attributes
attached to the object as an output parameter;
sec_rgy_attr_cursor_alloc does not.
Related
Information. Routines:
sec_rgy_attr_cursor_init
sec_rgy_attr_cursor_release
sec_rgy_attr_cursor_reset
sec_rgy_attr_lookup_by_id
Files:
dcelocal\include\dce\sec_attr_base.idl - The idl file from which
dce\sec_attr_base.h was derived.
ΓòÉΓòÉΓòÉ 8.3.18. sec_rgy_attr_cursor_init ΓòÉΓòÉΓòÉ
Purpose
Initializes a cursor used by the sec_rgy_attr_lookup_by_id routine.
Format
#include <dce/sec_rgy_attr.h>
void sec_rgy_attr_cursor_init (
sec_rgy_handle_t context,
sec_rgy_domain_t name_domain,
sec_rgy_name_t name,
unsigned32 *cur_num_attrs,
sec_attr_cursor_t *cursor,
error_status_t *status);
Parameters
Input
context An opaque handle bound to a registry server. Use
sec_rgy_site_open to acquire a bound handle.
name_domain A value of type sec_rgy_domain_t that identifies the
registry domain where the object specified by name
resides. The valid values are:
sec_rgy_domain_person The name identifies a
principal.
sec_rgy_domain_group The name identifies a
group.
sec_rgy_domain_org The name identifies an
organization.
This parameter is ignored if name is policy or replist.
name A pointer to a sec_rgy_name_t character string
containing the name of the person, group, or
organization to which the attribute to be scanned is
attached.
Output
cur_num_attrs A pointer to an unsigned 32-bit integer that specifies
the number of attributes currently attached to the
object.
cursor A pointer to a sec_rgy_cursor_t positioned at the first
attribute in the list of the object's attributes.
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns no such object.
Usage
The sec_rgy_attr_cursor_init routine initializes a cursor of type
sec_attr_cursor_t (used with the sec_rgy_attr_lookup_by_id routine)
and initializes the cursor to the first attribute in the specified
object's list of attributes. This routine also supplies the total
number of attributes attached to the object as part of its output.
The cursor allocation is a local operation. The cursor initialization
is a remote operation and makes a remote call to the Registry.
Use the sec_rgy_attr_cursor_release routine to release all resources
allocated to a sec_attr_cursor_t cursor.
Permissions Required
The sec_rgy_attr_cursor_init routine requires at least one permission
(of any type) on the person, group, or organization to which the
attribute to be scanned is attached.
Related Information
Routines:
sec_rgy_attr_lookup_by_id
sec_rgy_attr_cursor_release
Files:
dcelocal\include\dce\sec_rgy_attr.idl - The idl file from which
dce\sec_rgy_attr.h was derived.
ΓòÉΓòÉΓòÉ 8.3.19. sec_rgy_attr_cursor_release ΓòÉΓòÉΓòÉ
Purpose
Releases a cursor of type sec_attr_cursor_t that was allocated with
the sec_rgy_attr_cursor_init or sec_rgy_attr_cursor_alloc routine.
Format
#include <dce/sec_rgy_attr.h>
void sec_rgy_attr_cursor_release (
sec_attr_cursor_t *cursor,
error_status_t *status);
Parameters
Input/Output
cursor As an input parameter, a pointer to an uninitialized
cursor of type sec_attr_cursor_t. As an output
parameter, a pointer to an uninitialized cursor of type
sec_attr_cursor_t with all resources released.
Output
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns No such object.
Usage
The sec_rgy_attr_cursor_release routine releases all resources
allocated to a sec_attr_cursor_t by the sec_rgy_attr_cursor_init or
sec_rgy_attr_cursor_alloc routine.
This is a local operation and makes no remote calls.
Related Information
Routines:
sec_rgy_attr_cursor_init
sec_rgy_attr_cursor_alloc
sec_rgy_attr_lookup_by_id
Files:
dcelocal\include\dce\sec_rgy_attr.idl - The idl file from which
dce\sec_rgy_attr.h was derived.
ΓòÉΓòÉΓòÉ 8.3.20. sec_rgy_attr_cursor_reset ΓòÉΓòÉΓòÉ
Purpose
Reinitializes a cursor that has been allocated with either
sec_rgy_attr_cursor_init or sec_rgy_attr_cursor_alloc.
Format
#include <dce/sec_rgy_attr.h>
void sec_rgy_attr_cursor_reset (
sec_attr_cursor_t *cursor,
error_status_t *status);
Parameters
Input/Output
cursor A pointer to sec_attr_cursor_t. As an input parameter,
an initialized cursor. As an output parameter, cursor
is reset to the first attribute in the schema.
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns an error.
Usage
The sec_rgy_attr_cursor_reset routine resets a sec_attr_cursor_t that
has been allocated by either a sec_rgy_attr_cursor_init or
sec_rgy_attr_cursor_alloc routine. The reset cursor can then be used
to process a new sec_rgy_attr_lookup_by_id query by reusing the
cursor instead of releasing and re-allocating it. This is a local
operation and makes no remote calls.
Related Information
Routines
sec_rgy_attr_cursor_init
sec_rgy_attr_cursor_alloc
sec_rgy_attr_lookup_by_id
Files:
dcelocal\include\dce\sec_rgy_attr.idl - The idl file from which
dce\sec_rgy_attr.h was derived.
ΓòÉΓòÉΓòÉ 8.3.21. sec_rgy_attr_delete ΓòÉΓòÉΓòÉ
Purpose
Deletes specified attributes for a specified object.
Format
#include <dce/sec_rgy_attr.h>
void sec_rgy_attr_delete (
sec_rgy_handle_t context,
sec_rgy_domain_t name_domain,
sec_rgy_name_t name,
unsigned32 num_to_delete,
sec_attr_t attrs[],
signed32 *failure_index,
error_status_t *status)
Parameters
Input
context An opaque handle bound to a registry server. Use
sec_rgy_site_open to acquire a bound handle.
name_domain A value of type sec_rgy_domain_t that identifies the
registry domain where the object identified by name
resides. The valid values are as follows:
sec_rgy_domain_person The name identifies a
principal.
sec_rgy_domain_group The name identifies a
group.
sec_rgy_domain_org The name identifies an
organization.
This parameter is ignored if name is policy or replist.
name A character string of type sec_rgy_name_t specifying
the name of the person, group, or organization to which
the attributes are attached.
num_to_delete A 32-bit integer that specifies the number of elements
in the attrs array. This integer must be greater than
0.
attrs[]. An array of values of type sec_attr_t that specifies
the attribute instances to be deleted. The size of the
array is determined by num_to_delete.
Output
failure_index In the event of an error, failure_index is a pointer to
the element in the in_attrs array that caused the
update to fail. If the failure cannot be attributed to
a specific attribute, the value of failure_index is -1.
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns one of the following errors:
unauthorized
database read only
server unavailable
invalid/unsupported attribute type
site read only
Usage
The sec_rgy_attr_delete routine deletes attributes. This is an atomic
operation: if the deletion of any attribute in the attrs array
fails, all deletions are stopped. The attribute causing the delete
to fail is identified in failure_index. If the failure cannot be
attributed to a given attribute, failure_index contains -1.
The attrs array, which specifies the attributes to be deleted,
contains values of type sec_attr_t. These values consist of:
attr_id A UUID that identifies the attribute type.
attr_value A value of sec_attr_value_t that specifies the
attribute's encoding type and values.
To delete attributes that are not multivalued and to delete all
instances of a multivalued attribute, an attribute UUID is all that
is required. For these attribute instances, supply the attribute UUID
in the input array and set the attribute encoding (in
sec_attr_encoding_t) to sec_attr_enc_void.
To delete a specific instance of a multivalued attribute, supply the
UUID and value that uniquely identify the multivalued attribute
instance in the input array.
Note that if the deletion of any attribute instance in the array
fails, all fail. However, to help pinpoint the cause of the failure,
the routine identifies the first attribute whose deletion failed in a
failure index by array element number.
Permissions Required
The sec_rgy_attr_delete routine requires the delete permission set
for each attribute type identified in the attrs array. These
permissions are defined as part of the ACL manager set in the schema
entry for the attribute type.
Related Information
Routines.:
sec_rgy_attr_update
Files:
dcelocal\include\dce\sec_rgy_attr.idl - The idl file from which
dce\sec_rgy_attr.h was derived.
ΓòÉΓòÉΓòÉ 8.3.22. sec_rgy_attr_get_effective ΓòÉΓòÉΓòÉ
Purpose
Reads effective attributes by ID.
Format
#include <dce/sec_rgy_attr.h>
void sec_rgy_attr_get_effective (
sec_rgy_handle_t context,
sec_rgy_domain_t name_domain,
sec_rgy_name_t name,
unsigned32 num_attr_keys,
sec_attr_t attr_keys[],
sec_attr_vec_t *attr_list,
error_status_t *status)
Parameters
Input
context An opaque handle bound to a registry server. Use
sec_rgy_site_open to acquire a bound handle.
name_domain A value of type sec_rgy_domain_t that identifies the
domain where the object identified by name resides. The
valid values are:
sec_rgy_domain_person The name identifies a
principal.
sec_rgy_domain_group The name identifies a
group.
sec_rgy_domain_org The name identifies an
organization.
This parameter is ignored if name is policy or replist.
name A pointer to a sec_rgy_name_t character string
containing the name of the person, group, or
organization to which the attribute to be scanned is
attached.
num_attr_keys An unsigned 32-bit integer that specifies the number of
elements in the attr_keys array. If num_attr_keys is
set to 0, all of the effective attributes that the
caller is authorized to see are returned.
attr_keys[] An array of values of type sec_attr_t that specify the
UUIDs of the attributes to be returned, if they are
effective. If the attribute type is associated with a
query attribute trigger, the sec_attr_t attr_value
field can be used to pass in optional information
required by the attribute trigger query. If no
information is to be passed in the attr_value field
(whether the type indicates an attribute trigger query
or not), set the attribute's encoding type to
sec_rgy_attr_enc_void. The size of the attr_keys array
is determined by the num_attr_keys parameter.
Output
attr_list A pointer to an attribute vector allocated by the
server containing all of the effective attributes
matching the search criteria (defined in num_attr_keys
or attr_keys ). The server allocates a buffer large
enough to return all the requested attributes so that
subsequent calls are not necessary.
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns an error.
Usage
The sec_rgy_attr_get_effective routine returns the UUIDs of the
effective attributes of a specified object. Effective attributes are
determined by setting the schema entry apply_defaults flag:
o If the flag is set to off, only the attributes directly attached
to the object are effective.
o If the flag is set to on, obtain the effective attributes by
completing the following steps for each attribute identified by
UUID in the attr_keys array:
1. If the object named by name is a principal and if the
requested attribute exists on the principal, that attribute
is effective and is returned. If it does not exist, the
search continues.
2. The next step in the search depends on the type of object:
- For principals with accounts:
a. The organization named in the principal's account
is examined to see if an attribute of the
requested type exists. If it does, it is
effective and is returned; then the search for
that attribute ends. If it does not exist, the
search for that attribute continues to the policy
object as described in the next step.
b. The registry policy object is examined to see if
an attribute of the requested type exists. If the
attribute exists, it is returned. If it does
not, a message indicating that no attribute of
the type exists for the object is returned.
- For principals without accounts, for groups, and for
organizations:
a. The registry policy object is examined to see if
an attribute of the requested type exists. If it
does, it is returned.
b. If it does not, a message indicating that no
attribute of the type exists for the object is
returned.
For multivalued attributes, the routine returns a sec_attr_t for each
value as an individual attribute instance. For attribute sets, the
routine returns a sec_attr_t for each member of the set; it does not
return the set instance.
If the attribute instance to be read is associated with a query
attribute trigger that requires additional information before it can
process the query request, use a sec_attr_value_t to supply the
requested information:
1. Set the sec_attr_encoding_t to an encoding type that is
compatible with the information required by the query attribute
trigger.
2. Set the sec_attr_value_t to hold the required information.
If the attribute instance to be read is not associated with a query
trigger or additional information is not required by the query
trigger, only an attribute UUID is required. For these attribute
instances, supply the attribute UUID in the input array and set the
attribute encoding (in sec_attr_encoding_t) to sec_attr_enc_void.
If the requested attribute type is associated with a query trigger,
the value returned for the attribute is the binding (as set in the
schema entry) of the trigger server. The caller must bind to the
trigger server and pass the original input query attribute to the
sec_attr_trig_query routine in order to retrieve the attribute value.
Note: If the requested attribute type is associated with a query
trigger, the value returned for the attribute will be the
binding (as set in the schema entry) of the trigger server.
The caller must bind to the trigger server and pass the
orginal input query attribute to the sec_attr_trig_query call
in order to retrieve the attribute value.
Related Information
Routines:
sec_rgy_site_open
Files:
dcelocal \include\dce\sec_rgy_attr.idl - The idl file from which
dce\sec_rgy_attr.h was derived.
ΓòÉΓòÉΓòÉ 8.3.23. sec_rgy_attr_lookup_by_id ΓòÉΓòÉΓòÉ
Purpose
Reads a specified object's attributes, expanding attribute sets into
individual member attributes.
Format
#include <dce/sec_rgy_attr.h>
void sec_rgy_attr_lookup_by_id (
sec_rgy_handle_t context,
sec_rgy_domain_t name_domain,
sec_rgy_name_t name,
sec_attr_cursor_t *cursor,
unsigned32 num_attr_keys,
unsigned32 space_avail,
sec_attr_t attr_keys[],
unsigned32 *num_returned,
sec_attr_t attrs[],
unsigned32 *num_left,
error_status_t *status);
Parameters
Input
context An opaque handle bound to a registry server. Use
sec_rgy_site_open to acquire a bound handle.
name_domain A value of type sec_rgy_domain_t that identifies the
registry domain where the object specified by name
resides. The valid values are as follows:
sec_rgy_domain_person The name identifies a
principal.
sec_rgy_domain_group The name identifies a
group.
sec_rgy_domain_org The name identifies an
organization.
This parameter is ignored if name is policy or replist.
name A pointer to a sec_rgy_name_t character string
containing the name of the person, group, or
organization to which the attribute is attached.
num_attr_keys An unsigned 32-bit integer that specifies the number of
elements in the attr_keys array. Set this parameter to
0 to return all of the object's attributes that the
caller is authorized to see.
space_avail An unsigned 32-bit integer that specifies the size of
the attr_keys array.
attr_keys[] An array of values of type sec_attr_t that identify the
attribute type ID of the attribute instance to be
looked up. If the attribute type is associated with a
query attribute trigger, the attr_value field in
sec_attr_t can be used to pass in optional information
required by the attribute trigger query. If no
information is to be passed in the attr_value field
(whether the type indicates an attribute trigger query
or not), set the attribute's encoding type to
sec_rgy_attr_enc_void.
The size of the attr_keys array is determined by the
num_attr_keys parameter.
Input/Output
cursor A pointer to a sec_attr_cursor_t. As an input
parameter, cursor is a pointer to a sec_attr_cursor_t
initialized by a sec_rgy_attr_srch_cursor_init routine.
As an output parameter, cursor is a pointer to a
sec_attr_cursor_t that is positioned past components
returned in this routine.
Output
num_returned A pointer to a 32-bit unsigned integer that specifies
the number of attribute instances returned in the attrs
array.
attrs[] An array of values of type sec_attr_t that contains the
attributes retrieved by UUID. The size of the array is
determined by space_avail and the length by
num_returned.
num_left A pointer to a 32-bit unsigned integer that supplies
the number of attributes that were found but that could
not be returned because of space constraints in the
attrs buffer. To ensure that all the attributes are
returned, increase the size of the attrs array by
increasing the size of space_avail and num_returned.
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok, or, if
the requested attributes were not available, it returns
the message not_all_available. Otherwise, it returns
one of the following errors:
unauthorized
registry server unavailable
trigger server unavailable
Usage
The sec_rgy_attr_lookup_by_id routine reads those attributes
specified by UUID for an object specified by name. This routine is
similar to the sec_rgy_attr_lookup_no_expand routine with one
exception: for attribute sets, the sec_rgy_attr_lookup_no_expand
routine returns a sec_attr_t for the set instance only; it does not
expand the set and return a sec_attr_t for each member in the set.
This routine expands attribute sets and returns a sec_attr_t for each
member in the set.
If the num_attr_keys parameter is set to 0, all of the object's
attributes that the caller is authorized to see are returned. This
routine is useful for access by applications.
For multivalued attributes, the routine returns a sec_attr_t for each
value as an individual attribute instance. For attribute sets, the
routine returns a sec_attr_t for each member of the set; it does not
return the set instance.
The attr_keys array, which specifies the attributes to be returned,
contains values of type sec_attr_t. These values consist of:
attr_id A UUID that identifies the attribute type
attr_value A value of sec_attr_value_t that specifies the attribute's
encoding type and values
Use the attr_id field of each attr_keys array element to specify the
UUID that identifies the attribute type to be returned.
If the attribute instance to be read is not associated with a query
trigger or no additional information is required by the query
trigger, only an attribute UUID is required. For these attribute
instances, supply the attribute UUID in the input array and set the
attribute encoding (in sec_attr_encoding_t) to sec_attr_enc_void.
If the attribute instance to be read is associated with a query
attribute trigger that requires additional information before it can
process the query request, use a sec_attr_value_t to supply the
requested information:
1. Set the sec_attr_encoding_t to an encoding type that is
compatible with the information required by the query attribute
trigger.
2. Set the sec_attr_value_t to hold the required information.
Note that if you set num_attr_keys to zero to return all of the
object's attributes and an attribute is associated with a query
attribute trigger, the attribute trigger is called with no input
attribute information (that would normally have been passed in with
the attr_value field).
The cursor parameter specifies a cursor of type sec_attr_cursor_t
initialized to the starting point in the attribute list for
processing the query. Use the sec_attr_cursor_init routine to
initialize cursor. If cursor is uninitialized, the server begins
processing the query at the first attribute that satisfies the search
criteria.
The num_left parameter contains the number of attributes that were
found but could not be returned because of space constraints of the
attrs array. (Note that this number may be inaccurate if the target
server allows updates between successive queries.) To obtain all of
the remaining attributes, set the size of the attrs array so that it
is large enough to hold the number of attributes listed in num_left.
Notes
You must free the space allocated for each sec_attr_t pointer type
used by this routine. Some encoding types, for example printstrings
and bindings, allocate a large chunk of memory for each pointer each
time this routine is called. Failure to release this space can cause
a "memory leak", especially if you call this routine several times.
You can free the space by passing each sec_attr_t pointer to the
sec_attr_util_inst_free_ptrs or the sec_attr_util_inst_free routine.
If a requested attribute type is associated with a query trigger,
that attr_key will be passed as input to the sec_attr_trig_query
operation and the output of that call will be included in the output
attrs array. If num_attr_keys is zero, that is, return all
attributes, and an attribute is associated with a query trigger, the
trigger will be called with no input attribute information (that
would normally have been passed in by way of the attr_key value
field).
Permissions Required
The sec_rgy_attr_lookup_by_id routine requires the query permission
set for each attribute type identified in the attr_keys array. These
permissions are defined as part of the ACL manager set in the schema
entry of each attribute type.
Related Information
Routines:
sec_attr_util_inst_free_ptrs
sec_attr_util_inst_free
sec_rgy_attr_cursor_init
sec_rgy_attr_lookup_by_name
sec_rgy_attr_lookup_no_expand
sec_rgy_attr_sch_cursor_init
Files:
dcelocal\include\dce\sec_rgy_attr.idl - The idl file from which
dce\sec_rgy_attr.h was derived.
ΓòÉΓòÉΓòÉ 8.3.24. sec_rgy_attr_lookup_by_name ΓòÉΓòÉΓòÉ
Purpose
Reads a single attribute instance for a specific object.
Format
#include <dce/sec_rgy_attr.h>
void sec_rgy_attr_lookup_by_name(
sec_rgy_handle_t context,
sec_rgy_domain_t name_domain,
sec_rgy_name_t name,
unsigned_char_t *attr_name,
sec_attr_t *attr,
error_status_t *status);
Parameters
Input
context An opaque handle bound to a registry server. Use
sec_rgy_site_open to acquire a bound handle.
name_domain A value of type sec_rgy_domain_t that identifies the
registry domain where the object specified by name
resides. The valid values are:
sec_rgy_domain_person The name identifies a
principal.
sec_rgy_domain_group The name identifies a
group.
sec_rgy_domain_org The name identifies an
organization.
This parameter is ignored if name is policy or replist.
name A pointer to a sec_rgy_name_t character string
containing the name of the person, group, or
organization to which the attribute is attached.
attr_name A pointer to a character string that specifies the name
of the attribute to be retrieved.
Output
attr A pointer to a sec_attr_t that contains the first
instance of the named attribute.
status A pointer to the completion status. The completion
status can be error_status_ok if all instances of the
value are returned with no errors. Otherwise, status
can be one of the following:
o unauthorized
o registry server unavailable
o trigger server unavailable
Usage
The sec_rgy_attr_lookup_by_name routine returns the named attribute
for a named object. This routine is useful for an interactive editor.
For multivalued attributes, this routine returns the first instance
of the attribute. To retrieve every instance of the attribute, use
the sec_rgy_attr_lookup_by_id routine, supplying the attribute UUID
returned in the attr parameter.
For attribute sets, the routine returns the attribute set instance,
not the member instances. To retrieve all members of the set, use the
sec_rgy_attr_lookup_by_id routine, supplying the attribute set UUID
returned in the attr parameter.
Notes
1. You must free the space allocated for each sec_attr_t pointer
type used by this routine. Some encoding types, for example
printstrings and bindings, allocate a large chunk of memory for
each pointer each time this routine is called. Failure to
release this space can cause a memory leak, especially if you
call this routine several times. You can free the space by
passing each sec_attr_t pointer to the
sec_attr_util_inst_free_ptrs or the sec_attr_util_inst_free
routine.
2. This routine does not provide for input data to an attribute
trigger query operation. If the named attribute is associated
with a query attribute trigger, the attribute trigger is called
with no input attribute value information.
Permissions Required
The sec_rgy_attr_lookup_by_name routine requires the query permission
set for the attribute type of the attribute instance identified by
attr_name. These permissions are defined as part of the ACL manager
set in the schema entry of each attribute type.
Related Information
Routines: sec_rgy_site_open
sec_attr_util_inst_free_ptrs
sec_attr_util_inst_free
sec_rgy_attr_lookup_by_id
sec_rgy_attr_lookup_no_expand
Files:
dcelocal\include\dce\sec_rgy_attr.idl - The idl file from which
dce\sec_rgy_attr.h was derived.
ΓòÉΓòÉΓòÉ 8.3.25. sec_rgy_attr_lookup_no_expand ΓòÉΓòÉΓòÉ
Purpose
Reads a specified object's attributes without expanding attribute
sets into individual member attributes.
Format
#include <dce/sec_rgy_attr.h>
void sec_rgy_attr_lookup_no_expand
sec_rgy_handle_t context,
sec_rgy_domain_t name_domain,
sec_rgy_name_t name,
sec_attr_cursor_t *cursor,
unsigned32 num_attr_keys,
unsigned32 space_avail,
sec_attr_t attr_keys[],
unsigned32 *num_returned,
sec_attr_t attr_sets[],
unsigned32 *num_left,
error_status_t status;
Parameters
Input
context An opaque handle bound to a registry server. Use
sec_rgy_site_open to acquire a bound handle.
name_domain A value of type sec_rgy_domain_t that identifies the
domain where the named object resides. The valid values
are:
sec_rgy_domain_principal The name identifies a
principal.
sec_rgy_domain_group The name identifies a
group.
sec_rgy_domain_org The name identifies an
organization.
This parameter is ignored if name is policy or replist.
name A pointer to a sec_rgy_name_t character string that
contains the name of the person, group, or organization
to which the attribute is attached.
num_attr_keys An unsigned 32-bit integer that specifies the number of
elements in the attr_keys array. If num_attr_keys is
set to 0, all attribute sets that the caller is
authorized to see are returned.
space_avail An unsigned 32-bit integer that specifies the size of
the attrs_sets array.
attr_keys[] An array of values of type sec_attr_t that specify the
UUIDs of the attribute sets to be returned. The size of
the attr_keys array is determined by the num_attr_keys
parameter.
Input/Output
cursor A pointer to a sec_attr_cursor_t. As an input
parameter, cursor is a pointer to a sec_attr_cursor_t
that is initialized by the sec_rgy_attr_cursor_init. As
an output parameter, cursor is a pointer to a
sec_attr_cursor_t that is positioned past the attribute
sets returned in this routine.
Output
num_returned A pointer to a 32-bit integer that specifies the number
of attribute sets returned in the attrs array.
attr_sets[] An array of values of type sec_attr_t that contains the
attribute sets retrieved by UUID. The size of the array
is determined by space_avail and the length by
num_returned.
num_left A pointer to a 32-bit unsigned integer that supplies
the number of attribute sets that were found but that
could not be returned because of space constraints in
the attr_sets buffer. To ensure that all the attributes
are returned, increase the size of the attr_sets array
by increasing the size of space_avail and num_returned.
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns one of the following errors:
unauthorized
registry server unavailable
invalid/unsupported attribute type
Usage
The sec_rgy_attr_lookup_no_expand routine reads attribute sets. This
routine is similar to the sec_rgy_attr_lookup_by_id routine, with one
exception: for attribute sets, the sec_rgy_attr_lookup_by_id routine
expands attribute sets and returns a sec_attr_t for each member in
the set. This routine does not. Instead, it returns a sec_attr_t
for the set instance only. The sec_rgy_attr_lookup_no_expand routine
is useful for access by applications.
The cursor parameter is a cursor of type sec_attr_cursor_t that
establishes the point in the attribute set list where the server
should start processing the query. Use the sec_rgy_attr_cursor_init
routine to initialize cursor. If cursor is uninitialized, the server
begins processing the query with the first attribute that satisfies
the search criteria.
The num_left parameter contains the number of attribute sets that
were found but that could not be returned because of space
constraints of the attr_sets array. (Note that this number may be
inaccurate if the target server allows updates between successive
queries.) To obtain all of the remaining attribute sets, set the size
of the attr_sets array so that it is large enough to hold the number
of attributes listed in num_left.
Notes You must free the space allocated for each sec_attr_t pointer
type used by this routine. Some encoding types, for example
printstrings and bindings, allocate a large chunk of memory
for each pointer each time this routine is called. Failure to
release this space can cause a memory leak, especially if you
call this routine several times. You can free the space by
passing each sec_attr_t pointer to the
sec_attr_util_inst_free_ptrs or the sec_attr_util_inst_free
routine.
If the requested attribute type is associated with a query trigger,
the value returned for the attribute is the binding (as set in the
schema entry) of the trigger server. The caller must bind to the
trigger server and pass the original input query attribute to the
sec_attr_trig_query call in order to retrieve the attribute value.
Permissions Required
The sec_rgy_attr_lookup_no_expand routine requires the query
permission set for each attribute type identified in the attr_keys[]
array. These permissions are defined as part of the ACL manager set
in the schema entry of each attribute type.
Related Information
Routines: sec_attr_util_inst_free_ptrs
sec_attr_util_inst_free
sec_rgy_attr_cursor_init
sec_rgy_attr_lookup_by_id
sec_rgy_attr_lookup_by_name
sec_rgy_site_open
Files:
dcelocal\include\dce\sec_rgy_attr.idl - The idl file from which
dce\sec_rgy_attr.h was derived.
ΓòÉΓòÉΓòÉ 8.3.26. sec_rgy_attr_sch_aclmgr_strings ΓòÉΓòÉΓòÉ
Purpose
Returns printable ACL strings associated with an ACL manager
protecting a bound-to-schema object.
Format
#include <dce/dce_attr_base.h>
void sec_rgy_attr_sch_aclmgr_strings(
sec_rgy_handle_t context,
sec_attr_component_name_t schema_name,
uuid_t *acl_mgr_type,
unsigned32 size_avail,
uuid_t *acl_mgr_type_chain,
sec_acl_printstring_t *acl_mgr_info,
boolean32 *tokenize,
unsigned32 *total_num_printstrings,
unsigned32 *size_used,
sec_acl_printstring_t permstrings[],
error_status_t *status);
Parameters
Input
context An opaque handle bound to a registry server. Use
sec_rgy_site_open to acquire a bound handle.
schema_name A value of type sec_attr_component_name_t that
specifies the name of the schema object pointed to by
context.
acl_manager_type A pointer to the UUID identifying the type of the
ACL manager in question. There may be more than one
type of ACL manager protecting the schema object whose
ACL is bound to the input handle. Use this parameter to
distinguish them. Use sec_rgy_attr_sch_get_acl_mgrs to
acquire a list of the manager types protecting a given
schema object.
size_avail An unsigned 32-bit integer containing the allocated
length of the permstrings array.
Output
acl_mgr_type_chain If the target object ACL contains more than 32
permission bits, chains of manager types are used: each
manager type holds one 32-bit segment of permissions.
The UUID returned in acl_mgr_type_chain refers to the
next ACL manager in the chain. If there are no more ACL
managers in the chain, uuid_nil is returned.
acl_mgr_info A pointer to a print string that contains the ACL
manager type's name, help information, and set of
supported of permission bits.
tokenize A pointer to a variable that specifies whether print
strings are passed separately:
o TRUE indicates that the print strings must be
printed or passed separately.
o FALSE indicates that the print strings are
unambiguous and can be concatenated without
confusion when printed.
total_num_printstrings A pointer to an unsigned 32-bit integer
containing the total number of permission entries
supported by this ACL manager type.
size_used A pointer to an unsigned 32-bit integer containing the
number of permission entries returned in the
permstrings array.
permstrings[] An array of print strings of type
sec_acl_printstring_t. Each entry of the array is a
structure containing the following three components:
printstring A character string of maximum
length sec_acl_printstring_len
describing the printable
representation of a specified
permission.
helpstring A character string of maximum
length
sec_acl_printstring_help_len
containing some text that can be
used to describe the specified
permission.
permissions A sec_acl_permset_t permission set
describing the permissions that
are represented with the companion
print string.
The array consists of one entry for each permission
supported by the ACL manager identified by
acl_mgr_type.
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns one of the following errors:
sec_attr_unauthorized
sec_attr_svr_unavailable
sec_attr_no_memory
Usage
The sec_rgy_attr_sch_aclmgr_strings routine returns an array of
printable representations (called print strings) for each permission
bit or combination of permission bits that the specified ACL manager
supports. The ACL manager type specified by acl_mgr_type must be one
of the types protecting the schema object bound to by context.
In addition to returning the print strings, this routine also returns
instructions about how to print the strings in the tokenize variable.
If this variable is set to FALSE, the print strings can be
concatenated. If it is set to TRUE, the print strings cannot be
concatenated. For example, print strings of r and w can be
concatenated as rw without any confusion. However, print strings
containing whole words such as read or write should not be
concatenated.
ACL managers often define aliases for common permission combinations.
By convention, simple entries are at the beginning of the permstrings
array, and combinations are at the end.
Permissions Required
The sec_rgy_attr_sch_aclmgr_strings routine requires the r permission
on the attr_schema object.
Related Information
Routines:
sec_rgy_attr_sch_get_acl_mgrs
sec_rgy_site_open
Files:
dcelocal\include\dce\sec_rgy_attr_sch.idl - The idl file from which
dce\sec_rgy_attr_sch.h was derived.
ΓòÉΓòÉΓòÉ 8.3.27. sec_rgy_attr_sch_create_entry ΓòÉΓòÉΓòÉ
Purpose
Creates a schema entry.
Format
#include <dce/sec_rgy_attr_sch.h>
void sec_rgy_attr_sch_create_entry(
sec_rgy_handle_t context,
sec_attr_component_name_t schema_name,
sec_attr_schema_entry_t *schema_entry,
error_status_t *status);
Parameters
Input
context An opaque handle bound to a registry server. Use
sec_rgy_site_open to acquire a bound handle.
schema_name A value of type sec_attr_component_name_t that
specifies the name of the schema object to be created.
schema_entry A pointer to a sec_attr_schema_entry_t that contains
the schema entry values for the schema where the entry
is to be created.
Output
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns one of the following errors:
sec_attr_bad_name
sec_attr_bad_encoding_type
sec_attr_bad_acl_mgr_set
sec_attr_bad_acl_mgr_type
sec_attr_bad_permset
sec_attr_bad_intercell_action
sec_attr_trig_bind_info_missing
sec_attr_bad_bind_info
sec_attr_bad_bind_svr_name
sec_attr_bad_bind_prot_level
sec_attr_bad_bind_authn_svc
sec_attr_bad_bind_authz_svc
sec_attr_bad_uniq_query_accept
sec_attr_bad_scope
sec_attr_bad_comment
sec_attr_type_id_exists
sec_attr_name_exists
sec_attr_unauthorized
sec_attr_svr_read_only
sec_attr_svr_unavailable
sec_attr_no_memory
Usage
The sec_rgy_attr_sch_create_entry routine creates schema entries that
define attribute types.
Permissions Required
The sec_rgy_attr_sch_create_entry routine requires i permission on
the attr_schema object.
Related Information
Routines:
sec_rgy_attr_sch_delete_entry
sec_rgy_attr_sch_update_entry
sec_rgy_site_open
Files:
dcelocal\include\dce\sec_rgy_attr_sch.idl - The idl file from which
dce\sec_rgy_attr_sch.h was derived.
ΓòÉΓòÉΓòÉ 8.3.28. sec_rgy_attr_sch_cursor_alloc ΓòÉΓòÉΓòÉ
Purpose
Allocates resources to a cursor used with the
sec_rgy_attr_sch_cursor_alloc routine.
Format
#include <dce/sec_rgy_attr_sch.h>
void sec_rgy_attr_sch_cursor_alloc(
sec_attr_cursor_t *cursor,
error_status_t *status);
Parameters
Output
cursor A pointer to a sec_attr_cursor_t
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns sec_attr_no_memory.
Usage
The sec_rgy_attr_sch_cursor_alloc routine allocates resources to a
cursor used with the sec_rgy_attr_sch_scan routine. This routine,
which is a local operation, does not initialize cursor.
The sec_rgy_attr_sch_cursor_init routine, which makes a remote call,
allocates and initializes the cursor. In addition,
sec_rgy_attr_sch_cursor_init returns the total number of entries
found in the schema as an output parameter;
sec_rgy_attr_sch_cursor_alloc does not.
Related Information
Routines: sec_rgy_attr_sch_cursor_init
sec_rgy_attr_sch_cursor_release
sec_rgy_attr_sch_scan
Files:
dcelocal\include\dce\sec_rgy_attr_sch.idl - The idl file from which
dce\sec_rgy_attr_sch.h was derived.
ΓòÉΓòÉΓòÉ 8.3.29. sec_rgy_attr_sch_cursor_init ΓòÉΓòÉΓòÉ
Purpose
Initializes and allocates a cursor used by the sec_rgy_attr_sch_scan
routine.
Format
#include <dce/sec_rgy_attr_sch.h>
void sec_rgy_attr_cursor_init(
sec_rgy_handle_t context,
sec_attr_component_name_t schema_name,
unsigned32 *cur_num_entries,
sec_attr_cursor_t *cursor,
error_status_t *status);
Parameters
Input
context An opaque handle bound to a registry server. Use
sec_rgy_site_open to acquire a bound handle.
schema_name A value of type sec_attr_component_name_t that
specifies the name of the schema object to which cursor
is initialized.
Output
cur_num_entries A pointer to an unsigned 32-bit integer that
specifies the total number of entries contained in the
schema at the time of this call.
cursor A pointer to a cursor of type sec_attr_cursor_t that is
initialized to the first entry in the schema.
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns one of the following errors:
sec_attr_unauthorized
sec_attr_svr_unavailable
sec_attr_no_memory
Usage
The sec_rgy_attr_sch_cursor_init routine initializes and allocates
resources to a cursor used with the sec_rgy_attr_sch_scan routine.
This routine makes remote calls to initialize the cursor. To limit
the number of remote calls, use the sec_rgy_attr_sch_cursor_alloc
routine to allocate cursor, but not initialize it. Be aware, however,
that the sec_rgy_attr_sch_cursor_init routine supplies the total
number of entries found in the schema as an output parameter; the
sec_rgy_attr_sch_cursor_alloc routine does not.
If the cursor input to sec_rgy_attr_sch_scan has not been
initialized, the sec_rgy_attr_sch_scan routine initializes it; if it
has been initialized, sec_rgy_attr_sch_scan advances it.
Related Information
Routines: sec_rgy_attr_sch_cursor_release
sec_rgy_attr_sch_scan
sec_rgy_attr_sch_cursor_alloc
Files:
dcelocal\include\dce\sec_rgy_attr_sch.idl - The idl file from which
dce\sec_rgy_attr_sch.h was derived.
ΓòÉΓòÉΓòÉ 8.3.30. sec_rgy_attr_sch_cursor_release ΓòÉΓòÉΓòÉ
Purpose
Release states associated with a cursor used by the
sec_rgy_attr_sch_scan routine.
Format
#include <dce/sec_rgy_attr_sch.h>
void sec_rgy_attr_cursor_rel(
sec_attr_cursor_t *cursor,
error_status_t *status);
Parameters
Input/Output
cursor A pointer to a sec_attr_cursor_t. As an input
parameter, cursor must have been initialized to the
first entry in a schema. As an output parameter, cursor
is uninitialized with all resources released.
Output
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns an error.
Usage
The sec_rgy_attr_sch_cursor_init routine releases the resources
allocated to the cursor used by the sec_rgy_attr_sch_scan routine.
This routine is a local operation and makes no remote calls.
Related Information
Routines: sec_rgy_attr_sch_cursor_init
sec_rgy_attr_sch_cursor_alloc
sec_rgy_attr_sch_scan
Files:
dcelocal\include\dce\sec_rgy_attr_sch.idl - The idl file from which
dce\sec_rgy_attr_sch.h was derived.
ΓòÉΓòÉΓòÉ 8.3.31. sec_rgy_attr_sch_cursor_reset ΓòÉΓòÉΓòÉ
Purpose
Resets a cursor that has been allocated with either
sec_rgy_attr_sch_cursor_init or sec_rgy_attr_sch_cursor_alloc
routine.
Format
#include <dce/sec_rgy_attr_sch.h>
void dce_attr_cursor_reset(
sec_attr_cursor_t *cursor,
error_status_t *status);
Parameters
Input/Output
cursor A pointer to a sec_attr_cursor_t. As an input
parameter, an initialized cursor. As an output
parameter, cursor is reset to the first attribute in
the schema.
Output
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns sec_attr_bad_cursor.
Usage
The sec_rgy_attr_sch_cursor_reset routine resets to NULL a
sec_attr_cursor_t cursor that has been allocated by either
sec_rgy_attr_sch_cursor_init or sec_rgy_attr_sch_cursor_alloc. The
reset cursor can then be used to process a new sec_rgy_attr_sch_scan
query by reusing the cursor instead of releasing and re-allocating
it. This is a local operation and makes no remote calls.
Related Information
Routines:
sec_rgy_attr_sch_cursor_init
sec_rgy_attr_sch_cursor_alloc
sec_rgy_attr_sch_scan
Files:
dcelocal\include\dce\sec_rgy_ attr_sch.idl - The idl file from which
dce\sec_rgy_attr_sch.h was derived.
ΓòÉΓòÉΓòÉ 8.3.32. sec_rgy_attr_sch_delete_entry ΓòÉΓòÉΓòÉ
Purpose
Deletes a schema entry.
Format
#include <dce/sec_rgy_attr_sch.h>
void sec_rgy_attr_delete_entry(
sec_rgy_handle_t context,
sec_attr_component_name_t schema_name,
uuid_t *attr_id,
error_status_t *status);
Parameters
Input
context An opaque handle bound to a registry server. Use
sec_rgy_site_open to acquire a bound handle.
schema_name A value of type sec_attr_component_name_t that
specifies the name of the schema object to be created.
attr_id A pointer to a uuid_t that identifies the schema entry
to be deleted.
Output
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns one of the following errors:
sec_attr_sch_entry_not_found
sec_attr_unauthorized
sec_attr_svr_read_only
sec_attr_svr_unavailable
sec_attr_no_memory
Usage
The sec_rgy_attr_sch_delete_entry routine deletes a schema entry.
Because this is a radical operation that invalidates any existing
attributes of this type on objects dominated by the schema, access to
this operation should be severely limited.
Permissions Required
The sec_rgy_attr_sch_delete_entry routine requires the d permission
on the attr_schema object.
Related Information
Routines: sec_rgy_site_open
sec_rgy_attr_sch_create_entry
sec_rgy_attr_sch_update_entry
Files:
dcelocal\include\dce\sec_rgy_attr_sch.idl - The idl file from which
dce\sec_rgy_attr_sch.h was derived.
ΓòÉΓòÉΓòÉ 8.3.33. sec_rgy_attr_sch_get_acl_mgrs ΓòÉΓòÉΓòÉ
Purpose
Retrieves the manager types of the ACLs protecting the objects
dominated by a named schema.
Format
#include <dce/sec_rgy_attr_sch.h>
void sec_rgy_attr_get_acl_mgrs(
sec_rgy_handle_t context,
sec_attr_component_name_t schema_name,
unsigned32 size_avail,
unsigned32 *size_used,
unsigned32 *num_acl_mgr_types,
uuid_t acl_mgr_types[],
error_status_t *status);
Parameters
Input
context An opaque handle bound to a registry server. Use
sec_rgy_site_open to acquire a bound handle.
schema_name A value of type sec_attr_component_name_t that
specifies the name of the schema object to be created.
size_avail An unsigned 32-bit integer containing the allocated
length of the acl_mgr_types array.
Output
size_used An unsigned 32-bit integer containing the number of
output entries returned in the acl_mgr_types array.
num_acl_mgr_types An unsigned 32-bit integer containing the number of
types returned in the acl_mgr_types array. This may be
greater than size_used if there was not enough space
allocated by size_avail for all the manager types in
the acl_mgr_types array.
acl_mgr_types[] An array of the length specified in size_avail to
contain UUIDs (of type uuid_t) identifying the types of
ACL managers protecting the target object.
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns one of the following errors:
sec_attr_unauthorized
sec_attr_svr_unavailable
sec_attr_no_memory
Usage
The sec_rgy_attr_sch_get_acl_mgrs routine returns a list of the
manager types protecting the schema object identified by context.
ACL editors and browsers can use this operation to determine the ACL
manager types protecting a selected schema object. They can then use
the sec_rgy_attr_sch_aclmgr_strings routine to determine how to
format for display the permissions supported by that ACL manager
type.
Permissions Required
The sec_rgy_attr_sch_get_acl_mgrs routine requires the r permission
on the attr_schema object.
Related Information
Routines: sec_rgy_attr_sch_aclmgr_strings
sec_rgy_site_open
Files:
dcelocal\include\dce\sec_rgy_ attr_sch.idl - The idl file from which
dce\sec_rgy_attr_sch.h was derived.
ΓòÉΓòÉΓòÉ 8.3.34. sec_rgy_attr_sch_lookup_by_id ΓòÉΓòÉΓòÉ
Purpose
Reads a schema entry identified by UUID.
Format
#include <dce/sec_rgy_attr_sch.h>
void sec_rgy_attr_sch_lookup_by_id(
sec_rgy_handle_t context,
sec_attr_component_name_t schema_name,
uuid_t *attr_id,
sec_attr_schema_entry_t *schema_entry,
error_status_t *status);
Parameters
Input
context An opaque handle bound to a registry server. Use
sec_rgy_site_open to acquire a bound handle.
schema_name A value of type sec_attr_component_name_t that
specifies the name of the schema object to be created.
attr_id A pointer to a uuid_t that identifies a schema entry.
Output
schema_entry A sec_attr_schema_entry_t that contains an entry
identified by attr_id.
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns one of the following errors:
sec_attr_sch_entry_not_found
sec_attr_unauthorized
sec_attr_svr_unavailable
sec_attr_no_memory
Usage
The sec_rgy_attr_sch_lookup_by_id routine reads a schema entry
identified by attr_id. This routine is useful for access by
applications.
Notes
You must free the space allocated for each sec_attr_schema_entry_t
pointer type used by this routine. Some encoding types, for example
printstrings and bindings, allocate a large chunk of memory for each
pointer each time this routine is called. Failure to release this
space can cause a memory leak, especially if you call this routine
several times. You can free the space by passing each
sec_attr_schema_entry_t pointer to the
sec_attr_util_sch_ent_free_ptrs or the sec_attr_util_sch_ent_free
routine.
Permissions Required
The sec_rgy_attr_sch_lookup_by_id routine requires the r permission
on the attr_schema object.
Related Information
Routines:
sec_rgy_attr_sch_lookup_by_name
sec_rgy_attr_sch_scan
sec_rgy_site_open
Files:
dcelocal\include\dce\sec_rgy_attr_sch.idl -The idl file from which
dce\sec_rgy_attr_sch.h was derived.
ΓòÉΓòÉΓòÉ 8.3.35. sec_rgy_attr_sch_lookup_by_name ΓòÉΓòÉΓòÉ
Purpose
Reads a schema entry identified by name.
Format
#include <dce/sec_rgy_attr_sch.h>
void sec_rgy_attr_sch_lookup_by_name(
sec_rgy_handle_t context,
sec_attr_component_name_t schema_name,
unsigned_char *attr_name,
sec_attr_schema_entry_t *schema_entry,
error_status_t *status);
Parameters
Input
context An opaque handle bound to a registry server. Use
sec_rgy_site_open to acquire a bound handle.
schema_name A value of type sec_attr_component_name_t that
specifies the name of the schema that contains the
entry to be changed.
attr_name A pointer to an unsigned character string that
identifies a schema entry.
Output
schema_entry A sec_attr_schema_entry_t that contains the schema
entry identified by attr_name.
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns one of the following errors:
sec_attr_sch_entry_not_found
sec_attr_bad_name
sec_attr_unauthorized
sec_attr_svr_unavailable
sec_attr_no_memory
Usage
The sec_rgy_attr_sch_lookup_by_name routine reads a schema entry
identified by name. This routine is useful with an interactive
editor.
Notes
You must free the space allocated for each sec_attr_schema_entry_t
pointer type used by this routine. Some encoding types, for example
printstrings and bindings, allocate a large chunk of memory for each
pointer each time this routine is called. Failure to release this
space can cause a memory leak, especially if you call this routine
several times. You can free the space by passing each
sec_attr_schema_entry_t pointer to the
sec_attr_util_sch_ent_free_ptrs or the sec_attr_util_sch_ent_free
routine.
Permissions Required
The sec_rgy_attr_sch_lookup_by_name routine requires the r permission
on the attr_schema object.
Related Information
Routines: sec_rgy_attr_sch_lookup_by_id
sec_rgy_attr_sch_scan
sec_rgy_site_open
Files:
dcelocal\include\dce\sec_rgy_attr_sch.idl - The idl file from which
dce\sec_rgy_attr_sch.h was derived.
ΓòÉΓòÉΓòÉ 8.3.36. sec_rgy_attr_sch_scan ΓòÉΓòÉΓòÉ
Purpose
Reads a specified number of schema entries.
Format
#include <dce/sec_rgy_attr_sch.h>
void sec_rgy_attr_sch_scan(
sec_rgy_handle_t context,
sec_attr_component_name_t schema_name,
sec_attr_cursor_t *cursor,
unsigned32 num_to_read,
unsigned32 *num_read,
sec_attr_schema_entry_t schema_entries[],
error_status_t *status);
Parameters
Input
context An opaque handle bound to a registry server. Use
sec_rgy_site_open to acquire a bound handle.
schema_name A value of type sec_attr_component_name_t that
specifies the name of the schema object to be created.
num_to_read An unsigned 32-bit integer specifying the size of the
schema_entries array and the maximum number of entries
to be returned.
Input/Output
cursor A pointer to a sec_attr_cursor_t. As input, cursor
must be allocated and can be initialized. If cursor is
not initialized, sec_rgy_attr_sch_scan is initialized.
As output, cursor is positioned at the first schema
entry after the returned entries.
Output
num_read A pointer to an unsigned 32-bit integer specifying the
number of entries returned in schema_entries.
schema_entries[] A sec_attr_schema_entry_t that contains an array of
the returned schema entries.
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok
Otherwise, it returns one of the following errors:
sec_attr_bad_cursor
sec_attr_unauthorized
sec_attr_svr_unavailable
sec_attr_no_memory
Usage
The sec_rgy_attr_sch_scan routine reads schema entries. The read
begins at the entry where the input cursor is positioned and ends
after the number of entries specified in num_to_read.
The input cursor must have been allocated by either the
sec_rgy_attr_cursor_init or the sec_rgy_attr_cursor_alloc routine. If
the input cursor is not initialized, sec_rgy_attr_sch_scan
initializes it; if cursor is initialized, sec_rgy_attr_sch_scan only
advances it.
To read all entries in a schema, make successive
sec_rgy_attr_sch_scan routines. When all entries have been read, the
routine returns the message no_more_entries.
This routine is useful as a browser.
Permissions Required
The sec_rgy_attr_sch_scan routine requires r permission on the
attr_schema object.
Related Information
Routines:
sec_rgy_site_open
sec_rgy_attr_sch_cursor_init
sec_rgy_attr_sch_cursor_alloc
sec_rgy_attr_sch_cursor_release
Files:
dcelocal\include\dce\sec_rgy_attr_sch.idl - The idl file from which
dce\sec_rgy_attr_sch.h was derived.
ΓòÉΓòÉΓòÉ 8.3.37. sec_rgy_attr_sch_update_entry ΓòÉΓòÉΓòÉ
Purpose
Updates a schema entry.
Format
#include <dce/sec_rgy_attr_sch.h>
void sec_rgy_attr_sch_update_entry(
sec_rgy_handle_t context,
sec_attr_component_name_t schema_name,
sec_attr_schema_entry_parts_t modify_parts,
sec_attr_schema_entry_t *schema_entry,
error_status_t *status);
Parameters
Input
context An opaque handle bound to a registry server. Use
sec_rgy_site_open to acquire a bound handle.
schema_name A value of type sec_attr_component_name_t that
specifies the name of the schema that contains the
entry to be changed.
modify_parts A value of type sec_attr_schema_entry_parts_t that
identifies the fields in schema_entry that can be
modified.
schema_entry A pointer to a sec_attr_schema_entry_t that contains
the schema entry values for the schema entry to be
updated.
Output
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns one of the following errors:
sec_attr_field_no_update
sec_attr_bad_name
sec_attr_bad_acl_mgr_set
sec_attr_bad_acl_mgr_type
sec_attr_bad_permset
sec_attr_bad_intercell_action
sec_attr_trig_bind_info_missing
sec_attr_bad_bind_info
sec_attr_bad_bind_svr_name
sec_attr_bad_bind_prot_level
sec_attr_bad_bind_authn_svc
sec_attr_bad_bind_authz_svc
sec_attr_bad_uniq_query_accept
sec_attr_bad_comment
sec_attr_name_exists
sec_attr_sch_entry_not_found
sec_attr_unauthorized
sec_attr_svr_read_only
sec_attr_svr_unavailable
sec_attr_no_memory
Usage
The sec_rgy_attr_sch_update_entry routine modifies schema entries.
Only those schema entry fields set to be modified in the
sec_attr_schema_entry_parts_t data type can be modified.
Some schema entry components can never be modified. Instead, to make
any changes to these components, the schema entry must be deleted
(which deletes all attribute instances of that type) and re-created.
The schema entry components that can never be modified are:
o Attribute name
o Reserved flag
o Apply defaults flag
o Intercell action flag
o Trigger binding
o Comment
Fields that are arrays of structures (such as acl_mgr_set and
trig_binding) are completely replaced by the new input array. This
operation cannot be used to add a new element to the existing array.
Permissions Required
The sec_rgy_attr_sch_update_entry routine requires the M permission
on the attr_schema object.
Related Information
Routines:
sec_rgy_attr_sch_delete_entry
sec_rgy_attr_sch_create_entry
sec_rgy_site_open
Files:
dcelocal\include\dce\sec_rgy_attr_sch.idl - The idl file from which
dce\sec_rgy_attr_sch.h was derived.
ΓòÉΓòÉΓòÉ 8.3.38. sec_rgy_attr_test_and_update ΓòÉΓòÉΓòÉ
Purpose
Updates specified attribute instances for a specified object only if
a set of control attribute instances match the existing attribute
instances of the object.
Format
#include <dce/sec_rgy_attr.h>
void sec_rgy_attr_test_and_update(
sec_rgy_handle_t context,
sec_rgy_domain_t name_domain,
sec_rgy_name_t name,
unsigned32 num_to_test,
sec_attr_t test_attrs[],
signed32 num_to_write,
sec_attr_t update_attrs[],
singed32 *failure_index,
error_status_t *status);
Parameters
Input
context An opaque handle bound to a registry server. Use
sec_rgy_site_open to acquire a bound handle.
name_domain A value of type sec_rgy_domain_t that identifies the
registry domain in which the object specified by name
resides. The valid values are:
sec_rgy_domain_person The name identifies a
principal.
sec_rgy_domain_group The name identifies a
group.
sec_rgy_domain_org The name identifies an
organization.
This parameter is ignored if name is policy or replist.
name A character string of type sec_rgy_name_t specifying
the name of the person, group, or organization to which
the attribute is attached.
num_to_test An unsigned 32-bit integer that specifies the number of
elements in the test_attrs array. This integer must be
greater than 0.
test_attrs[] An array of values of type sec_attr_t that specifies
the control attributes. The update takes place only if
the types and values of the control attributes exactly
match those of the attribute instances on the named
registry object. The size of the array is determined by
num_to_test.
num_to_write A 32-bit integer that specifies the number of attribute
instances returned in the update_attrs array.
update_attrs[] An array of values of type sec_attr_t that specifies
the attribute instances to be updated. The size of the
array is determined by num_to_write.
Output
failure_index In the event of an error, failure_index is a pointer to
the element in the update_attrs array that caused the
update to fail. If the failure cannot be attributed to
a specific attribute, the value of failure_index is -1.
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns one of the following errors:
control attribute has changed
unauthorized
database read only
server unavailable
invalid/unsupported attribute type
invalid encoding type
value not unique
trigger server unavailable
site read only
Usage
The sec_rgy_attr_test_and_update routine updates an attribute only if
the set of control attributes specified in the test_attrs match
attributes that already exist for the object.
This update is an atomic operation: if any of the control attributes
do not match existing attributes, none of the updates are performed.
If an update should be performed but the write cannot occur for
whatever reason to any member of the update_attrs array, all updates
are stopped. The attribute causing the update to fail is identified
in failure_index. If the failure cannot be attributed to a given
attribute, failure_index contains -1.
If an attribute instance already exists that is identical in both
attr_id and attr_value to an attribute specified in test_attrs, the
existing attribute information is overwritten by the new information.
For multivalued attributes, every instance with the same attr_id is
overwritten with the supplied values.
If an attribute instance does not exist, it is created.
If you specify an attribute set for updating, the update applies to
the set instance, the set itself, not the members of the set. To
update a member of an attribute set, supply the UUID of the set
member.
If an input attribute is associated with an update attribute trigger
server, the attribute trigger server is used (by the
sec_attr_trig_update routine) and the test_attr array is supplied as
input. The output attributes from the update attribute trigger server
are stored in the registry database and returned in the update_attrs
array.
Notes The update attribute trigger server may modify the values
before they are used to update the registry database. This is
the only circumstance when the values in the update_attrs
array differ from the values in the test_attrs array.
If an input attribute is associated with an update trigger, the
trigger will be invoked with the input attr array and the output
attributes from the update trigger will be stored in the ERA database
and returned in the out_attrs array.
Permissions Required
The sec_rgy_attr_test_and_update routine requires the test permission
and the update permission set for each attribute type identified in
the test_attrs array. These permissions are defined as part of the
ACL manager set in the schema entry of each attribute type.
Related Information
Routines:
sec_attr_trig_update
sec_rgy_attr_update
sec_rgy_attr_delete
sec_rgy_site_open
Files:
dcelocal\include\dce\sec_rgy_attr.idl - The idl file from which
dce\sec_rgy_attr.h was derived.
ΓòÉΓòÉΓòÉ 8.3.39. sec_rgy_attr_update ΓòÉΓòÉΓòÉ
Purpose
Creates and updates attribute instances for a specified object.
Format
#include <dce/sec_rgy_attr.h>
void sec_rgy_attr_update(
sec_rgy_handle_t context,
sec_rgy_domain_t name_domain,
sec_rgy_name_t name,
unsigned32 num_to_write,
unsigned32 space_avail,
sec_attr_t in_attrs[]
unsigned32 *num_returned
sec_attr_t out_attrs[]
unsigned32 *num_left
signed32 *failure_index
error_status_t *status);
Parameters
Input
context An opaque handle bound to a registry server. Use
sec_rgy_site_open to acquire a bound handle.
name_domain A value of type sec_rgy_domain_t that identifies the
registry domain where the object specified by name
resides. The valid values are:
sec_rgy_domain_person The name identifies a
principal.
sec_rgy_domain_group The name identifies a
group.
sec_rgy_domain_org The name identifies an
organization.
This parameter is ignored if name is policy or replist.
name A character string of type sec_rgy_name_t specifying
the name of the person, group, or organization to which
the attribute is attached.
num_to_write An unsigned 32-bit integer that specifies the number of
elements in the in_attrs array. This integer must be
greater than 0.
space_avail A 32-bit unsigned integer that specifies the size of
the out_attrs array. This integer must be greater than
0.
in_attrs[] An array of values of type sec_attr_t that specifies
the attribute instances to be updated. The size of the
array is determined by num_to_write.
Output
num_returned A pointer to an unsigned 32-bit integer that specifies
the number of attribute instances returned in the
out_attrs array.
out_attrs[] An array of values of type sec_attr_t that specifies
the updated attribute instances. Note that these
attributes differ from the attributes in the in_attrs
array only if they were processed by an update
attribute trigger server. The size of the array is
determined by space_avail and the length by
num_returned.
num_left A pointer to an unsigned 32-bit integer that supplies
the number of attributes that could not be returned
because of space constraints in the out_attrs buffer.
To ensure that all the attributes are returned,
increase the size of the out_attrs array by increasing
the size of space_avail and num_returned.
failure_index In the event of an error, failure_index is a pointer to
the element in the in_attrs array that caused the
update to fail. If the failure cannot be attributed to
a specific attribute, the value of failure_index is -1.
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns one of the following errors:
unauthorized
database read only
server unavailable
invalid/unsupported attribute type
invalid encoding type
value not unique
attribute instance already exists
trigger server unavailable
site read only
Usage
The sec_rgy_attr_update routine creates new attribute instances and
updates existing attribute instances attached to an object specified
by name and Registry domain. The instances to be created or updated
are passed as an array of sec_attr_t data types. This is an atomic
operation: if the creation of any attribute in the in_attrs array
fails, all updates are stopped. The attribute causing the update to
fail is identified in failure_index. If the failure cannot be
attributed to a given attribute, failure_index contains -1.
The in_attrs array, which specifies the attributes to be created,
contains values of type sec_attr_t. These values are:
attr_id A UUID that identifies the attribute type
attr_value A value of sec_attr_value_t that specifies the attribute's
encoding type and values.
If an attribute instance already exists that is identical in both
attr_id and attr_value to an attribute specified in in_attrs, the
existing attribute information is overwritten by the new information.
For multivalued attributes, every instance with the same attr_id is
overwritten with the supplied values.
If an attribute instance does not exist, it is created.
For multivalued attributes, because every instance of the multivalued
attribute is identified by the same UUID, every instance is
overwritten with the supplied value. To change only one of the
values, you must supply the values that should be unchanged as well
as the new value.
To create instances of multivalued attributes, create individual
sec_attr_t data types to define each multivalued attribute instance
and then pass all of them in using the input array.
If an input attribute is associated with an update attribute trigger
server, the attribute trigger server is used (by the
sec_attr_trig_update routine) and the in_attrs array is supplied as
input. The output attributes from the update attribute trigger server
are stored in the registry database and returned in the out_attrs
array.
Notes The update attribute trigger server may modify the values
before they are used to update the registry database. This is
the only circumstance where the values in the out_attrs array
differ from the values in the in_attrs array.
If an input attribute is associated with an update trigger, the
trigger will be invoked with the input attr array and the output
attributes from the update trigger will be stored in the ERA database
and returned in the out_attrs array.
Permissions Required
The sec_rgy_attr_update routine requires the update permission set
for each attribute type identified in the in_attrs array. These
permissions are defined as part of the ACL manager set in the schema
entry of each attribute type.
Related Information
Routines:
sec_rgy_attr_delete
sec_rgy_attr_test_and_update
Files:
dcelocal\include\dce\sec_rgy_attr.idl - The idl file from which
dce\sec_rgy_attr.h was derived.
ΓòÉΓòÉΓòÉ 8.4. DCE Generic Security Service API ΓòÉΓòÉΓòÉ
The Generic Security Service Application Programming Interface (GSSAPI)
provides security services to applications using peer-to-peer communications
(instead of DCE-secure RPC). Using DCE GSSAPI routines, applications can:
o Determine the current user of another application.
o Delegate access rights to another application.
o Apply security services, such as confidentiality and integrity, on a
per-message basis.
GSSAPI represents a secure connection between two communicating applications
with a data structure called a security context. The application that
establishes the secure connection is called the context initiator or simply
initiator. The context initiator is similar to a DCE RPC client. The
application that accepts the secure connection is the context acceptor, or
acceptor. The context acceptor is similar to a DCE RPC server.
There are four stages involved in using the GSSAPI:
1. The context initiator acquires a credential to use to prove its identity
to other processes. Similarly, the context acceptor acquires a credential
to enable it to accept a security context. Either application can omit
this credential acquisition and use its default credentials in subsequent
stages.
The applications use credentials to establish their global identity. The
global identity can be, but is not necessarily, related to the local user
name under which the application is running. Credentials can contain the
following:
o The login context - Includes a principal's network credentials, as
well as other account information.
o The principal name and a key - The key that corresponds to the
principal name and must be registered with the DCE Security Service
in a key table. A set of DCE GSSAPI routines enables applications to
register and use principal names.
2. The communicating applications establish a joint security context by
exchanging authentication tokens.
The security context is a pair of GSSAPI data structures that contain
information that is shared between the communicating applications. The
information describes the state of each application. This security
context is required for per-message security services.
To establish a security context, the context initiator calls the
gss_init_sec_context routine to get a token. The token is
cryptographically protected, opaque data. The context initiator transfers
the token to the context acceptor, which in turn passes the token to the
gss_accept_sec_context routine to decode and extract the shared
information. As part of establishing the security context, the context
initiator is authenticated to the context acceptor. The context initiator
can require the context acceptor to authenticate itself in return.
The context initiator can delegate rights to allow the context acceptor
to act as its agent. Delegation means the context initiator gives the
context acceptor the ability to initiate additional security contexts as
an agent of the context initiator. To delegate, the context initiator
sets a flag on the gss_init_sec_context routine indicating that it wants
to delegate and sends the returned token in the normal way to the context
acceptor. The acceptor passes this token to the gss_accept_sec_context
routine, which generates a delegated credential. The context acceptor can
use the credential to initiate additional security contexts.
3. The applications exchange protected messages and data.
The applications can call GSSAPI routines to protect data exchanged in
messages. The application sends a protected message by calling the
appropriate GSSAPI routine to:
o Apply protection.
o Bind the message to the appropriate security context.
The application can then send the resulting information to the peer
application.
The application that receives the message passes the received data to
a GSSAPI routine, which removes the protection and validates the
data. GSSAPI treats application data as arbitrary octet strings. The
GSSAPI per-message security services can provide either:
o Integrity and authentication of data origin.
o Confidentiality, integrity, and authentication of data origin.
4. When the applications finish communicating, either one can instruct
GSSAPI to delete the security context.
This introduction includes general information about the Generic Security
Service Application Programming Interface (GSSAPI) defined in Internet RFC
1508, Generic Security Service Application Programming Interface, and RFC
1509, Generic Security Service API: C-bindings.
See the following subtopics for more information:
Error Handling
GSSAPI Data Types
Optional Parameters
GSSAPI Routines
Related Information
ΓòÉΓòÉΓòÉ 8.4.1. Error Handling ΓòÉΓòÉΓòÉ
Each GSSAPI routine returns two status values:
Major status values Generic API routine errors or calling errors defined in
RFC 1509.
Minor status values Values that indicate DCE-specific errors.
If a routine has output parameters that contain pointers for storage allocated
by the routine, the output parameters always contain a valid pointer, even if
the routine returns an error. If no storage was allocated, the routine sets
the pointer to NULL and sets any length fields associated with the pointers
(such as in the gss_buffer_desc structure) to 0 (zero).
Minor status values usually contain more detailed information about the error.
They are not, however, portable between GSSAPI implementations. When designing
portable applications, use major status values for handling errors. Use minor
status values to debug applications and to display error and error-recovery
information to users.
ΓòÉΓòÉΓòÉ 8.4.1.1. Major Status Values ΓòÉΓòÉΓòÉ
GSSAPI routines return GSS status codes as their OM_uint32 function value.
These codes indicate either generic API routine errors or calling errors.
A GSS status code can indicate a single, irrecoverable generic API error from
the routine and a single calling error. Additional status information can also
be contained in the GSS status code. The errors are encoded into a 32-bit GSS
status code, as follows:
MSB LSB
+---------------------------------------------------+
| Calling Error | Routine Error | Supplementary Info|
+---------------------------------------------------+
Bit 31 24 23 16 15 0
If a GSSAPI routine returns a GSS status code whose upper 16 bits contain a
nonzero value, the call failed. If the calling error field is nonzero, the
context initiator's use of the routine was in error. In addition, the routine
can indicate additional information by setting bits in the supplementary
information field of the status code. The tables that follow describe the
routine errors, calling errors, and supplementary information status bits and
their meanings.
The following table lists the GSSAPI routine errors and their meanings:
ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
Γöé Table 13. GSSAPI Routine Errors Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé NAME Γöé FIELD Γöé MEANING Γöé
Γöé Γöé VALUE Γöé Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé GSS_S_BAD_MECH Γöé 1 Γöé The required mechanism is Γöé
Γöé Γöé Γöé unsupported. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé GSS_S_BAD_NAME Γöé 2 Γöé The name passed is not Γöé
Γöé Γöé Γöé valid. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé GSS_S_BAD_NAMETYPE Γöé 3 Γöé The name passed is unsup- Γöé
Γöé Γöé Γöé ported. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé GSS_S_BAD_BINDINGS Γöé 4 Γöé The channel bindings are Γöé
Γöé Γöé Γöé incorrect. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé GSS_S_BAD_STATUS Γöé 5 Γöé A status value was not Γöé
Γöé Γöé Γöé valid. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé GSS_S_BAD_SIG Γöé 6 Γöé A token had a signature that Γöé
Γöé Γöé Γöé is not valid. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé GSS_S_NO_CRED Γöé 7 Γöé No credentials were sup- Γöé
Γöé Γöé Γöé plied. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé GSS_S_NO_CONTEXT Γöé 8 Γöé No context has been estab- Γöé
Γöé Γöé Γöé lished. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé GSS_S_DEFECTIVE_TOKEN Γöé 9 Γöé A token was not valid. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé GSS_S_DEFECTIVE_CREDENTIAL Γöé 10 Γöé A credential was not valid. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé GSS_S_CREDENTIALS_EXPIRED Γöé 11 Γöé The referenced credentials Γöé
Γöé Γöé Γöé expired. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé GSS_S_CONTEXT_EXPIRED Γöé 12 Γöé The context expired. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé GSS_S_FAILURE Γöé 13 Γöé The routine failed. Check Γöé
Γöé Γöé Γöé minor status codes. Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
The following table lists the calling error values and their meanings:
ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
Γöé Table 14. Calling Errors Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé NAME Γöé FIELD Γöé MEANING Γöé
Γöé Γöé VALUE Γöé Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé GSS_S_CALL_INACCESSIBLE_READ Γöé 1 Γöé Could not read a required Γöé
Γöé Γöé Γöé input parameter. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé GSS_S_CALL_INACCESSIBLE_WRITE Γöé 2 Γöé Could not write a required Γöé
Γöé Γöé Γöé output parameter. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé GSS_S_BAD_STRUCTURE Γöé 3 Γöé A parameter was incorrectly Γöé
Γöé Γöé Γöé structured. Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
The following table lists the supplementary bits and their meanings.
ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
Γöé Table 15. Supplementary Information Status Bits Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé NAME Γöé FIELD Γöé MEANING Γöé
Γöé Γöé VALUE Γöé Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé GSS_S_CONTINUE_NEEDED Γöé 0 Γöé Call the routine again to Γöé
Γöé Γöé (LSB) Γöé complete its function. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé GSS_S_DUPLICATE_TOKEN Γöé 1 Γöé The token is a duplicate of Γöé
Γöé Γöé Γöé an earlier token. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé GSS_S_OLD_TOKEN Γöé 2 Γöé The token's validity period Γöé
Γöé Γöé Γöé expired; the routine cannot Γöé
Γöé Γöé Γöé verify that the token is not Γöé
Γöé Γöé Γöé a duplicate of an earlier Γöé
Γöé Γöé Γöé token. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé GSS_S_UNSEQ_TOKEN Γöé 3 Γöé A later token has been proc- Γöé
Γöé Γöé Γöé essed. Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
All GSS_S_ symbols equate to complete OM_uint32 status codes, rather than to
bitfield values. For example, the actual value of GSS_S_BAD_NAMETYPE (value 3
in the routine error field) is 3 << 16.
The major status code GSS_S_FAILURE indicates that DCE Security detected an
error that does not have a major status code. Check the minor status code for
details about the error.
The GSSAPI provides three macros to extract values for each type of error from
a GSS status code:
o GSS_CALLING_ERROR
o GSS_ROUTINE_ERROR
o GSS_SUPPLEMENTARY_INFO
Each macro takes a GSS status code and masks all but the relevant field. For
example, when you use the GSS_ROUTINE_ERROR macro on a status code, it returns
a value. The value of the macro is arrived at by using the routine errors
field only and zeroing the values of the calling error and the supplementary
information fields.
An additional macro, GSS_ERROR, lets you determine whether the status code
indicated a calling or routine error. If the status code indicated a calling
or routine error, the macro returns a nonzero value. If no calling or routine
error is indicated, the routine returns a 0 (zero).
Note: At times, a GSSAPI routine that is unable to access data can generate a
platform-specific signal instead of returning a
GSS_S_CALL_INACCESSIBLE_READ or GSS_S_CALL_INACCESSIBLE_WRITE status
value.
ΓòÉΓòÉΓòÉ 8.4.1.2. Minor Status Values ΓòÉΓòÉΓòÉ
The GSSAPI routines return a minor_status parameter to indicate errors from
either DCE Security or Kerberos. The parameter can contain a single error,
which is indicated by an OM_uint32 value. The OM_uint32 data type is equivalent
to the DCE data type error_status_t and can contain any DCE-defined error.
ΓòÉΓòÉΓòÉ 8.4.2. GSSAPI Data Types ΓòÉΓòÉΓòÉ
This section provides an overview of the GSSAPI data types and their
definitions. The GSSAPI defines the following data types:
OM_uint32 A 32-bit unsigned integer. A portable data type that the GSSAPI
routine definitions use for guaranteed minimum bit-counts.
gss_buffer_t A pointer to the buffer descriptor gss_buffer_desc, used to
pass the data between the GSSAPI routines and applications.
Many of the GSSAPI routines take arguments and return values
that describe contiguous multiple-byte data, such as opaque
data and character strings. The gss_buffer_t data type has the
following structure:
typedef struct gss_buffer_desc_struct {
size_t length;
void *value;
} gss_buffer_desc, *gss_buffer_t;
where the fields are:
length Contains the total number of bytes in the data.
value Contains a pointer to the actual data.
When using the gss_buffer_t data type, the GSSAPI routine
allocates storage for any data it passes to the application.
The calling application must allocate the gss_buffer_desc
object. It can initialize unused gss_buffer_desc objects with
the value GSS_C_EMPTY_BUFFER. To free the storage, the
application calls the gss_release_buffer routine.
gss_OID Allows you to choose a security mechanism, either DCE Security
or Kerberos, and to specify name types. Select a security
mechanism by using one of the following OIDs:
GSSDCE_C_OID_DCE_KRBV5_DES For DCE Security.
GSS_C_NULL_OID Default DCE Security.
Use the default security
mechanisms to ensure the
portability of the
application.
GSSDCE_C_OID_KRBV5_DES For Kerberos Version 5.
The gss_OID data type contains tree-structured values defined
by ISO as typedef OM_object_identifier. Type
OM_object_identifier is of type OM_string, which has the
following structure:
typedef struct {
OM_string_length length;
void *elements;
} OM_string;
where the fields are:
elements A pointer to the first byte of an octet
string containing the ASN.1 BER encoding of
the value of the gss_OID data type.
length The number of bytes in the value. The
OM_string_length type is defined as
OM_uint32. The gss_OID_desc values returned
from the GSSAPI are read-only values. The application should
not try to deallocate them.
gss_OID_set Represents one or more object identifiers. The values of this
data type are used to:
o Report the available mechanisms supported by GSSAPI.
o Request specific mechanisms.
o Indicate which mechanisms a credential supports.
The gss_OID_set data type has the following structure:
typedef struct gss_OID_set_desc_struct {
int count;
gss_OID elements;
} gss_OID_set_desc, *gss_OID_set;
where the fields are:
count The number of OIDs in the set.
elements A pointer to an array of gss_oid_desc
objects, where each describes a single OID.
The application calls the gss_release_oid_set routine to
deallocate storage associated with the gss_OID_set values that
the GSSAPI routines return to the application.
gss_cred_id_t An atomic data type that identifies a GSSAPI credential data
structure. Credentials establish, or prove, the identity of an
application or other principal.
gss_ctx_id_t Contains an atomic value that identifies one end of a GSSAPI
security context. This data type is opaque to the caller.
The security context is a pair of GSSAPI data structures that
contain information shared between the communicating
applications. The information describes the cryptographic state
of each application. This security context is required for
per-message security services and is created by a successful
authentication exchange.
gss_buffer_t A token to GSSAPI routines. GSSAPI uses tokens to maintain the
synchronization between the applications sharing a security
context. The token is a cryptographically protected bit string
generated by DCE Security at one end of the GSSAPI security
context for use by the peer application at the other end of the
security context. This data type is opaque to the caller.
gss_name_t Contains a principal name in non-printable format. Names
identify principals. The GSSAPI authenticates the relationship
between a name and the principal claiming the name. Names are
represented in two forms:
o A printable form, for presentation to an application.
o An internal, canonical form that is used by the API and is
opaque to applications.
The gss_import_name and gss_display_name routines convert names
between their printable form and their gss_name_t data type.
DCE GSSAPI supports only DCE principal names, which are
identified by the constant OID, GSSCDE_C_OID_DCENAME.
The gss_compare_names routine compares internal form names.
gss_channel_bindings_t Contains a channel binding. You can define and use
channel bindings to associate the security context with the
communications channel that carries the context. The
gss_channel_bindings_t data type has the following structure:
typedef struct gss_channel_bindings_struct {
OM_uint32 initiator_addrtype;
gss_buffer_desc initiator_address;
OM_uint32 acceptor_addrtype;
gss_buffer_desc acceptor_address;
gss_buffer_desc application_data;
} *gss_channel_bindings_t;
Use initiator_addrtype and acceptor_addrtype to initiate the
type of addresses contained in the initiator_address and
acceptor_address buffers. The following table lists the address
types and their addrtype values:
ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
Γöé Table 16. GSSAPI Address Types Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé ADDRESS TYPE Γöé ADDRTYPE VALUE Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé Unspecified Γöé GSS_C_AF_UNSPEC Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé Host-local Γöé GSS_C_AF_LOCAL Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé DARPA Internet Γöé GSS_C_AF_INET Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé ARPAnet IMP Γöé GSS_C_AF_IMPLINK Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé pup protocols (for example, BSP) Γöé GSS_C_AF_PUP Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé MIT CHAOS protocol Γöé GSS_C_AF_CHAOS Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé XEROX NS Γöé GSS_C_AF_NS Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé nbs Γöé GSS_C_AF_NBS Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé ECMA Γöé GSS_C_AF_ECMA Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé datakit protocols Γöé GSS_C_AF_DATAKIT Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé CCITT protocols (for example, Γöé GSS_C_AF_CCITT Γöé
Γöé X.25) Γöé Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé IBM SNA Γöé GSS_C_AF_SNA Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé Digital DECnet Γöé GSS_C_AF_DECNET Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé Direct data link interface Γöé GSS_C_AF_DLI Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé LAT Γöé GSS_C_AF_LAT Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé NSC Hyperchannel Γöé GSS_C_AF_HYLINK Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé AppleTalk Γöé GSS_C_AF_APPLETALK Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé BISYNC 2780/3780 Γöé GSS_C_AF_BSC Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé Distributed system services Γöé GSS_C_AF_DSS Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé OSI TP4 Γöé GSS_C_AF_OSI Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé X25 Γöé GSS_C_AF_X25 Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé No address specified Γöé GSS_C_AF_NULLADDR Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
The tags specify address families rather than addressing
formats. For address families that contain several alternative
address forms, initiator_address and the acceptor_address
should contain sufficient information to determine the address
form that is used. Format the bytes that contain the addresses
in the same order the bytes are transmitted across the network.
The GSSAPI creates an octet string by concatenating all the
fields (initiator_addrtype, initiator_address,
acceptor_addrtype, acceptor_address, and application_data). The
security mechanism signs the octet string and binds the
signature to the token generated by the gss_init_sec_context
routine. The context acceptor presents the same bindings to the
gss_accept_sec_context routine, which evaluates the signature
and compares it to the signature in the token. If the
signatures differ, the gss_accept_sec_context routine returns a
GSS_S_BAD_BINDINGS error, and the context is not established.
Some security mechanisms check that the initiator_address field
of the channel bindings presented to the gss_init_sec_context
routine contains the correct network address of the host
system. Therefore, portable applications should use either the
correct address type and value or GSS_C_AF_NULLADDR for
initiator_addrtype. Some security mechanisms include the
channel binding data in the token instead of in a signature, so
portable applications should not use confidential data as
channel-binding components. The DCE GSSAPI does not verify the
address or include the plain text bindings information in the
token.
ΓòÉΓòÉΓòÉ 8.4.3. Optional Parameters ΓòÉΓòÉΓòÉ
In routine descriptions, optional parameters allow the application to request
default behaviors by passing a default value for the parameter. The following
conventions are used for optional parameters:
ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
Γöé Table 17. GSSAPI Routine Errors Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé CONVENTION Γöé VALUE DEFAULT Γöé EXPLANATION Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé gss_buffer_t Γöé GSS_C_NO_BUFFER Γöé For an input Γöé
Γöé types Γöé Γöé parameter, indi- Γöé
Γöé Γöé Γöé cates no data is Γöé
Γöé Γöé Γöé supplied. For an Γöé
Γöé Γöé Γöé output parameter, Γöé
Γöé Γöé Γöé indicates that Γöé
Γöé Γöé Γöé the information Γöé
Γöé Γöé Γöé returned is not Γöé
Γöé Γöé Γöé required by the Γöé
Γöé Γöé Γöé application. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé Integer types Γöé Γöé Refer to the ref- Γöé
Γöé (input) Γöé Γöé erence pages for Γöé
Γöé Γöé Γöé default values. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé Integer types Γöé NULL Γöé Indicates that Γöé
Γöé (output) Γöé Γöé the application Γöé
Γöé Γöé Γöé does not require Γöé
Γöé Γöé Γöé the information. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé Pointer types Γöé NULL Γöé Indicates that Γöé
Γöé (output) Γöé Γöé the application Γöé
Γöé Γöé Γöé does not require Γöé
Γöé Γöé Γöé the information. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé OIDs Γöé GSS_C_NULL_OID Γöé Indicates the Γöé
Γöé Γöé Γöé default choice Γöé
Γöé Γöé Γöé for name type or Γöé
Γöé Γöé Γöé security mech- Γöé
Γöé Γöé Γöé anism. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé OID sets Γöé GSS_C_NULL_OID_SET Γöé Indicates the Γöé
Γöé Γöé Γöé default set of Γöé
Γöé Γöé Γöé security mech- Γöé
Γöé Γöé Γöé anisms, DCE Secu- Γöé
Γöé Γöé Γöé rity, and Γöé
Γöé Γöé Γöé Kerberos. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé Credentials Γöé GSS_C_NO_CREDENTIAL Γöé Indicates that Γöé
Γöé Γöé Γöé the application Γöé
Γöé Γöé Γöé should use the Γöé
Γöé Γöé Γöé default creden- Γöé
Γöé Γöé Γöé tial handle. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé Channel bindings Γöé GSS_C_NO_CHANNEL_BINDINGS Γöé Indicates that no Γöé
Γöé Γöé Γöé channel bindings Γöé
Γöé Γöé Γöé are used. Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
ΓòÉΓòÉΓòÉ 8.4.4. GSSAPI Routines ΓòÉΓòÉΓòÉ
There are two sets of GSSAPI routines:
o Standard GSSAPI routines, which are defined in the Internet RFC 1508,
Generic Security Service Application Programming Interface, and RFC 1509,
Generic Security Service API: C-bindings. These routines have the prefix
gss_.
o OSF DCE extensions to the GSSAPI routines. These are additional routines
that enable an application to use DCE security services. These routines
have the prefix gssdce_.
The standard GSS routines are:
gss_accept_sec_context
gss_acquire_cred
gss_compare_name
gss_context_time
gss_delete_sec_context
gss_display_name
gss_display_status
gss_import_name
gss_indicate_mechs
gss_init_sec_context
gss_inquire_cred
gss_process_context_token
gss_release_buffer
gss_release_cred
gss_release_name
gss_release_oid_set
gss_seal
gss_sign
gss_unseal
gss_verify
The GSSAPI DCE extension routines are the following:
gssdce_add_oid_set_member Adds a specified Object Identifier to a
set of Object Identifiers. Convenience
routine.
gssdce_create_empty_oid_set Creates an Object Identifier set
containing no elements. Convenience
routine.
gssdce_cred_to_login_context Constructs a DCE login context from a
GSSAPI credential.
gssdce_extract_creds_from_sec_context Extracts a DCE credentials object from a
GSSAPI security context.
gssdce_extract_PAC_from_cred Extracts DCE credentials from a GSSAPI
credential.
gssdce_extract_PAC_from_sec_context Extracts a DCE privilege attribute
certificate (PAC) from a GSSAPI security
context.
gssdce_login_context_to_cred Constructs a GSSAPI credential from a
DCE login context.
gssdce_register_acceptor_identity Specifies a DCE keytable to be used for
accepting contexts under a specified
name.
gssdce_set_cred_context_ownership Changes the ownership of a DCE
credential's login context.
gssdce_test_oid_set_member Determines whether a specified Object
Identifier is contained in a set.
Convenience routine.
ΓòÉΓòÉΓòÉ 8.4.5. Related Information ΓòÉΓòÉΓòÉ
Books:
DCE for OS/2 Warp: Application Development Guide - Core Components
ΓòÉΓòÉΓòÉ 8.4.6. gssdce_add_oid_set_member ΓòÉΓòÉΓòÉ
Purpose
Adds an OID value to an object identifier (OID) set.
Format
#include <dce/gssapi.h>
OM_uint32 gssdce_add_oid_set_member (
OM_uint32 *minor_status,
gss_OID member_OID,
gss_OID_set *OID_set );
Parameters
Input
member_OID Specifies the OID you want to add to the OID set.
OID_set Specifies an OID set.
Output
minor_status Returns a status code from the security mechanism.
Usage
The gssdce_add_oid_set_member routine adds a new OID to an OID set.
If an OID set does not exist, you can create a new empty OID set with
the gssdce_create_empty_oid_set routine.
Return Codes
This routine returns the following major status code:
GSS_S_COMPLETE The routine was completed successfully. Check the
minor_status parameter for details.
Related Information
Routines: gssdce_create_empty_oid_set
gss_acquire_cred
ΓòÉΓòÉΓòÉ 8.4.7. gssdce_create_empty_oid_set ΓòÉΓòÉΓòÉ
Purpose
Creates a new empty OID set that members can be added to by calling
the gssdce_add_oid_set_member routine.
Format
#include <dce/gssapi.h>
OM_uint32 gssdce_create_empty_oid_set (
OM_uint32 *minor_status,
gss_OID_set *OID_set );
Parameters
Input
OID_set Specifies the OID set you want to create.
Output
minor_status Returns a status code from the security mechanism.
Usage
The gssdce_create_empty_oid_set routine creates a new empty OID set
to which the context initiator can add members. Use the
gssdce_add_oid_set_member routine to add members to the OID set.
Use the gssdce_create_empty_oid_set routine to specify a set of
security mechanisms with which you can use an acquired credential.
To create a credential that can accept a security context using DCE
Security, Kerberos, or a combination of the two, use the
gss_acquire_cred routine.
Return Codes
This routine returns the following major status codes:
GSS_S_COMPLETE The routine was completed successfully. Check the
minor_status parameter for details.
Related Information
Routines:
gssdce_add_oid_set_member
gss_acquire_cred
ΓòÉΓòÉΓòÉ 8.4.8. gssdce_cred_to_login_context ΓòÉΓòÉΓòÉ
Purpose
Obtains the DCE login context associated with a GSSAPI credential.
Format
#include <dce/gssapi.h>
OM_uint32 gssdce_cred_to_login_context (
OM_uint32 *minor_status,
gss_cred_id_t cred_handle,
sec_login_handle_t *login_context );
Parameters
Input
cred_handle Specifies the credential handle.
Output
login_context Returns the DCE login context associated with the
credential.
minor_status Returns a status code from the security mechanism.
Usage
Using the gssdce_cred_to_login_context routine, an application can
obtain the DCE login context associated with a GSSAPI credential.
Only credentials with usage types INIT or BOTH have associated login
contexts.
Use this routine to:
o Add delegation notes to a login context.
o Use an INITIATE or BOTH credential to initiate an authenticated
RPC.
The application must delete the login context when it no longer needs
the credentials or the login context.
Return Codes
This routine returns the following major status codes:
GSS_S_COMPLETE The routine was completed successfully.
GSS_S_DEFECTIVE_CREDENTIAL The credential is defective in some way.
GSS_S_FAILURE The routine failed. Check the minor_status parameter
for details.
GSS_S_NO_CRED The routine requested the default login context, but no
default login context was available.
Related Information
Routines:
gssdce_login_context_to_cred
sec_login_purge_context
sec_login_release_context
ΓòÉΓòÉΓòÉ 8.4.9. gssdce_extract_PAC_from_cred ΓòÉΓòÉΓòÉ
Purpose
Extracts a DCE privilege attribute certificate (PAC) from a GSSAPI
credential.
Format
#include <dce/gssapi.h>
OM_uint32 gssdce_extract_PAC_from_cred
OM_uint32 *minor_status,
gss_cred_id_t context_handle,
sec_id_pac_t output_pac );
Parameters
Input
context_handle Specifies the handle of the security context
containing the credential.
Output
output_pac Returns the PAC.
minor_status Returns a status code from the security mechanism.
Usage
The gssdce_extract_PAC_from_cred routine extracts a DCE credential
from a GSSAPI credential. The routine extracts privilege attribute
information about the principal associated with the credential.
A context acceptor calls this routine to examine the credential
contained in a delegated credential.
Return Codes
This routine returns the following major status codes:
GSS_S_COMPLETE The routine was completed successfully.
GSS_S_FAILURE The routine failed. Check the minor_status parameter
for details.
GSS_S_NO_CRED The routine could not access the credentials.
GSS_S_DEFECTIVE_CREDENTIAL The credential is defective in some way.
Related Information
Routines:
gssdce_extract_creds_from_sec_context
ΓòÉΓòÉΓòÉ 8.4.10. gssdce_extract_creds_from_sec_context ΓòÉΓòÉΓòÉ
Purpose
Extracts a DCE credential from a GSSAPI security context.
Format
#include <dce/gssapi.h>
OM_uint32 gssdce_extract_creds_from_sec_context (
OM_uint32 *minor_status,
gss_ctx_id_t context_handle,
rpc_authz_cred_handle_t *output_cred );
Parameters
Input
context_handle Specifies the handle of the security context
containing the DCE credential.
Output
output_cred Returns the DCE credential.
minor_status Returns a status code from the security mechanism.
Usage
The gssdce_extract_creds_from_sec_context routine extracts the
context initiator's DCE credential from a context acceptor's security
context. Use this routine if the underlying mechanism type is DCE
Security (GSSDCE_C_OID_DCE_KRBV5_DES).
The context acceptor calls the gssdce_extract_creds_from_sec_context
routine to get the DCE credential containing the privilege attributes
of the context initiator. DCE credentials are used by DCE ACL
managers to determine whether the initiator has the right to access
the object to which an ACL refers.
The principal contained in the DCE credential may not be the same as
the src_name parameter value from the gss_accept_sec_context routine.
The principal in the DCE credential can be a compound principal.
Return Codes
This routine returns the following major status codes:
GSS_S_COMPLETE The routine was completed successfully.
GSS_S_FAILURE The routine failed. Check the minor_status
parameter for details.
GSS_S_NO_CONTEXT The routine could not access the security
context.
Related Information
Routines:
gss_accept_sec_context
gss_init_sec_context
ΓòÉΓòÉΓòÉ 8.4.11. gssdce_extract_PAC_from_sec_context ΓòÉΓòÉΓòÉ
Purpose
Extracts a DCE privilege attribute certifiicate (PAC) from a GSSAPI
security context.
Format
#include <dce/gssapi.h>
OM_uint32 gssdce_extract_PAC_from_sec_context (
OM_uint32 *minor_status,
gss_ctx_id_t context_handle,
sec_id_pac_t *output_PAC);
Parameters
Input
context_handle Specifies the handle of the security context
containing the PAC.
Output
output_PAC Returns the DCE PAC.
minor_status Returns a status code from the security mechanism.
Usage
The gssdce_extract_PAC_from_sec_context routine extracts the context
initiator's DCE privilege attribute information (PAC) from a context
acceptor's security context.
The context acceptor calls the gssdce_extract_PAC_from_sec_context
routine to get the DCE PAC of the context initiator.
Return Codes
This routine returns the following status codes:
GSS_S_COMPLETE The routine was completed
successfully.
GSS_S_FAILURE The routine failed. Check the
minor_status parameter for details.
GSS_S_NO_CRED No credentials were supplied.
GSS_S_DEFECTIVE_CREDENTIAL A credential was not valid.
Related Information
Routines:
gssdce_extract_PAC_from_cred
ΓòÉΓòÉΓòÉ 8.4.12. gssdce_login_context_to_cred ΓòÉΓòÉΓòÉ
Purpose
Creates a GSSAPI credential handle for a context initiator or context
acceptor from a DCE login context.
Format
#include <dce/gssapi.h>
OM_uint32 gssdce_login_context_to_cred (
OM_uint32 *minor_status,
sec_login_handle_t login_context,
OM_uint32 lifetime_req,
gss_OID_set desired_mechs,
gss_cred_id_t *output_cred_handle,
gss_OID_set *actual_mechs,
OM_uint32 *lifetime_rec );
Parameters
Input
login_context Specifies the DCE login context handle. To use the
default login context handle, specify NULL.
lifetime_req Specifies the number of seconds the credential should
remain valid.
desired_mechs Specifies the OID set for the security mechanism to use
with the credential:
To use... Specify...
DCE Security
GSS_C_NULL_OID_SET
Kerberos
GSSDCE_C_OID_KRBV5_DES
Both DCE Security and Kerberos
GSSDCE_C_OID_DCE_KRBV5_DES
and
GSSDCE_C_OID_KRBV5_DES
To ensure portability of your application, use the
default security mechanism by specifying
GSS_C_NULL_OID_SET.
Input/Output
output_cred_handle As an input parameter, the routine tests the
contents of this parameter. If output_cred_handle
contains NULL, the routine returns
GSS_S_CALL_INACCESSIBLE_WRITE. As an output parameter,
it contains the credential handle.
Output
actual_mechs Returns the set specifying the security mechanisms with
which the credential can be used. The set can contain
one or both of the following:
o GSSDCE_C_OID_DCE_KRBV5_DES for DCE Security.
o GSSDCE_C_OID_KRBV5_DES for Kerberos.
lifetime_rec Returns the number of seconds that the credential
remains valid.
minor_status Returns a status code from the security mechanism.
Usage
The gssdce_login_context_to_cred routine creates a GSSAPI credential
handle for the context initiator or context acceptor from a DCE login
context. The routine creates a credential that can be used to
initiate or acquire a security context. Use this routine if you need
to create a GSSAPI credential for delegation.
Return Codes
This routine returns the following major status codes:
GSS_S_COMPLETE The routine was completed successfully.
GSS_S_CALL_INACCESSIBLE_WRITE. Could not write a required output
parameter.
GSS_S_NO_CRED The routine requested the default login context, but no
default login context was available.
GSS_S_FAILURE The routine failed. Check the minor_status parameter
for details.
Related Information
Routines:
gssdce_cred_to_login_context
gss_acquire_cred
ΓòÉΓòÉΓòÉ 8.4.13. gssdce_register_acceptor_identity ΓòÉΓòÉΓòÉ
Purpose
Registers a context acceptor's identity.
Format
#include <dce/gssapi.h>
OM_uint32 gssdce_register_acceptor_identity (
OM_uint32 *minor_status,
gss_name_t acceptor_principal_name,
rpc_auth_key_retrieval_fn_t get_key_fn,
void *arg );
Parameters
Input
acceptor_principal_name Specifies the principal name to use for
the context acceptor.
get_key_fn Specifies either the DCE default
key-retrieval routine or the address of
a routine that returns encryption keys.
arg Specifies an argument to pass to the
key acquisition routine specified in
get_key_fn. To specify the DCE default,
use NULL.
Output
minor_status Returns a status code from the security
mechanism.
Usage
The gssdce_register_acceptor_identity routine registers the server
principal name as an identity claimed by the context acceptor and
tells DCE security where to find the key table containing the
principal's key information.
The gssdce_register_acceptor_identity routine uses the get_key_fn and
arg parameters of the rpc_server_register_auth_info routine to find
the key for the token for the context acceptor's principal name. The
following table lists the values for the parameters and the key
tables to which they point.
ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
Γöé Retrieval routine Γöé Key Table arg Γöé Explanation Γöé
Γöé get_key_fn Γöé Γöé Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé NULL Γöé NULL Γöé Uses the default DCE Γöé
Γöé Γöé Γöé retrieval routine to Γöé
Γöé Γöé Γöé get the key from the Γöé
Γöé Γöé Γöé DCE key table using Γöé
Γöé Γöé Γöé the default key Γöé
Γöé Γöé Γöé table, Γöé
Γöé Γöé Γöé dcelocal\krb5\v5srvtaΓöé.
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé NULL Γöé string=key_table_name Γöé Uses the default DCE Γöé
Γöé Γöé Γöé retrieval routine to Γöé
Γöé Γöé Γöé get the key from a Γöé
Γöé Γöé Γöé key table whose name Γöé
Γöé Γöé Γöé you specify using Γöé
Γöé Γöé Γöé the argument string. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé routine_address Γöé user_written_routine Γöé Uses a user-written Γöé
Γöé Γöé Γöé retrieval routine to Γöé
Γöé Γöé Γöé get the key from a Γöé
Γöé Γöé Γöé key table specified Γöé
Γöé Γöé Γöé in the routine. Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
For more information on registering a server with DCE, refer to the
rpc_server_register_auth_info routine.
Return Codes
This routine returns the following major status codes:
GSS_S_COMPLETE The routine was completed successfully.
GSS_S_FAILURE The routine failed. Check the minor_status parameter
for details.
Related Information
Routines:
rpc_server_register_auth_info
gss_accept_sec_context
ΓòÉΓòÉΓòÉ 8.4.14. gssdce_set_cred_context_ownership ΓòÉΓòÉΓòÉ
Purpose
Changes the ownership of a DCE credential's login context.
Format
#include <dce/gssapi.h>
OM_uint32 gssdce_set_cred_context_ownership (
OM_uint32 *minor_status,
gss_cred_id_t credential_handle,
int ownership);
Parameters
Input
credential_handle Specifies the handle of the DCE credential to be
modified.
ownership Specifies the owner of the DCE credential. Specify one
of the following:
GSSDCE_C_OWNERSHIP_GSSAPI Specifies that the
credential's login context is owned
by GSSAPI.
GSSDCE_C_OWNERSHIP_APPLICATION Specifies that the
credential's login context is owned
by the application.
Output
minor_status Returns a status code from the security mechanism.
Usage
The gssdce_set_cred_context_ownership routine modifies the ownership
of a DCE credential's login context. The INIT and BOTH credentials
have DCE login contexts. Normally, these internal login contexts are
deleted when the credential is released (when the application calls
the gss_release_cred routine). However, for credentials created by
the gssdce_cred_to_login_context and credentials passed to the
gsscdce_cred_to_login_context routine, the application can have an
external reference to the credential's login context and may still be
using the login context. GSSAPI does not delete internal login
contexts of these credentials when they are released.
This routine allows the application to modify the ownership of a
credential's login context. If ownership is changed to
GSSDCE_C_OWNERSHIP_GSSAPI, the login context is deleted when GSSAPI
releases the credential. If ownership is changed to
GSSDCE_C_OWNERSHIP_APPLICATION, the application is responsible for
deleting the login context. DCE credential login contexts that are
owned by an application must not be deleted until the credential is
released, because GSSAPI may still need to access the credential's
login context.
Related Information
Routines:
gss_acquire_cred
gss_release_cred
gssdce_cred_to_login_context
ΓòÉΓòÉΓòÉ 8.4.15. gssdce_test_oid_set_member ΓòÉΓòÉΓòÉ
Purpose
Checks an OID set to see if a specified OID is in the set.
Format
#include <dce/gssapi.h>
OM_uint32 gssdce_test_oid_set_member (
OM_uint32 *minor_status,
gss_OID member_OID,
gss_OID_set set,
int *is_present );
Parameters
Input
member_OID Specifies the OID to search for in the OID set.
set Specifies the OID set to check.
Output
is_present Returns one of the following values to indicate whether
the OID is a member of the OID set:
Returns... If...
1 The OID is present as a member of the
OID set.
0 The OID is absent, not a member of the
OID set.
minor_status Returns a status code from the security mechanism.
Usage
The gssdce_test_oid_set_member routine checks an OID set to see if
the specified OID is a member of the set. To add a member to an OID
set, use the gssdce_add_oid_set_member routine.
The gssdce_test_oid_set_member routine uses the value of the
actual_mechs output parameter from the gss_acquire_cred routine to
get the list of OIDs. It checks this list to see if any of the OIDs
are members of the OID set.
Return Codes
This routine returns the following major status codes:
GSS_S_COMPLETE The routine was completed successfully. Check the
minor_status parameter for details.
Related Information
Routines:
gssdce_add_oid_set_member
gss_acquire_cred
gss_indicate_mechs
ΓòÉΓòÉΓòÉ 8.4.16. gss_accept_sec_context ΓòÉΓòÉΓòÉ
Purpose
Establishes a security context between the application and a context
acceptor.
Format
#include <dce/gssapi.h>
OM_uint32 gss_accept_sec_context (
OM_uint32 *minor_status,
gss_ctx_id_t *context_handle,
gss_cred_id_t verifier_cred_handle,
gss_buffer_t input_token_buffer,
gss_channel_bindings_t input_chan_bindings,
gss_name_t *src_name,
gss_OID *actual_mech_type,
gss_buffer_t output_token,
int *ret_flags,
OM_uint32 *time_rec
gss_cred_id_t *delegated_cred_handle);
Parameters
Input
verifier_cred_handle Specifies the credential handle (the identity)
claimed by the context acceptor. This is optional
information. The credential must be either an ACCEPT
type credential or a BOTH type credential. If you do
not specify a credential handle and specify instead
GSS_C_NO_CREDENTIAL, the application can accept a
context under any registered identity. Use the
gssdce_register_acceptor_identity routine to register
an identity before specifying GSS_C_NO_CREDENTIAL.
input_token_buffer Specifies the token received from the context
acceptor.
input_chan_bindings Specifies bindings supplied by the context
initiator.
Allows the context initiator to bind the channel
identification information securely to the security
context.
Input/Output
context_handle Specifies a context handle for a new context. The
first time the context acceptor uses the routine,
specify GSS_C_NO_CONTEXT to set up a specific context.
In subsequent calls, use the value returned by this
parameter.
Note: If the call returns an error, either the context
is 0 (the context was not created) or the
context was created and returned but is in a
closed state. You can determine from the
minor_status return code whether the context was
created and its status. If the context was
created, you may decide to reuse it.
Output
src_name Returns the authenticated name of the context
initiator. This information is optional. If the
authenticated name is not required, specify NULL.
To deallocate the authenticated name, pass it to the
gss_release_name routine.
actual_mech_type Returns the security mechanism with which the
context was established. The security mechanism is one
of the following:
o GSSDCE_C_OID_DCE_KRBV5_DES for DCE Security.
o GSSDCE_C_OID_KRBV5_DES for Kerberos Version 5.
output_token Returns a token to pass to the context acceptor. If no
token is to be passed to the context acceptor, the
routine sets the length field of the returned token
buffer to 0 (zero).
ret_flags Returns a bit-mask containing six independent flags,
each of which indicates support of a specified service
option. The following symbolic names are provided to
correspond to each flag. The symbolic names should be
joined by means of a logical AND with the value of
ret_flags to test whether the context supports the
service option.
GSS_C_DELEG_FLAG
TRUE The creation of delegated credentials is
supported.
FALSE The creation of delegated credentials is
not supported.
GSS_C_MUTUAL_FLAG
TRUE Mutual authentication is supported.
FALSE Mutual authentication is not supported.
GSS_C_REPLAY_FLAG
TRUE The detection of replayed signed or
sealed messages is supported.
FALSE The detection of replayed signed or
sealed messages is not supported.
GSS_C_SEQUENCE_FLAG
TRUE The detection of out-of-sequence signed
or sealed messages is supported.
FALSE The detection of out-of-sequence signed
or sealed messages is not supported.
GSS_C_CONF_FLAG
TRUE Confidentiality services are available
by calling the gss_seal routine.
FALSE Confidentiality services are not
available. However, the application can
call the gss_seal routine to provide
message encapsulation, data-origin
authentication, and integrity services.
GSS_C_INTEG_FLAG
TRUE Integrity services can be invoked by
calling either the gss_sign or gss_seal
routine.
FALSE Integrity services for individual
messages are not available.
time_rec Returns the number of seconds the context remains
valid. This is optional information. If the time is not
required, specify NULL.
delegated_cred_handle Returns the credential handle for credentials
received from the context initiator. The credential
handle is valid only if delegated credentials are
available. If the ret_flags parameter is true, the flag
GSS_C_DELEG_FLAG is set, indicating that delegated
credentials are available.
minor_status Returns a status code from the security mechanism.
Usage
The gss_accept_sec_context routine is the second step in establishing
a security context between the context initiator and a context
acceptor. In the first step, the context initiator calls the
gss_init_sec_context routine. The gss_init_sec_context routine
generates a token for the security context and passes it to the
context initiator, and sets the major status to GSS_S_Continue. The
context initiator sends the token to the context acceptor.
In the second step, the context acceptor accepts the token from the
context initiator and calls the gss_accept_sec_context routine, which
uses the token as its input_token parameter.
The gss_accept_sec_context routine returns a value in the
output_token parameter. The context acceptor passes this token back
to the context initiator, which presents the token to the
gss_init_sec_context routine. The presence of this token tells the
gss_init_sec_context routine that this is the second call from the
context initiator. If the acceptor does not need to send a token to
the initiator, gss_accept_sec_context sets the length field of the
output_token parameter to 0 (zero).
To finish establishing the context, the context initiator can require
one or more reply tokens from the context acceptor. If the
application requires reply tokens, the gss_accept_sec_context routine
returns a status value containing GSS_S_CONTINUE_NEEDED. The
application calls the routine again when the reply token is received
from the context acceptor. The application passes the token to the
gss_accept_sec_context routine by means of the output_token
parameter.
The gss_accept_sec_context routine must find a key to decrypt the
token. The token contains the unencrypted principal name of the
context acceptor. The acceptor's principal name identifies the key
that the context initiator used to encrypt the rest of the token. The
gss_accept_sec_context routine matches the principal name with the
key in the following ways:
o If you specify a credential, the credential and the name in the
token must match. The acceptor's principal name (contained in
the token) has been registered by a call to the
gssdce_register_acceptor_identity routine. The
gss_accept_sec_context routine looks in the registered key
table.
o If you specify GSS_C_NO_CRED and the principal name in the token
is registered, the gss_accept_sec_context routine, using either
the rpc_server_register_auth_info routine or the
gssdce_register_acceptor_identity routine, looks in the table
specified when you registered the token name.
o If you specify GSS_C_NO_CRED and the principal name in the token
is not registered, the gss_accept_sec_context routine fails and
returns the status GSS_S_FAILURE because the GSSAPI does not
know where to find the key.
The following table summarizes how the gss_accept_sec_context routine
determines the key for the credential:
ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
Γöé You specify... Γöé Is the princi- Γöé Then the routine... Γöé
Γöé Γöé pal's name reg- Γöé Γöé
Γöé Γöé istered? Γöé Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé A credential Γöé Yes Γöé Looks in the key table specified Γöé
Γöé Γöé Γöé in Γöé
Γöé Γöé Γöé gssdce_register_acceptor_identityΓöé
Γöé Γöé Γöé or the default key table. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé GSS_C_NO_CRED Γöé Yes Γöé Looks in the key table specified Γöé
Γöé Γöé Γöé in Γöé
Γöé Γöé Γöé gssdce_register_acceptor_identityΓöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé Γöé No Γöé Fails because the principal is Γöé
Γöé Γöé Γöé not registered. It returns the Γöé
Γöé Γöé Γöé status code GSS_S_FAILURE. Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
The values returned using the src_name, ret_flags, time_rec, and
delegated_cred_handle parameters are not defined unless the routine
returns the status GSS_S_COMPLETE.
Return Codes
This routine returns the following major status codes:
GSS_S_COMPLETE The routine completed successfully.
GSS_S_BAD_BINDINGS The input_token parameter contains
different channel bindings from those
specified with the input_chan_bindings
parameter.
GSS_S_DEFECTIVE_CREDENTIAL Consistency checks performed on the
credential failed.
GSS_S_DEFECTIVE_TOKEN Consistency checks performed on the
input_token parameter failed.
GSS_S_DUPLICATE_TOKEN The input_token parameter was already
processed. This is an irrecoverable error
that occurs during context establishment.
GSS_S_FAILURE The routine failed. See the minor_status
parameter for more information.
GSS_S_NO_CONTEXT The supplied context handle did not refer
to a valid context.
GSS_S_NO_CRED Indicates that either the supplied
credentials were not valid for context
acceptance or the credential handle did
not reference any credentials.
GSS_S_OLD_TOKEN The input_token parameter was too old.
This is an irrecoverable error that occurs
during context establishment.
Related Information
Routines:
gss_acquire_cred
gss_delete_sec_context
gss_init_sec_context
gssdce_register_acceptor_identity
gss_release_name
gss_seal
gss_sign
ΓòÉΓòÉΓòÉ 8.4.17. gss_acquire_cred ΓòÉΓòÉΓòÉ
Purpose
Allows an application to acquire a handle for an existing named
credential.
Format
#include <dce/gssapi.h>
OM_uint32 gss_acquire_cred (
OM_uint32 *minor_status,
gss_name_t desired_name,
OM_uint32 time_req,
gss_OID_set desired_mechs,
int cred_usage,
gss_cred_id_t *output_cred_handle,
gss_OID_set *actual_mechs,
OM_int32 *time_rec);
Parameters
Input
desired_name Specifies the principal name to use for the credential.
time_req Specifies the number of seconds that credentials remain
valid.
desired_mechs Specifies the OID set for the security mechanism to use
with the credential, as follows:
To use... Specify...
DCE Security
GSS_C_NULL_OID_SET
Kerberos
GSSDCE_C_OID_KRBV5_DES
Both DCE Security and Kerberos
GSSDCE_C_OID_DCE_KRBV5_DES
and
GSSDCE_C_OID_KRBV5_DES
To ensure portability of your application, request the
default security mechanism by specifying
GSS_C_NULL_OID_SET.
cred_usage Indicates one of the following:
GSS_C_BOTH Specifies credentials that the
context initiator can use to either
initiate or accept security
contexts.
GSS_C_ACCEPT Specifies credentials that the
context initiator can use only to
accept security contexts.
Output
output_cred_handle Returns the handle for the return credential.
actual_mechs Returns a set of mechanisms for which the credential is
valid. This information is optional. If you do not
want a set of mechanisms returned, specify NULL.
time_rec Returns the actual number of seconds the return
credential remains valid. This information is
optional. If the actual number of seconds is not
required, specify NULL.
minor_status Returns a status code from the security mechanism.
Usage
The gss_acquire_cred routine allows an application to obtain a handle
for either an ACCEPT or a BOTH credential. The application then
passes the credential handle to either the gss_init_sec_context or
gss_accept_sec_context routine.
Credential handles created by the gss_acquire_cred routine contain a
principal name. If the principal name is unregistered, the
gss_acquire_cred routine automatically registers the principal in the
default key table. You can change the principal's key table by
calling the gssdce_register_acceptor_identity routine.
To create an INITIATE credential, you must use the
gssdce_login_context_to_cred routine.
Return Codes
This routine returns the following major status codes:
GSS_S_COMPLETE The routine was completed successfully.
GSS_S_BAD_NAME A name that is not valid was passed by the
desired_name parameter.
GSS_S_FAILURE The routine failed. See the minor_status parameter for
more information.
GSS_S_NO_CRED The routine requested the default login context, but no
default login context was available.
Related Information
Routines:
gss_accept_sec_context gssdce_create_empty_oid_set
gssdce_login_context_to_cred gssdce_register_acceptor_identity
gss_init_sec_context
ΓòÉΓòÉΓòÉ 8.4.18. gss_compare_name ΓòÉΓòÉΓòÉ
Purpose
Allows an application to compare two internal names to determine
whether they refer to the same object.
Format
#include <dce/gssapi.h>
OM_uint32 gss_compare_name (
OM_uint32 *minor_status,
gss_name_t name1,
gss_name_t name2,
int *name_equal);
Parameters
Input
name1 Specifies the first internal name.
name2 Specifies the second internal name.
Output
name_equal Returns one of the following values:
TRUE The names refer to the same object.
FALSE The names are not known to refer to the
same object.
minor_status Returns a status code from the security mechanism.
Usage
The gss_compare_name routine lets an application compare two internal
names to determine whether they refer to the same object.
Return Codes
This routine returns the following major status codes:
GSS_S_COMPLETE The routine was completed successfully.
Related Information
Routines:
gss_display_name
gss_import_name
gss_release_name
ΓòÉΓòÉΓòÉ 8.4.19. gss_context_time ΓòÉΓòÉΓòÉ
Purpose
Checks the number of seconds the context remains valid.
Format
#include <dce/gssapi.h>
OM_uint32 gss_context_time (
OM_uint32 *minor_status,
gss_ctx_id_t context_handle,
OM_int32 *time_rec);
Parameters
Input
context_handle Specifies the context to be checked.
Output
time_rec Returns the number of seconds that the context remains
valid. Returns a 0 (zero) if the context has already
expired.
minor_status Returns a status code from the security mechanism.
Usage
The gss_context_time routine checks the number of seconds for which
the context remains valid.
Return Codes
This routine returns the following major status codes:
GSS_S_COMPLETE The routine was completed successfully.
ΓòÉΓòÉΓòÉ 8.4.20. gss_delete_sec_context ΓòÉΓòÉΓòÉ
Purpose
Deletes a security context.
Format
#include <dce/gssapi.h>
OM_uint32 gss_delete_sec_context (
OM_uint32 *minor_status,
gss_ctx_id_t *context_handle,
gss_buffer_t output_token_buffer);
Parameters
Input
context_handle The context handle for the context to delete.
Output
output_token_buffer Returns a token to tell the application to delete
the context.
minor_status Returns a status code from the security mechanism.
Usage
The gss_delete_sec_context routine deletes a security context. It
also deletes the local data structures associated with the security
context. When it deletes the context, the routine can generate a
token. The application passes the token to the context acceptor.
The context acceptor then passes the token to the
gss_process_context_token routine, telling it to delete the context
and all associated local data structures.
When the context is deleted, the applications cannot use the
context_handle parameter for additional security services.
Return Codes
This routine returns the following major status codes:
GSS_S_COMPLETE The routine was completed successfully.
GSS_S_FAILURE The routine failed. See the minor_status
parameter for more information.
GSS_S_NO_CONTEXT The supplied context handle did not refer to a
valid context.
Related Information
Routines:
gss_accept_sec_context
gss_init_sec_context
gss_process_context_token
ΓòÉΓòÉΓòÉ 8.4.21. gss_display_name ΓòÉΓòÉΓòÉ
Purpose
Provides the textual representation of an opaque internal name to an
application.
Format
#include <dce/gssapi.h>
OM_uint32 gss_display_name (
OM_uint32 *minor_status,
gss_name_t input_name,
gss_buffer_t output_name_buffer,
gss_OID *output_name_type);
Parameters
Input
input_name Specifies the name to convert to text.
Output
output_name_buffer Returns the name as a character string.
output_name_type Returns the type of name to display as a pointer to
static storage. The application should treat this as
read-only.
minor_status Returns a status code from the security mechanism.
Usage
The gss_display_name routine provides an application with the text
form of an opaque internal name. The application can use the text to
display the name but not to print it.
Return Codes
This routine returns the following major status codes:
GSS_S_COMPLETE The routine was completed successfully.
GSS_S_BAD_NAME A name that is not valid was passed by the input_name
parameter.
GSS_S_FAILURE The routine failed. Check the minor_status parameter
for details.
Related Information
Routines:
gss_compare_name
gss_import_name
gss_release_name
ΓòÉΓòÉΓòÉ 8.4.22. gss_display_status ΓòÉΓòÉΓòÉ
Purpose
Provides an application with the textual representation of a GSSAPI
status code that can be displayed to a user or used for logging.
Format
#include <dce/gssapi.h>
OM_uint32 gss_display_status (
OM_uint32 *minor_status,
OM_uint32 status_value,
int status_type,
gss_OID mech_type,
int *message_context,
gss_buffer_t status_string);
Parameters
Input
status_value Specifies the status value to convert.
status_type Specifies one of the following status types:
GSS_C_GSS_CODE Major status; a GSS status
code.
GSS_C_MECH_CODE Minor status; either DCE
Security or Kerberos status
code.
mech_type Specifies the security mechanism. To use DCE Security,
specify either GSSDCE_C_OID_DCE_KRBV5_DES or
GSS_C_NULL_OID_SET.
To use Kerberos, specify GSSDCE_C_OID_KRBV5_DES.
Input/Output
message_context Indicates whether the status code has multiple
messages to read.
The first time an application calls the routine,
initialize the parameter to 0 (zero). The routine
returns the first message. If there are more messages,
the routine sets the parameter to a non-zero value.
The application calls the routine repeatedly to get the
next message, until the message_context parameter is
zero again.
Output
status_string Returns the status value as a text message.
minor_status Returns a status code from the security mechanism.
Usage
The gss_display_status routine provides the context initiator with a
textual representation of a status code so that the application can
display the message to a user or log the message. Because some status
values can indicate more than one error, the routine enables the
calling application to process status codes with multiple messages.
The message_context parameter indicates the error message the
application should extract from the status_value parameter. The first
time an application calls the routine, it should initialize the
message_context parameter to 0 (zero) and return the first message.
If there are additional messages to read, the gss_display_status
routine returns a non-zero value. The application can call
gss_display_status repeatedly to generate a single text string for
each call.
Return Codes
This routine returns the following major status codes:
GSS_S_COMPLETE The routine was completed successfully.
GSS_S_BAD_MECH The translation requires a mechanism that is
unsupported or unavailable.
GSS_S_BAD_STATUS Indicates that either the status value was not
recognized or the status type was something
other than GSS_C_GSS_CODE or GSS_C_MECH_CODE
GSS_S_FAILURE The routine failed. Check minor_status for
details.
ΓòÉΓòÉΓòÉ 8.4.23. gss_import_name ΓòÉΓòÉΓòÉ
Purpose
Converts a printable name to an internal form.
Format
#include <dce/gssapi.h>
OM_uint32 gss_import_name (
OM_uint32 *minor_status,
gss_buffer_t input_name_buffer,
gss_OID input_name_type,
gss_name_t *output_name);
Parameters
Input
input_name_buffer Specifies the buffer containing the printable name
to convert.
input_name_type Specifies the object identifier for the type of
printable name. Specify GSS_C_NULL_OID to use the DCE
name.
You can explicitly request the DCE name by using
GSS_C_OID_DCE_NAME. To ensure portability of your
application, use the default, GSS_C_NULL_OID.
Output
output_name Returns the name in an internal form.
minor_status Returns a status code from the security mechanism.
Usage
The gss_import_name routine converts a printable name to an internal
form.
Return Codes
This routine returns the following major status codes:
GSS_S_COMPLETE The routine was completed successfully.
GSS_S_BAD_NAMETYPE The name passed by the input_name_buffer
parameter is not recognized.
GSS_S_BAD_NAME The routine could not interpret the
input_name_buffer parameter as a name of the type
specified.
Related Information
Routines:
gss_compare_name
gss_display_name
gss_release_name
ΓòÉΓòÉΓòÉ 8.4.24. gss_indicate_mechs ΓòÉΓòÉΓòÉ
Purpose
Allows an application to determine the underlying security mechanisms
that are available.
Format
#include <dce/gssapi.h>
OM_uint32 gss_indicate_mechs (
OM_uint32 *minor_status,
gss_OID_set *mech_set);
Parameters
Output
mech_set Returns the set of supported security mechanisms. The
value of gss_OID_set is a pointer to a static storage
and should be treated as read-only by the context
initiator.
minor_status Returns a status code from the security mechanism.
Usage
The gss_indicate_mechs routine enables an application to determine
the underlying security mechanisms that are available. These are DCE
Security and Kerberos Version 5.
You can use the gssdce_test_oid_set_member routine to check whether a
specific security mechanism is available.
Return Codes
This routine returns the following major status codes:
GSS_S_COMPLETE The routine was completed successfully.
Related Information
Routines:
gssdce_test_oid_set_member
ΓòÉΓòÉΓòÉ 8.4.25. gss_init_sec_context ΓòÉΓòÉΓòÉ
Purpose
Establishes a security context between the context initiator and a
context acceptor.
Format
#include <dce/gssapi.h>
OM_uint32 gss_init_sec_context (
OM_uint32 *minor_status,
gss_cred_id_t claimant_cred_handle,
gss_ctx_id_t *context_handle,
gss_name_t target_name,
gss_OID mech_type,
int req_flags,
OM_uint32 time_req,
gss_channel_bindings_t input_channel_bindings,
gss_buffer_t input_token,
gss_OID *actual_mech_types,
gss_buffer_t output_token,
int *ret_flags,
OM_uint32 *time_rec);
Parameters
Input
claimant_cred_handle Specifies an optional handle for the
credential. To use the default credential,
supply GSS_C_NO_CREDENTIAL. The credential
handle created refers to the DCE default login
context. The credential must be either an
INITIATE or a BOTH type credential.
target_name Specifies the name of the context acceptor.
mech_type Specifies the security mechanism. To use DCE
Security, specify either
GSSDCE_C_OID_DCE_KRBV5_DES and or
GSS_C_NULL_OID. To use Kerberos, specify
GSSDCE_C_OID_KRBV5_DES.
req_flags Specifies four independent flags, each of
which requests that the context support a
service option. The following symbolic names
are provided to correspond to each flag. The
symbolic names should be joined with a logical
OR to form a bit-mask value.
GSS_C_DELEG_FLAG
TRUE The support of delegated
credentials is requested.
FALSE The support of delegated
credentials is not requested.
GSS_C_MUTUAL_FLAG
TRUE The support of mutual
authentication is requested.
FALSE The support of mutual
authentication is not
requested.
GSS_C_REPLAY_FLAG
TRUE The support of detection of
replayed signed or sealed
messages is requested.
FALSE The support of detection of
replayed signed or sealed
messages is not requested.
GSS_C_SEQUENCE_FLAG
TRUE The support of detection of
out-of-sequence signed or
sealed messages is requested.
FALSE The support of detection of
out-of-sequence signed or
sealed messages is requested.
time_req Specifies the desired number of seconds for
which the context should remain valid. To
specify the default validity period, use 0
(zero).
input_channel_bindings Specifies the bindings set by the context
initiator. Allows the context initiator to
bind the channel identification information
securely to the security context.
input_token Specifies the token received from the context
acceptor. The first time the application calls
the routine, specify GSS_C_NO_BUFFER.
Subsequent calls require a token from the
context acceptor.
Input/Output
context_handle Specifies the context handle for the new context. The
first time the application calls the routine, specify
GSS_C_NO_CONTEXT. Subsequent calls use the value
returned by the first call.
Output
actual_mech_types Returns one of the following values indicating the
security mechanism:
o GSSDCE_C_OID_DCE_KRBV5_DES, for DCE Security.
o GSSDCE_C_OID_KRBV5_DES, for Kerberos.
output_token Returns the token to send to the context acceptor. If
the length field of the returned buffer is 0 (zero), no
token is sent.
ret_flags Returns six independent flags, each of which indicates
that the context supports a service option. The
following symbolic names are provided to correspond to
each flag:
GSS_C_DELEG_FLAG
TRUE The creation of delegated credentials is
supported.
FALSE The creation of delegated credentials is
not supported.
GSS_C_MUTUAL_FLAG
TRUE Mutual authentication is supported.
FALSE Mutual authentication is not supported.
GSS_C_REPLAY_FLAG
TRUE The detection of replayed signed or
sealed messages is supported.
FALSE The detection of replayed signed or
sealed messages is not supported.
GSS_C_SEQUENCE_FLAG
TRUE The detection of out-of-sequence signed
or sealed messages is supported.
FALSE The detection of out-of-sequence signed
or sealed messages is not supported.
GSS_C_CONF_FLAG
TRUE Confidentiality service can be invoked
by calling the gss_seal routine.
FALSE No confidentiality service is available.
(Confidentiality can be provided using
the gss_seal routine, which provides
only message encapsulation, data-origin
authentication, and integrity services.)
GSS_C_INTEG_FLAG
TRUE Integrity service can be invoked by
calling either the gss_sign or the
gss_seal routine.
FALSE Integrity service for individual
messages is unavailable.
time_rec Returns the number of seconds the context is valid. If
the mechanism does not support credential expiration,
the routine returns the value GSS_C_INDEFINITE. If the
credential expiration time is not required, specify
NULL.
minor_status Returns a status code from the security mechanism.
Usage
The gss_init_sec_context routine is the first step in establishing a
security context between the context initiator and the context
acceptor. To ensure the portability of the application, use its
default credential by supplying GSS_C_NO_CREDENTIAL to the
claimant_cred_handle parameter. Specify an explicit credential when
the application needs an additional credential, for example, to use
delegation.
The first time the application calls the gss_init_sec_context
routine, specify the input_token parameter as GSS_NO_BUFFER. Calls to
the routine can return an output_token for transfer to the context
acceptor. The context acceptor presents the token to the
gss_accept_sec_context routine.
If the context initiator does not require a token,
gss_init_sec_context sets the length field of the output_token
argument to 0 (zero).
To finish establishing the context, the calling application can
require one or more reply tokens from the context acceptor. If the
application requires reply tokens, the gss_init_sec_context routine
returns a status value of GSS_S_CONTINUE_NEEDED. The application
calls the routine again when the reply token is received from the
context acceptor and passes the token to the gss_init_sec_context
routine by means of the input_token parameter.
The values returned by the ret_flags and time_rec parameters are not
defined unless the routine returns the status GSS_S_COMPLETE.
Return Codes
This routine returns the following major status codes:
GSS_S_COMPLETE The routine was completed successfully.
input_chan_bindings parameter.
GSS_S_BAD_NAME The target_name parameter was incorrectly
formed.
GSS_S_CONTINUE_NEEDED To complete the context, the
gss_init_sec_context routine must be
called again with a token required from
the context acceptor.
GSS_S_DEFECTIVE_CREDENTIAL Consistency checks performed on the
credential failed.
GSS_S_DEFECTIVE_TOKEN Consistency checks performed on the
input_token parameter failed.
GSS_S_FAILURE The routine failed. See the minor_status
parameter for more information.
GSS_S_NO_CONTEXT The supplied context handle did not refer
to a valid context.
GSS_S_NO_CRED Indicates that either the supplied
credentials were not valid for context
acceptance or the credential handle did
not reference any credentials.
GSS_S_BAD_MECH The translation requires a mechanism that
is unsupported or unavailable.
Related Information
Routines:
gss_accept_sec_context
gss_delete_sec_context
ΓòÉΓòÉΓòÉ 8.4.26. gss_inquire_cred ΓòÉΓòÉΓòÉ
Purpose
Provides information about a credential to the calling application.
Format
#include <dce/gssapi.h>
OM_uint32 gss_inquire_cred (
OM_uint32 *minor_status,
gss_cred_id_t cred_handle,
gss_name_t *name,
OM_uint32 *lifetime,
int *cred_usage,
gss_OID_set *mechs);
Parameters
Input
cred_handle Specifies a handle for the target credential. To get
information about the default credential, specify
GSS_C_NO_CREDENTIAL.
Output
name Returns the principal name asserted by the credential.
If the principal name is not required, specify NULL
lifetime Returns the number of seconds for which the credential
remains valid. If the credential expired, the parameter
returns a 0 (zero). If there is no credential
expiration, the parameter returns the value
GSS_C_INDEFINITE. If an expiration time is not
required, specify NULL.
cred_usage Returns one of the following values, which describes
how the application can use the credential:
o GSS_C_INITIATE
o GSS_C_ACCEPT
o GSS_C_BOTH
If no usage information is required, specify NULL.
mechs Returns a set of security mechanisms supported by the
credential:
o GSSDCE_C_OID_DCE_KRBV5_DES, for DCE Security.
o GSSDCE_C_OID_KRBV5_DES for Kerberos.
minor_status Returns a status code from the security mechanism.
Usage
The gss_inquire_cred routine provides information about a credential
to the calling application. The calling application must first have
called the gss_acquire_cred routine for a handle for the credential.
Return Codes
This routine returns the following major status codes:
GSS_S_COMPLETE The routine was completed
successfully.
GSS_S_DEFECTIVE_CREDENTIAL The credentials were not valid.
GSS_S_FAILURE The routine failed. Check the
minor_status parameter for details.
Related Information
Routines:
gss_acquire_cred
ΓòÉΓòÉΓòÉ 8.4.27. gss_process_context_token ΓòÉΓòÉΓòÉ
Purpose
Passes a context to the security service.
Format
#include <dce/gssapi.h>
OM_uint32 gss_process_context_token (
OM_uint32 *minor_status,
gss_ctx_id_t context_handle,
gss_buffer_t input_token_buffer);
Parameters
Input
context_handle Specifies the context handle where the security
service processes the token.
input_token_buffer Specifies an opaque pointer to the first byte of
the token to be processed.
Output
minor_status Returns a status code from the security mechanism.
Usage
The gss_process_context_token routine passes tokens generated by the
gss_delete_security_context routine to the security service.
Usually, tokens are associated with either the context establishment
or with per-message security services. If the tokens are associated
with the context establishment, they are passed to the
gss_init_sec_context or gss_accept_sec_context routine. If the tokens
are associated with the per-message security service, they are passed
to the gss_verify or gss_unseal routine. Tokens generated by the
gss_delete_security_context routine are passed by the
gss_process_context_token routine to the security service for
processing.
Return Codes
This routine returns the following major status codes:
GSS_S_DEFECTIVE_TOKEN Consistency checks performed on the
input_token parameter failed.
GSS_S_NO_CONTEXT The supplied context handle did not refer
to a valid context.
GSS_S_BAD_SIG The signature was incorrect.
GSS_S_FAILURE The routine failed. See the minor_status
parameter return value for more
information.
GSS_S_UNSEQ_TOKEN The token was valid and contained the
correct signature but it has been verified
out of sequence. An earlier token signed
or sealed by the remote application has
not been processed locally.
Related Information
Routines:
gss_delete_sec_context
gss_init_sec_context
gss_accept_sec_context
gss_unseal
gss_verify
ΓòÉΓòÉΓòÉ 8.4.28. gss_release_buffer ΓòÉΓòÉΓòÉ
Purpose
Frees storage associated with a buffer.
Format
#include <dce/gssapi.h>
OM_uint32 gss_release_buffer (
OM_uint32 *minor_status,
gss_buffer_t buffer);
Parameters
Input
buffer Specifies the buffer to delete.
Output
minor_status Returns a status code from the security mechanism.
Usage
The gss_release_buffer routine deletes the buffer by freeing the
storage associated with it.
Return Codes
This routine returns the following major status code:
GSS_S_COMPLETE The routine was completed successfully. See the
minor_status parameter for details.
ΓòÉΓòÉΓòÉ 8.4.29. gss_release_cred ΓòÉΓòÉΓòÉ
Purpose
Marks a credential for deletion.
Format
#include <dce/gssapi.h>
OM_uint32 gss_release_cred (
OM_uint32 *minor_status,
gss_cred_id_t *cred_handle);
Parameters
Input
cred_handle Specifies the buffer containing the opaque credential
handle. This information is optional. To release the
default credential, specify GSS_C_NO_CREDENTIAL.
Output
minor_status Returns a status code from the security mechanism.
Usage
The gss_release_cred routine informs the GSSAPI that a credential is
no longer required and marks it for deletion.
Return Codes
This routine returns the following major status codes:
GSS_S_COMPLETE The routine was completed
successfully.
GSS_S_DEFECTIVE_CREDENTIAL The credentials were not valid.
ΓòÉΓòÉΓòÉ 8.4.30. gss_release_name ΓòÉΓòÉΓòÉ
Purpose
Frees storage associated with an internal name that was allocated by
a GSSAPI routine.
Format
#include <dce/gssapi.h>
OM_uint32 gss_release_name (
OM_uint32 *minor_status,
gss_name_t *name);
Parameters
Input
name The internal name to delete.
Output
minor_status Returns a status code from the security mechanism.
Usage
The gss_release_name routine deletes the internal name by freeing the
storage associated with that internal name.
Return Codes
This routine returns the following major status codes:
GSS_S_COMPLETE The routine was completed successfully.
GSS_S_BAD_NAME The name parameter did not contain a valid internal
name. Check the minor_status parameter for details.
Related Information
Routines:
gss_compare_name
gss_display_name
gss_import_name
ΓòÉΓòÉΓòÉ 8.4.31. gss_release_oid_set ΓòÉΓòÉΓòÉ
Purpose
Frees storage associated with a gss_OID_set object.
Format
#include <dce/gssapi.h>
OM_uint32 gss_release_oid_set (
OM_uint32 *minor_status,
gss_OID_set *set);
Parameters
Input
set Specifies the OID set to delete.
Output
minor_status Returns a status code from the security mechanism.
Usage
The gss_release_oid_set routine frees storage that is associated with
the set parameter and that was allocated by a GSSAPI routine.
Return Codes
This routine returns the following major status code:
GSS_S_COMPLETE The routine was completed successfully.
ΓòÉΓòÉΓòÉ 8.4.32. gss_seal ΓòÉΓòÉΓòÉ
Purpose
Cryptographically signs and optionally encrypts a message.
Format
#include <dce/gssapi.h>
OM_uint32 gss_seal (
OM_uint32 *minor_status,
gss_ctx_id_t context_handle,
int conf_req_flag,
int qop_req,
gss_buffer_t input_message_buffer,
int *conf_state,
gss_buffer_t output_message_buffer);
Parameters
Input
context_handle Specifies the context on which the message
is sent.
conf_req_flag Specifies the requested level of
confidentiality and integrity services as
follows:
TRUE Both confidentiality and
integrity services are
requested.
FALSE Only integrity services are
requested.
qop_req Specifies the cryptographic algorithm or
quality of protection. This parameter has
two parts: the high-order 16 bits represent
the confidentiality algorithm selected, and
the low-order 16 bits represent the
integrity algorithm selected.
There are two constants defined for the
confidentiality algorithm:
GSSDCE_C_QOP_CONF_DES The DES
confidentiality algorithm.
GSSDCE_C_QOP_CONF_CDMF The CDMF
confidentiality algorithm.
There are three constants defined for the
integrity algorithm. These values are as
follows:
GSSDCE_C_QOP_INTEG_MD5 Faster supported
signature.
GSSDCE_C_QOP_INTEG_DES_MD5 DES MAC of
an MD5 signature. Faster than
GSSDCE_C_QOP_INTEG_DES_MAC.
GSSDCE_C_QOP_INTEG_DES_MAC Conventional
DES MAC. Slow but well understood.
The value of qop_req can be any combination
of the confidentiality and integrity
algorithms. To construct a qop_req value to
pass into gss_seal, simply OR the
confidentiality and integrity constants as
follows:
qop_req = GSSDCE_C_QOP_CONF_CDMF | GSSDCE_C_QOP_INTEG_MD5;
The default qop_req value is
GSS_C_QOP_DEFAULT (0x00000000), and
represents GSSDCE_C_QOP_CONF_DES
confidentiality and GSSDCE_C_QOP_INTEG_MD5
integrity.
Note: If an integrity algorithm that is not
supported is specified in the qop_req
parameter,
gssdce_s_unsupported_signature_algorithm
is returned in minor_status.
If a confidentiality algorithm that is not
supported was specified in the qop_req
parameter,
gssdce_s_unsupported_encryption_algorithm is
returned in minor_status.
input_message_buffer Specifies the message to seal.
Output
conf_state Returns the requested level of
confidentiality and integrity services as
follows:
TRUE Both confidentiality and
integrity services are
requested.
FALSE Only integrity services are
requested.
output_message_buffer Returns the buffer to receive the sealed
message.
minor_status Returns a status code from the security
mechanism.
Usage
The gss_seal routine cryptographically signs and optionally encrypts
a message. The output_message_buffer token contains both the
signature and the message in a token structure.
Return Codes
This routine returns the following major status codes: termhi=0
compact break=fit.
GSS_S_COMPLETE The routine was completed successfully.
GSS_S_FAILURE The routine failed. Check the minor_status
parameter for details.
GSS_S_NO_CONTEXT The context identified in the
context_handle parameter was not valid.
Related Information
Routines:
gss_unseal
ΓòÉΓòÉΓòÉ 8.4.33. gss_sign ΓòÉΓòÉΓòÉ
Purpose
Generates a cryptographic signature for a message.
Format
#include <dce/gssapi.h>
OM_uint32 gss_sign (
OM_uint32 *minor_status,
gss_ctx_id_t context_handle,
int qop_req,
gss_buffer_t message_buffer,
gss_buffer_t msg_token);
Parameters
Input
context_handle Specifies the context on which the message is sent.
qop_req Specifies the cryptographic algorithm or quality of
protection. This parameter has two parts: the
high-order 16 bits represent the confidentiality
algorithm, which is ignored by this routine, and the
low-order 16 bits, which represent the integrity
algorithm selected.
There are four constants defined for the integrity
algorithm. These values are as follows:
GSSDCE_C_QOP_INTEG_MD5 Faster supported signature.
GSSDCE_C_QOP_INTEG_DES_MD5 DES MAC of an MD5
signature. Faster than
GSSDCE_C_QOP_INTEG_DES_MAC.
GSSDCE_C_QOP_INTEG_DES_MAC Conventional DES MAC.
Slow but well understood.
GSS_C_QOP_DEFAULT (0x00000000), represents
GSSDCE_C_QOP_INTEG_MD5 integrity.
Note: If an integrity algorithm that is not supported
is specified in the qop_req parameter,
gssdce_s_unsupported_signature_algorithm is
returned in minor_status.
message_buffer Specifies the message to send.
Output
msg_token Returns the buffer to receive the signature token to
transfer to the context acceptor.
minor_status Returns a status code from the security mechanism.
Usage
The gss_sign routine generates an encrypted signature for a message.
It places the signature in a token for transfer to the context
acceptor.
Return Codes
This routine returns the following major status codes: termhi=0
compact.
GSS_S_COMPLETE The routine was completed successfully.
GSS_S_FAILURE The routine failed. Check the minor_status
parameter for details.
GSS_S_NO_CONTEXT The context identified in the
context_handle parameter was not valid.
Related Information
Routines:
gss_verify
ΓòÉΓòÉΓòÉ 8.4.34. gss_unseal ΓòÉΓòÉΓòÉ
Purpose
Converts a sealed message into a usable form and verifies the
embedded signature.
Format
#include <dce/gssapi.h>
OM_uint32 gss_unseal (
OM_uint32 *minor_status,
gss_ctx_id_t context_handle,
gss_buffer_t input_message_buffer,
gss_buffer_t output_message_buffer,
int *conf_state,
int *qop_state);
Parameters
termhi=0.
Input
context_handle Specifies the context on which the
message arrived.
input_message_buffer Specifies the sealed message.
output_message_buffer Specifies the buffer to receive the
unsealed message.
termhi=0.
Output
conf_state Returns the requested level of
confidentiality and integrity
services as follows:
TRUE Both confidentiality
and integrity
services are
requested.
FALSE Only integrity
services are
requested.
qop_state Returns the cryptographic algorithm
or quality of protection. This
parameter has two parts: the
high-order 16 bits represent the
confidentiality algorithm selected,
and the low-order 16 bits represent
the integrity algorithm selected.
One of the following two values is
returned for the confidentiality
algorithm:
0x00000000
(GSSDCE_C_QOP_CONF_DES) The
DES confidentiality
algorithm.
0x00010000
(GSSDCE_C_QOP_CONF_CDMF) The
CDMF confidentiality
algorithm.
One of the following three values
is returned for the integrity
algorithm:
0x00000001
(GSSDCE_C_QOP_INTEG_MD5)
Faster supported
signature.
0x00000002
(GSSDCE_C_QOP_INTEG_DES_MD5)
DES MAC of an MD5
signature. Faster than
GSSDCE_C_QOP_INTEG_DES_MAC.
0x00000003
(GSSDCE_C_QOP_INTEG_DES_MAC)
Conventional DES MAC.
Slow but well understood.
If GSS_C_QOP_DEFAULT was the input
value for qop_req in the gss_seal
routine, the return value for
qop_state will be
GSSDCE_C_QOP_CONF_CDMF |
GSSDCE_C_QOP_INTEG_MD5.
minor_status Returns a status code from the
security mechanism.
Usage
The gss_unseal routine converts a sealed message to a usable form and
verifies the embedded signature. The conf_state parameter indicates
whether the message was encrypted. The qop_state parameter is ORed to
return the type of algorithm used for decryption and integrity
verification.
Return Codes
This routine returns the following major status codes: termhi=0
break=fit.
GSS_S_COMPLETE The routine was completed
successfully.
GSS_S_DEFECTIVE_TOKEN The token failed consistency
checks.
GSS_S_DUPLICATE_TOKEN The token was valid and contained
the correct signature, but it had
already been processed.
GSS_S_FAILURE The routine failed. The context
specified in the context_handle
parameter was not valid.
GSS_S_NO_CONTEXT The context identified in the
context_handle parameter was not
valid.
GSS_S_OLD_TOKEN The token was valid and contained
the correct signature but it is too
old.
GSS_S_UNSEQ_TOKEN The token was valid and contained
the correct signature but it has
been verified out of sequence. An
earlier token signed or sealed by
the remote application has not been
processed locally.
Related Information
Routines:
gss_seal
ΓòÉΓòÉΓòÉ 8.4.35. gss_verify ΓòÉΓòÉΓòÉ
Purpose
Checks that the cryptographic signature fits the supplied message.
Format
#include <dce/gssapi.h>
OM_uint32 gss_verify (
OM_uint32 *minor_status,
gss_ctx_id_t context_handle,
gss_buffer_t message_buffer,
gss_buffer_t token_buffer)
int *qop_state);
Parameters
Input
context_handle Specifies the context on which the message arrived.
message_buffer Specifies the message to be verified.
token_buffer Specifies the signature token to be associated with the
message.
Output
qop_state Returns the cryptographic algorithm or quality of
protection from the signature. This parameter has two
parts: the high-order 16 bits represent the
confidentiality algorithm, which is ignored by this
routine, and the low-order 16 bits, which represent the
integrity algorithm selected.
One of the following three values is returned for the
integrity algorithm: These values are as follows:
0x00000001 (GSSDCE_C_QOP_INTEG_MD5) Faster
supported signature.
0x00000002 (GSSDCE_C_QOP_INTEG_DES_MD5) DES MAC of
an MD5 signature. Faster than
GSSDCE_C_QOP_INTEG_DES_MAC.
0x00000003 (GSSDCE_C_QOP_INTEG_DES_MAC)
Conventional DES MAC. Slow but well
understood. If GSS_C_QOP_DEFAULT was the
input value for qop_req in the gss_sign routine, the
return value for qop_state will be
GSSDCE_C_QOP_INTEG_MD5.
Note: If an integrity algorithm that is not supported
is specified in the qop_req parameter,
gssdce_s_unsupported_signature_algorithm is
returned in minor_status.
minor_status Returns a status code from the security mechanism.
Usage
The gss_verify routine checks that an encrypted signature, in the
token_buffer parameter, is the same as the one for the message in the
message_buffer buffer. The application receiving the message can use
the qop_state parameter to check the message's protection.
Return Codes
This routine returns the following major status codes: termhi=0
compact.
GSS_S_COMPLETE The routine was completed
successfully.
GSS_S_FAILURE The routine failed. Check the
minor_status parameter for details.
GSS_S_NO_CONTEXT The context identified in the
context_handle parameter was not
valid.
GSS_S_DEFECTIVE_TOKEN Consistency checks performed on the
input_token parameter failed.
GSS_S_BAD_SIG The signature was incorrect.
Related Information
Routines:
gss_sign
ΓòÉΓòÉΓòÉ 8.5. DCE ID Mapping API ΓòÉΓòÉΓòÉ
The ID Mapping facility consists of routines with the prefix sec_id. There are
no user interfaces to this facility. The routines map a global principal or
group name into a cell name and a cell-relative principal or group name, and
generate a global principal or group name from a cell name and a cell-relative
principal or group name. These routines also convert the internal name (UUID)
to a human-readable string and back again.
The ID Mapping routines are the following:
sec_id_gen_group Generates a global name from cell and group UUIDs.
sec_id_gen_name Generates a global name from cell and principal UUIDs.
sec_id_parse_group Translates a global name into group and cell names and
UUIDs.
sec_id_parse_name Translates a global name into principal and cell names and
UUIDs.
ΓòÉΓòÉΓòÉ 8.5.1. sec_id_gen_group ΓòÉΓòÉΓòÉ
Purpose
Generates a global name from cell and group UUIDs.
Library
\lib\dceos2.lib
Format
#include <dce/secidmap.h>
void sec_id_gen_group(
sec_rgy_handle_t context,
uuid_t *cell_idp,
uuid_t *group_idp,
sec_rgy_name_t global_name,
sec_rgy_name_t cell_namep,
sec_rgy_name_t group_namep,
error_status_t *status);
Parameters
Input
context An opaque handle bound to a registry server. Use
sec_rgy_site_open to acquire a bound handle.
cell_idp A pointer to the UUID of the home cell of the group
name that is in question.
group_idp A pointer to the UUID of the group name that is in
question.
Output
global_name The global (full) name of the group in sec_rgy_name_t
form.
cell_namep The name of the group's home cell in sec_rgy_name_t
form.
group_namep The local (with respect to the home cell) name of the
group in sec_rgy_name_t form.
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns one of the following errors:
sec_id_e_name_too_long The name is too long for
current implementation.
sec_id_e_bad_cell_uuid The cell UUID is not valid.
sec_rgy_object_not_found The registry server could
not find the specified group.
sec_rgy_server_unavailable The DCE Registry Server
is unavailable.
Usage
The sec_id_gen_group routine generates a global name from input cell
and group UUIDs. For example, given a UUID specifying the cell
\...\world\hp\brazil, and a UUID specifying a group resident in that
cell named writers, the routine returns the global name of that
group; in this case, \...\world\hp\brazil\writers. It also returns
the simple names of the cell and group, translated from the UUIDs.
The routine does not produce translations to any name for which a
NULL pointer has been supplied.
Related Information
Routines:
sec_id_gen_name
sec_id_parse_group
sec_id_parse_name
sec_rgy_site_open
Files:
\include\dce\secidmap.idl - The idl file from which dce\secidmap.h
was derived.
ΓòÉΓòÉΓòÉ 8.5.2. sec_id_gen_name ΓòÉΓòÉΓòÉ
Purpose
Generates a global name from cell and principal UUIDs.
Library
\lib\dceos2.lib
Format
#include <dce/secidmap.h>
void sec_id_gen_name(
sec_rgy_handle_t context,
uuid_t *cell_idp,
uuid_t *princ_idp,
sec_rgy_name_t global_name,
sec_rgy_name_t cell_namep,
sec_rgy_name_t princ_namep,
error_status_t *status);
Parameters
Input
context An opaque handle bound to a registry server. Use
sec_rgy_site_open to acquire a bound handle.
cell_idp A pointer to the UUID of the home cell of the principal
name that is in question.
princ_idp A pointer to the UUID of the principal name that is in
question.
Output
global_name The global (full) name of the principal, in
sec_rgy_name_t form.
cell_namep The name of the principal's home cell, in
sec_rgy_name_t form.
princ_namep The local (with respect to the home cell) name of the
principal, in sec_rgy_name_t form.
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns one of the following errors:
sec_id_e_name_too_long The name is too long for
current implementation.
sec_id_e_bad_cell_uuid The cell UUID is not valid.
sec_rgy_object_not_found The registry server could
not find the specified
principal.
sec_rgy_server_unavailable The DCE Registry Server
is unavailable.
Usage
The sec_id_gen_name routine generates a global name from input cell
and principal UUIDs. For example, given a UUID specifying the cell
\...\world\hp\brazil, and a UUID specifying a principal resident in
that cell named writers\tom, the routine would return the global name
of that principal, in this case, \...\world\hp\brazil\writers\tom. It
also returns the simple names of the cell and principal, translated
from the UUIDs.
The routine does not produce translations to any name for which a
NULL pointer has been supplied.
Permissions Required
The sec_id_gen_name routine requires at least one permission of any
kind on the account associated with the input cell and principal
UUIDs.
Related Information
Routines: sec_id_gen_group
sec_id_parse_group
sec_id_parse_name
Files:
\include\dce\secidmap.idl - The idl file from which dce\secidmap.h
was derived.
ΓòÉΓòÉΓòÉ 8.5.3. sec_id_parse_group ΓòÉΓòÉΓòÉ
Purpose
Translates a global name into group and cell names and UUIDs.
Library
\lib\dceos2.lib
Format
#include <dce/secidmap.h>
void sec_id_parse_group(
sec_rgy_handle_t context,
sec_rgy_name_t global_name,
sec_rgy_name_t cell_namep,
uuid_t *cell_idp,
sec_rgy_name_t group_namep,
uuid_t *group_idp,
error_status_t *status);
Parameters
Input
context An opaque handle bound to a registry server. Use
sec_rgy_site_open to acquire a bound handle.
global_name The global (full) name of the group, in sec_rgy_name_t
form.
Output
cell_namep The output name of the group's home cell in
sec_rgy_name_t form.
cell_idp A pointer to the UUID of the home cell of the group
name that is in question.
group_namep The local (with respect to the home cell) name of the
group in sec_rgy_name_t form.
group_idp A pointer to the UUID of the group name that is in
question.
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns one of the following errors:
sec_id_e_name_too_long The name is too long for
current implementation.
sec_id_e_bad_cell_uuid The cell UUID is not valid.
sec_rgy_object_not_found The registry server could
not find the specified group.
sec_rgy_server_unavailable The DCE Registry Server
is unavailable.
Usage
The sec_id_parse_group routine translates a global group name into a
cell name and a cell-relative group name. It also returns the UUIDs
associated with the group and its home cell.
The routine does not produce translations to any name for which a
NULL pointer has been supplied.
Related Information
Routines:
sec_id_gen_group
sec_id_gen_name
sec_id_parse_name
sec_rgy_site_open
ΓòÉΓòÉΓòÉ 8.5.4. sec_id_parse_name ΓòÉΓòÉΓòÉ
Purpose
Translates a global name into principal and cell names and UUIDs.
Library
\lib\dceos2.lib
Format
#include <dce/secidmap.h>
void sec_id_parse_name(
sec_rgy_handle_t context,
sec_rgy_name_t global_name,
sec_rgy_name_t cell_namep,
uuid_t *cell_idp,
sec_rgy_name_t princ_namep,
uuid_t *princ_idp,
error_status_t *status);
Parameters
Input
context An opaque handle bound to a registry server. Use
sec_rgy_site_open to acquire a bound handle.
global_name The global (full) name of the principal, in
sec_rgy_name_t form.
Output
cell_namep The output name of the principal's home cell in
sec_rgy_name_t form.
cell_idp A pointer to the UUID of the home cell of the principal
name that is in question.
princ_namep The local (with respect to the home cell) name of the
principal in sec_rgy_name_t form.
princ_idp A pointer to the UUID of the principal name that is in
question.
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns one of the following errors:
sec_id_e_name_too_long The name is too long for
current implementation.
sec_id_e_bad_cell_uuid The cell UUID is not valid.
sec_rgy_object_not_found The registry server could
not find the specified
principal.
sec_rgy_server_unavailable The DCE Registry Server
is unavailable.
Usage
The sec_id_parse_name routine translates a global principal name into
a cell name and a cell-relative principal name. It also returns the
UUIDs associated with the principal and its home cell.
The routine does not produce translations to any name for which a
NULL pointer has been supplied.
Permissions Required
Only if princ_idp is requested as output does the sec_id_parse_name
routine require a permission. In this case, the routine requires at
least one permission of any kind on the account whose global
principal name is to be translated.
Related Information
Routines: sec_id_gen_name
sec_rgy_site_open
ΓòÉΓòÉΓòÉ 8.6. DCE Key Management API ΓòÉΓòÉΓòÉ
For a distributed application, it can be important for a server to have a
network identity that is distinct from the principal identity it inherits from
the user who calls it or from the host on which it runs. The Key Management
facility enables noninteractive principals to manage their secret keys.
The user interface to the Key Management facility consists of a few rgy_edit
subcommands which call the Key Management API. This API consists of several
routines with the prefix sec_key....
The sections describing the Key Management data types, constants, and routines
are listed as follows:
Key Management Data Types
Key Management Routines
ΓòÉΓòÉΓòÉ 8.6.1. Key Management Data Types ΓòÉΓòÉΓòÉ
sec_passwd_type_t An enumerated set describing the currently supported key
types. The possible values are:
sec_passwd_none Indicates no key types are supported.
sec_passwd_plain Indicates that the key is a printable
string of data.
sec_passwd_des Indicates that the key is DES
encrypted data.
sec_passwd_rec_t A structure containing either a plain text password or a
preencrypted buffer of password data.
Note: Operations that take a keydata parameter expect a pointer to
a sec_passwd_rec_t structure. Operations that yield a keydata
parameter as output set the pointer to an array of
sec_passwd_rec_t structures. (The array is terminated by an
element with key type sec_passwd_none.)
The sec_passwd_rec_t structure consists of three components:
version_number The version number of the password.
pepper A character string combined with the password before
an encryption key is derived from the password.
key A structure consisting of the following components:
key_type The key type can be either of the
following:
sec_passwd_plain Indicates that
tagged_union contains a
printable string of
data stored in plain
format.
sec_passwd_des Indicates that
tagged_union contains
an array of data stored
in des_key format.
tagged_union A structure specifying the
password. The value of the structure
depends on key_type. If key_type is
sec_passwd_plain, the structure
contains plain, a character string. If
key_type is sec_passwd_des, the
structure contains des_key, a DES key
of type sec_passwd_des_key_t.
sec_passwd_version_t An unsigned 32-bit integer that defines the password
version number. You can supply a version number or a 0 for no
version number. If you supply the constant
sec_passwd_c_version_none, the Security service supplies a
system-generated version number.
sec_key_mgmt_authn_service A 32-bit unsigned integer that indicates that the
authentication service in use, because a server can have different
keys for different levels of security. The possible values of this
data type and their meanings are as follows:
rpc_c_authn_none No authentication.
rpc_c_authn_dce_private DCE private key authentication (an
implementation of the Kerberos system).
rpc_c_authn_dce_public DCE public key authentication (reserved
for future use).
ΓòÉΓòÉΓòÉ 8.6.2. Key Management Routines ΓòÉΓòÉΓòÉ
sec_key_mgmt_change_key
sec_key_mgmt_delete_key
sec_key_mgmt_delete_key_type
sec_key_mgmt_free_key
sec_key_mgmt_garbage_collect
sec_key_mgmt_gen_rand_key
sec_key_mgmt_get_key
sec_key_mgmt_get_next_key
sec_key_mgmt_get_next_kvno
sec_key_mgmt_get_nth_key
sec_key_mgmt_initialize_cursor
sec_key_mgmt_manage_key
sec_key_mgmt_release_cursor
sec_key_mgmt_set_key
ΓòÉΓòÉΓòÉ 8.6.3. sec_key_mgmt_change_key ΓòÉΓòÉΓòÉ
Purpose
Changes a principal's key.
Library
\lib\dceos2.lib
Format
#include <dce/keymgmt.h>
void sec_key_mgmt_change_key(
sec_key_mgmt_authn_service authn_service,
void *arg,
unsigned_char *principal_name,
unsigned32 key_vno,
void *keydata,
sec_timeval_period_t *garbage_collect_time,
error_status_t *status);
Parameters
Input
authn_service Identifies the authentication protocol using this key.
The possible authentication protocols are as follows:
rpc_c_authn_dce_secret DCE shared-secret key
authentication
rpc_c_authn_dce_public DCE public key
authentication (reserved
for future use).
arg Specifies either the local key file or a parameter to
the get_key_fn key acquisition routine of the
rpc_server_register_auth_info routine.
A value of NULL specifies that the default key file
v5srvtab should be used. A key file name specifies that
file should be used as the key file. You must prepend
the file's absolute filename with WRFILE: and the file
must have been created with the rgy_edit ktadd command
or the sec_key_mgmt_set_key routine.
Any other value specifies a parameter for the
get_key_fn key acquisition. See
rpc_server_register_auth_info for more information.
principal_name A pointer to a character string indicating the name of
the principal whose key is to be changed.
key_vno The version number of the new key. If zero is
specified, the routine selects the next appropriate key
version number.
keydata A pointer to a structure of type sec_passwd_rec_t.
Output
garbage_collect_time The number of seconds that must elapse before
all currently valid tickets (which are encoded with the
current or previous keys) expire. At that time, all
obsolete keys can be garbage collected, because no
valid tickets encrypted with those keys remain
outstanding on the network.
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns one of the following errors:
sec_key_mgmt_e_key_unavailable The old key is not
present and cannot be
used to set a client side
authentication context.
sec_key_mgmt_e_authn_invalid The authentication
protocol is not valid.
sec_key_mgmt_e_auth_unavailable The authentication
protocol is not available
to update the network
database or obtain the
necessary network
credentials.
sec_key_mgmt_e_unauthorized The caller is not
authorized to perform the
operation.
sec_key_mgmt_e_key_unsupported The key type is not
supported.
sec_key_mgmt_e_key_version_ex A key with this
version number already
exists.
sec_rgy_server_unavailable The DCE Registry Server
is unavailable.
sec_rgy_object_not_found No principal was found
with the given name.
sec_s_no_memory Unable to allocate
memory.
sec_s_bad_key_parity The parity is bad.
Note: Any error condition leaves the key state
unchanged.
Usage
The sec_key_mgmt_change_key routine performs all activities necessary
to update a principal's key to the specified value. This includes
updating any local storage for the principal's key and also
performing any remote operations needed to keep the authentication
protocol (or network registry) current. Old keys for the principal
are garbage collected if appropriate.
Related Information
Routines: rpc_server_register_auth_info
sec_key_mgmt_gen_rand_key
sec_key_mgmt_set_key
ΓòÉΓòÉΓòÉ 8.6.4. sec_key_mgmt_delete_key ΓòÉΓòÉΓòÉ
Purpose
Deletes a key from the local storage.
Library
\lib\dceos2.lib
Format
#include <dce/keymgmt.h>
void sec_key_mgmt_delete_key(
sec_key_mgmt_authn_service authn_service,
void *arg,
unsigned_char *principal_name,
unsigned32 key_vno,
error_status_t *status);
Parameters
Input
authn_service Identifies the authentication protocol using this key.
The possible authentication protocols are as follows:
rpc_c_authn_dce_secret DCE shared-secret key
authentication.
rpc_c_authn_dce_public DCE public key
authentication (reserved for
future use).
arg Specifies either the local key file or a parameter to
the get_key_fn key acquisition routine of the
rpc_server_register_auth_info routine.
A value of NULL specifies that the default key file
v5srvtab should be used. A key file name specifies that
file should be used as the key file. You must prepend
the file's absolute filename with WRFILE: and the file
must have been created with the rgy_edit ktadd command
or the sec_key_mgmt_set_key routine.
Any other value specifies a parameter for the
get_key_fn key acquisition. See
rpc_server_register_auth_info for more information.
principal_name A pointer to a character string indicating the name of
the principal whose key is to be deleted.
key_vno The version number of the desired key.
Output
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns one of the following errors:
sec_key_mgmt_e_key_unavailable The requested key
is not present.
sec_key_mgmt_e_authn_invalid The authentication
protocol is not valid.
sec_key_mgmt_e_unauthorized The caller is not
authorized to perform
the operation.
Note: Any error condition leaves the key state
unchanged.
Usage
The sec_key_mgmt_delete_key routine deletes the specified key from
the local key storage. If an administrator discovers or suspects
that the security of a server's key has been compromised, the
administrator should delete the key immediately with
sec_key_mgmt_delete_key. This routine removes the key from the local
key storage, which invalidates all existing tickets encoded with the
key. If the compromised key is the current one, the principal should
change the key with sec_key_mgmt_change_key before deleting it. It
is not an error for a process to delete the current key (as long as
it is done after the network context has been established), but it
can seriously inconvenience legitimate clients of a service.
This routine deletes all key types that have the specified key
version number. A key type identifies the data encryption algorithm
being used (for example, DES). This routine differs from
sec_key_mgmt_delete_key_type in that sec_key_mgmt_delete_key_type
deletes only the specified key version of the specified key type from
the local key storage.
Related Information
Routines: sec_key_mgmt_change_key
sec_key_mgmt_delete_key_type
sec_key_mgmt_garbage_collect
sec_key_mgmt_set_key
ΓòÉΓòÉΓòÉ 8.6.5. sec_key_mgmt_delete_key_type ΓòÉΓòÉΓòÉ
Purpose
Deletes a key version of a key type from the local key storage.
Library
\lib\dceos2.lib
Format
#include <dce/keymgmt.h>
void sec_key_mgmt_delete_key_type(
sec_key_mgmt_authn_service authn_service,
void *arg,
unsigned_char *principal_name,
void *keytype,
unsigned32 key_vno,
error_status_t *status);
Parameters
Input
authn_service Identifies the authentication protocol using this key.
The possible authentication protocols are as follows:
rpc_c_authn_dce_secret DCE shared-secret key
authentication
rpc_c_authn_dce_public DCE public key
authentication (reserved for
future use).
arg Specifies either the local key file or a parameter to
the get_key_fn key acquisition routine of the
rpc_server_register_auth_info routine.
A value of NULL specifies that the default key file
v5srvtab should be used. A key file name specifies that
file should be used as the key file. You must prepend
the file's absolute filename with WRFILE: and the file
must have been created with the rgy_edit ktadd command
or the sec_key_mgmt_set_key routine.
Any other value specifies a parameter for the
get_key_fn key acquisition routine. See
rpc_server_register_auth_info for more information.
principal_name A pointer to a character string indicating the name of
the principal whose key type is to be deleted.
keytype A pointer to a value of type sec_passwd_type_t. The
value identifies the data encryption algorithm that is
being used (for example, DES).
key_vno The version number of the desired key.
Output
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns one of the following errors:
sec_key_mgmt_e_key_unavailable The requested key
is not present.
sec_key_mgmt_e_authn_invalid The authentication
protocol is not valid.
sec_key_mgmt_e_unauthorized The caller is not
authorized to perform the
operation.
Note: Any error condition leaves the key state
unchanged.
Usage
The sec_key_mgmt_delete_key_type routine deletes the specified key
version of the specified key type from the local key storage. It
differs from sec_key_mgmt_delete_key in that sec_key_mgmt_delete_key
deletes all key types that have the same key version number.
This routine removes the key from the local key storage, which
invalidates all existing tickets encoded with the key. If the key in
question is the current one, the principal should change the key with
sec_key_mgmt_change_key before deleting it. It is not an error for a
process to delete the current key (as long as it is done after the
network context has been established), but it can seriously
inconvenience legitimate clients of a service.
Related Information
Routines: sec_key_mgmt_delete_key
sec_key_mgmt_garbage_collect
rpc_server_register_auth_info
sec_key_mgmt_change_key
ΓòÉΓòÉΓòÉ 8.6.6. sec_key_mgmt_free_key ΓòÉΓòÉΓòÉ
Purpose
Frees the memory used by a key value.
Library
\lib\dceos2.lib
Format
#include <dce/keymgmt.h>
void sec_key_mgmt_free_key(
void *keydata,
error_status_t *status);
Parameters
Input
keydata A pointer to a structure of type sec_passwd_rec_t.
Output
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns an error.
Usage
The sec_key_mgmt_free_key routine releases any storage allocated for
the indicated key data by sec_key_mgmt_get_key. The storage for the
key data returned by sec_key_mgmt_get_key is dynamically allocated.
Related Information
Routines:
sec_key_mgmt_get_key
ΓòÉΓòÉΓòÉ 8.6.7. sec_key_mgmt_garbage_collect ΓòÉΓòÉΓòÉ
Purpose
Deletes obsolete keys.
Library
\lib\dceos2.lib
Format
#include <dce/keymgmt.h>
void sec_key_mgmt_garbage_collect(
sec_key_mgmt_authn_service authn_service,
void *arg,
unsigned_char *principal_name,
error_status_t *status);
Parameters
Input
authn_service Identifies the authentication protocol using this key.
The possible authentication protocols are as follows:
rpc_c_authn_dce_secret DCE shared-secret key
authentication
rpc_c_authn_dce_public DCE public key
authentication (reserved for
future use).
arg This parameter can specify either the local key file or
an argument to the get_key_fn key acquisition routine
of the rpc_server_register_auth_info routine.
A value of NULL specifies that the default key file
v5srvtab should be used. A key file name specifies that
file should be used as the key file. You must prepend
the file's absolute file name with WRFILE: and the file
must have been created with the rgy_edit ktadd command
or the sec_key_mgmt_set_key routine.
Any other value specifies an argument for the
get_key_fn key acquisition routine. See
rpc_server_register_auth_info for more information.
principal_name A pointer to a character string indicating the name of
the principal whose key information is to be garbage
collected.
Output
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns one of the following errors:
sec_key_mgmt_e_authn_invalid The authentication
protocol is not valid.
sec_key_mgmt_e_key_unavailable The requested key
is not present.
sec_key_mgmt_e_unauthorized The caller is not
authorized to perform the
operation.
sec_rgy_server_unavailable The DCE Registry Server
is unavailable.
sec_rgy_object_not_found No principal was found
with the given name.
sec_s_no_memory Unable to allocate memory.
Usage
The sec_key_mgmt_garbage_collect routine discards any obsolete key
information for this principal. An obsolete key is one that can only
decode invalid tickets. As an example, a key that was in use on
Monday and was only used to encode tickets whose maximum lifetime was
one day was changed at 8:00 am on Tuesday morning, it would become
obsolete by 8:00 am Wednesday morning. After that, there could be no
valid tickets outstanding.
Related Information
Routines:
sec_key_mgmt_delete_key
ΓòÉΓòÉΓòÉ 8.6.8. sec_key_mgmt_gen_rand_key ΓòÉΓòÉΓòÉ
Purpose
Generates a new random key of a specified key type.
Library
\lib\dceos2.lib
Format
#include <dce/keymgmt.h>
void sec_key_mgmt_gen_rand_key(
sec_key_mgmt_authn_service authn_service,
void *arg,
unsigned_char *principal_name,
void *keytype,
unsigned32 key_vno,
void **keydata,
error_status_t *status);
Parameters
Input
authn_service Identifies the authentication protocol using this key.
The possible authentication protocols are as follows:
rpc_c_authn_dce_secret DCE shared-secret key
authentication
rpc_c_authn_dce_public DCE public key
authentication (reserved for
future use).
arg This parameter can specify either the local key file or
an argument to the get_key_fn key acquisition routine
of the rpc_server_register_auth_info routine.
A value of NULL specifies that the default key file
v5srvtab should be used. A key file name specifies that
file should be used as the key file. You must prepend
the file's absolute file name with WRFILE: and the file
must have been created with the rgy_edit ktadd command
or the sec_key_mgmt_set_key routine.
Any other value specifies an argument for the
get_key_fn key acquisition routine. See
rpc_server_register_auth_info for more information.
principal_name A pointer to a character string indicating the name of
the principal for whom the key is to be generated.
keytype A pointer to a value of type sec_passwd_type_t. The
value identifies the data encryption algorithm to be
used for the key (for example, DES).
Note: In this release, only the sec_passwd_des key
type is supported.
key_vno The version number of the new key.
Output
keydata A pointer to a value of sec_passwd_rec_t. The storage
for keydata is allocated dynamically, so the returned
pointer actually indicates a pointer to the key value.
The storage for this data can be freed with the
sec_key_mgmt_free_key routine.
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns one of the following errors:
sec_key_mgmt_e_not_implemented The specified key
type is not supported.
sec_s_no_key_seed No random key seed has
been set.
sec_s_no_memory Unable to allocate
memory.
Usage
The sec_key_mgmt_gen_rand_key routine generates a new random key for
a specified principal and of a specified key type. The generated key
can be used with the sec_key_mgmt_change_key and sec_key_mgmt_set_key
routines. Note that to initialize the random keyseed, the process
must first make an authenticated call such as sec_rgy_site_open.
Related Information
Routines: rpc_server_register_auth_info
sec_key_mgmt_change_key
sec_key_mgmt_free_key
sec_key_mgmt_set_key This routine deleted per OSF OT #13151
ΓòÉΓòÉΓòÉ 8.6.9. sec_key_mgmt_get_key ΓòÉΓòÉΓòÉ
Purpose
Retrieves a key from local storage.
Library
\lib\dceos2.lib
Format
#include <dce/keymgmt.h>
void sec_key_mgmt_get_key(
sec_key_mgmt_authn_service authn_service,
void *arg,
unsigned_char *principal_name,
unsigned32 key_vno,
void **keydata,
error_status_t *status);
Parameters
Input
authn_service Identifies the authentication protocol using this key.
The possible authentication protocols are as follows:
rpc_c_authn_dce_secret DCE shared-secret key
authentication
rpc_c_authn_dce_public DCE public key
authentication (reserved for
future use).
arg This parameter can specify either the local key file or
an argument to the get_key_fn key acquisition routine
of the rpc_server_register_auth_info routine.
A value of NULL specifies that the default key file
v5srvtab should be used. A key file name specifies that
file should be used as the key file. The file must have
been created with the rgy_edit ktadd command or the
sec_key_mgmt_set_key routine.
Any other value specifies an argument for the
get_key_fn key acquisition routine. See
rpc_server_register_auth_info for more information.
principal_name A pointer to a character string indicating the name of
the principal to whom the key belongs.
key_vno The version number of the desired key. To return the
latest version of the key, set this parameter to
sec_c_key_version_none.
Output
keydata A pointer to a value of type sec_passwd_rec_t. The
storage for keydata is allocated dynamically, so the
returned pointer actually indicates a pointer to the
key value. The storage for this data can be freed with
the sec_key_mgmt_free_key routine.
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns one of the following errors:
sec_key_mgmt_e_key_unavailable The requested key
is not present.
sec_key_mgmt_e_authn_invalid The authentication
protocol is not valid.
sec_key_mgmt_e_unauthorized The caller is not
authorized to perform the
operation.
sec_s_no_memory Unable to allocate
memory.
Usage
The sec_key_mgmt_get_key routine extracts the specified key from the
local key storage.
ΓòÉΓòÉΓòÉ 8.6.10. sec_key_mgmt_get_next_key ΓòÉΓòÉΓòÉ
Purpose
Retrieves successive keys from the local key storage.
Library
\lib\dceos2.lib
Format
#include <dce/keymgmt.h>
void sec_key_mgmt_get_next_key(
void *cursor,
unsigned_char **principal_name,
unsigned32 *key_vno,
void **keydata,
error_status_t *status);
Parameters
Input/Output
cursor A pointer to the current cursor position in the local
key storage. The cursor position is set by means of
sec_key_mgmt_initialize_cursor.
Output
principal_name A pointer to a character string indicating the name of
the principal associated with the extracted key. Free
the storage for the principal name with the free
routine.
key_vno The version number of the extracted key.
keydata A pointer to a value of type sec_passwd_rec_t. The
storage for keydata is allocated dynamically, so the
returned pointer actually indicates a pointer to the
key value. The storage for this data can be freed with
the sec_key_mgmt_free_key routine.
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns one of the following errors:
sec_key_mgmt_e_key _unavailable The requested key
is not present.
sec_key_mgmt_e_unauthorized The caller is not
authorized to perform
the operation.
sec_s_no_memory Unable to allocate
memory.
Usage
The sec_key_mgmt_get_next_key routine extracts the key pointed to by
the cursor in the local key storage and updates the cursor to point
to the next key. By repeatedly calling this routine, you can scan all
the keys in the local key storage.
Related Information
Routines:
sec_key_mgmt_free_key
sec_key_mgmt_get_key
sec_key_mgmt_initialize_cursor
ΓòÉΓòÉΓòÉ 8.6.11. sec_key_mgmt_get_next_kvno ΓòÉΓòÉΓòÉ
Purpose
Retrieves the next eligible key version number for a key.
Format
#include <dce/keymgmt.h>
void sec_key_mgmt_get_next_kvno(
sec_key_mgmt_authn_service authn_service,
void *arg,
unsigned_char *principal_name,
void *keytype,
unsigned32 *key_vno,
unsigned32 *next_key_vno,
error_status_t *status);
Parameters
Input
authn_service Identifies the authentication protocol using this key.
The possible authentication protocols are as follows:
rpc_c_authn_dce_secret DCE shared-secret key
authentication
rpc_c_authn_dce_public DCE public key
authentication (reserved for
future use).
arg This parameter can specify either the local key file or
an argument to the get_key_fn key acquisition routine
of the rpc_server_register_auth_info routine.
A value of NULL specifies that the default key file
v5srvtab should be used. A key file name specifies that
file should be used as the key file. You must prepend
the file's absolute file name with WRFILE: and the file
must have been created with the rgy_edit ktadd command
or the sec_key_mgmt_set_key routine.
Any other value specifies an argument for the
get_key_fn key acquisition routine. See
rpc_server_register_auth_info for more information.
principal_name A pointer to a character string indicating the name of
the principal associated with the key.
keytype A pointer to a value of type sec_passwd_type_t. The
value identifies the data encryption algorithm (for
example, DES) being used for the key.
Output
key_vno The current version number of the key. Specify NULL if
this value does not need to be returned.
next_key_vno The next eligible version number for the key. Specify
NULL if this value does not need to be returned.
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns one of the following errors:
sec_key_mgmt_e_key_unavailable The requested key
is not present.
sec_key_mgmt_e_authn_invalid The authentication
protocol is not valid.
sec_key_mgmt_e_unauthorized The caller is not
authorized to perform the
operation.
sec_rgy_server_unavailable The DCE Registry Server
is unavailable.
sec_rgy_object_not_found No principal was found
with the given name.
Usage
The sec_key_mgmt_get_next_kvno routine returns the current and next
eligible version numbers for a key from the registry server (not from
the local key table). The key is identified by its associated
authentication protocol, principal name, and key type. The keyfile in
which the key is stored is also specified.
Related Information
Routines:
rpc_server_register_auth_info
ΓòÉΓòÉΓòÉ 8.6.12. sec_key_mgmt_get_nth_key ΓòÉΓòÉΓòÉ
Purpose
Extract the specified key from the local key store.
Format
#include <dce/keymgmt.h>
void sec_key_mgmt_get_nth_key (
sec_key_mgmt_authn_service authn_service,
void *arg,
char *principal_name,
signed32 index,
unsigned32 *key_vno,
void **keydata,
error_status_t *status);
Parameters
Input
authn_service Identifies the authentication shema.
arg This parameter can specify either the local key file or
an argument to the get_key_fn key acquisition routine
of the rpc_server_register_auth_info routine.
principal_name The name of the principal whose key is to be read.
index The nth key to extract. Zero (0) indicates the first
key available.
Output
key_vno The key version extracted.
keydata The key value extracted. This data may be released by
calling the sec_key_mgmt_free_key routine.
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns one of the following errors:
sec_key_mgmt_e_key_unavailable The requested key
is not present.
sec_key_mgmt_e_authn_invalid The authentication
protocol is not valid.
sec_key_mgmt_e_unauthorized The caller is not
authorized to perform the
operation.
Note: Any error condition will leave the key state
unchanged.
Usage
Extracts the specified key from the local key store. This operation
can be used to scan all keys belonging to the specified principal and
stored in the local key store. Use of this routine is not
recommended; use sec_key_mgmt_get_next_key along with the initialize
and release cursor functions above. This routine was deficient in
that it made the caller keep track of an index into the key storage,
and did not return a principal name associated with the key.
Related Information
Routines: rpc_server_register_auth_info
Files:
\usr\include\dce\keymgmt.idl - The idl file from which dce\keymgmt.h
was derived.
ΓòÉΓòÉΓòÉ 8.6.13. sec_key_mgmt_initialize_cursor ΓòÉΓòÉΓòÉ
Purpose
Repositions the cursor in the local key storage.
Library
\lib\dceos2.lib
Format
#include <dce/keymgmt.h>
void sec_key_mgmt_initialize_cursor(
sec_key_mgmt_authn_service authn_service,
void *arg,
unsigned_char *principal_name,
void *keytype,
void **cursor,
error_status_t *status);
Parameters
Input
authn_service Identifies the authentication protocol using this key.
The possible authentication protocols are as follows:
rpc_c_authn_dce_secret DCE shared-secret key
authentication
rpc_c_authn_dce_public DCE public key
authentication (reserved for
future use).
arg This parameter can specify either the local key file or
an argument to the get_key_fn key acquisition routine
of the rpc_server_register_auth_info routine.
A value of NULL specifies that the default key file
v5srvtab should be used. A key file name specifies that
file should be used as the key file. You must prepend
the file's absolute file name with WRFILE: and the file
must have been created with the rgy_edit ktadd command
or the sec_key_mgmt_set_key routine.
Any other value specifies an argument for the
get_key_fn key acquisition routine. See the
rpc_server_register_auth_info for more information.
principal_name A pointer to a character string indicating the name of
the principal whose key is to be accessed. To access
all keys in the local key storage, supply NULL for this
parameter.
keytype A pointer to the data encryption algorithm (for
example, DES) being used for the key.
Output
cursor The returned cursor value. The storage for the cursor
information is allocated dynamically, so the returned
pointer actually indicates a pointer to the cursor
value. The storage for this data can be freed with the
sec_key_mgmt_release_cursor routine.
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns one of the following errors:
sec_key_mgmt_e_authn_invalid The authentication
protocol is not valid.
sec_key_mgmt_e_unauthorized The caller is not
authorized to perform the
operation.
sec_s_no_memory Unable to allocate memory.
Usage
The sec_key_mgmt_initialize_cursor routine resets the cursor in the
local key storage.
Use this routine to reposition the cursor before performing a scan of
the local storage by means of sec_key_mgmt_get_next_key. The returned
cursor value is supplied as input to sec_key_mgmt_get_next_key.
Related Information
Routines:
rpc_server_register_auth_info
sec_key_mgmt_get_next_key
sec_key_mgmt_release_cursor
ΓòÉΓòÉΓòÉ 8.6.14. sec_key_mgmt_manage_key ΓòÉΓòÉΓòÉ
Purpose
Automatically changes a principal's key before it expires.
Library
\lib\dceos2.lib
Format
#include <dce/keymgmt.h>
void sec_key_mgmt_manage_key(
sec_key_mgmt_authn_service authn_service,
void *arg,
unsigned_char *principal_name,
error_status_t *status);
Parameters
Input
authn_service Identifies the authentication protocol using this key.
The possible authentication protocols are as follows:
rpc_c_authn_dce_secret DCE shared-secret key
authentication
rpc_c_authn_dce_public DCE public key
authentication (reserved for
future use).
arg This parameter can specify either the local key file or
an argument to the get_key_fn key acquisition routine
of the rpc_server_register_auth_info routine.
A value of NULL specifies that the default key file
v5srvtab should be used. A key file name specifies that
file should be used as the key file. You must prepend
the file's absolute file name with WRFILE: and the file
must have been created with the rgy_edit ktadd command
or the sec_key_mgmt_set_key routine.
Any other value specifies an argument for the
get_key_fn key acquisition routine. See
rpc_server_register_auth_info for more information.
principal_name A pointer to a character string indicating the name of
the principal whose key is to be managed.
Output
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns one of the following errors:
sec_key_mgmt_e_key_unavailable The old key is not
present and cannot be used
to set a client side
authentication context.
sec_key_mgmt_e_authn_invalid The authentication
protocol is not valid.
sec_key_mgmt_e_unauthorized The caller is not
authorized to perform the
operation.
sec_key_mgmt_e_key_unsupported The key type is not
supported.
sec_rgy_server_unavailable The DCE Registry Server
is unavailable.
sec_rgy_object_not_found No principal was found
with the given name.
Usage
The sec_key_mgmt_manage_key routine changes the specified principal's
key on a regular basis, as determined by the local cell's policy. It
runs indefinitely and never returns during normal operation. It
should be called only from a thread that has been devoted to managing
keys.
This routine queries the DCE Registry to determine the password
expiration policy that applies to the named principal. It then idles
until a short time before the current key is due to expire and uses
the sec_key_mgmt_gen_rand_key to produce a new random key. It updates
both the local key storage and the DCE Registry. This routine also
calls sec_key_mgmt_garbage_collect as needed.
Related Information
Routines: sec_key_mgmt_gen_rand_key
sec_key_mgmt_garbage_collect
ΓòÉΓòÉΓòÉ 8.6.15. sec_key_mgmt_release_cursor ΓòÉΓòÉΓòÉ
Purpose
Releases the memory used by an initialized cursor value.
Library
\lib\dceos2.lib
Format
#include <dce/keymgmt.h>
void sec_key_mgmt_release_cursor(
void **cursor,
error_status_t *status);
Parameters
Input
cursor A pointer to the cursor value for which the storage is
to be released.
Output
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns the following error:
sec_key_mgmt_e_unauthorized The caller is not
authorized to perform
the operation.
Usage
The sec_key_mgmt_release_cursor routine releases any storage
allocated for the indicated cursor value by
sec_key_mgmt_initialize_cursor. The storage for the cursor value
returned by sec_key_mgmt_initialize_cursor is dynamically allocated.
Related Information
Routines:
sec_key_mgmt_initialize_cursor
ΓòÉΓòÉΓòÉ 8.6.16. sec_key_mgmt_set_key ΓòÉΓòÉΓòÉ
Purpose
Inserts a key value into the local storage.
Library
\lib\dceos2.lib
Format
#include <dce/keymgmt.h>
void sec_key_mgmt_set_key(
sec_key_mgmt_authn_service authn_service,
void *arg,
unsigned_char *principal_name,
unsigned32 key_vno,
void *keydata,
error_status_t *status);
Parameters
Input
authn_service Identifies the authentication protocol using this key.
The possible authentication protocols are as follows:
rpc_c_authn_dce_secret DCE shared-secret key
authentication
rpc_c_authn_dce_public DCE public key
authentication (reserved for
future use).
arg Specifies either the local key file or an argument to
the get_key_fn key acquisition routine of the
rpc_server_register_auth_info routine.
A value of NULL specifies that the default key file
v5srvtab should be used. A key file name specifies that
file should be used as the key file. The file name must
begin with WRFILE:. If the file name does not begin
with WRFILE:, the code adds it.
Any other value specifies an argument for the
get_key_fn key acquisition routine. See
rpc_server_register_auth_info for more information.
principal_name A pointer to a character string indicating the name of
the principal associated with the key to be set.
key_vno The version number of the key to be set.
keydata A pointer to the key value to be set.
Output
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns one of the following errors:
sec_key_mgmt_e_key_unavailable The old key is not
present and cannot be
used to set a client
side authentication
context.
sec_key_mgmt_e_authn_invalid The authentication
protocol is not valid.
sec_key_mgmt_e_unauthorized The caller is not
authorized to perform
the operation.
sec_key_mgmt_e_key_unsupported The key type is not
supported.
sec_key_mgmt_e_key_version_ex A key with this
version number already
exists.
Usage
The sec_key_mgmt_set_key routine performs all local activities
necessary to update a principal's key to the specified value. This
routine will not update the authentication protocol's value for the
principal's key.
Related Information
Routines: rpc_server_register_auth_info
sec_key_mgmt_change_key
sec_key_mgmt_gen_rand_key
ΓòÉΓòÉΓòÉ 8.7. DCE Login API ΓòÉΓòÉΓòÉ
The Login API communicates with the Security Server to establish, and possibly
change, a principal's login context. A login context contains the information
necessary for a principal to qualify for (although not necessarily be granted)
access to network services.
This section contains information on the data types, constants, and sec_login
routines that comprise the login part of the Security Service.
Login Data Types
Login Constants
Login Routines
ΓòÉΓòÉΓòÉ 8.7.1. Login Data Types ΓòÉΓòÉΓòÉ
The following data types are used in sec_login routines:
sec_login_handle_t This is an opaque pointer to a data structure representing
a complete login context. The context includes a principal's
network credentials, as well as other account information. The
network credentials are also referred to as the principal's
ticket-granting ticket.
sec_login_flags_t A 32-bit set of flags describing restrictions on the use of
a principal's validated network credentials. Currently, only one
flag is implemented, and the set can take on the following two
values:
sec_login_no_flags No special flags are set.
sec_login_credentials_private Restricts the validated
network credentials to the current process. If
this flag is not set, it is permissible to
share credentials with descendents of the
current process.
sec_login_auth_src_t An enumerated set describing how the login context was
authorized. The possible values are:
sec_login_auth_src_network Authentication is accomplished
through the normal network authority. A login
context authenticated this way has all the
network credentials it should have.
sec_login_auth_src_local Authentication is accomplished
using local data. Authentication occurs locally
if a principal's account is tailored for the
local machine, or if the network authority is
unavailable. Because login contexts
authenticated locally have no network
credentials, they cannot be used for network
operations.
sec_login_auth_src_overridden Authentication is accomplished
using the override facility.
sec_login_passwd_t The sec_login_get_pwent routine returns a pointer to a
password structure that depends on the underlying registry
structure. In most cases, the structure is similar to the one
supported by Berkeley 4.4 and OSF/1:
struct passwd {
char *pw_name; /* user name */
char *pw_passwd; /* encrypted password */
int pw_uid; /* user uid */
int pw_gid; /* user gid */
time_t pw_change; /* password change time */
char *pw_class; /* user access class */
char *pw_gecos; /* Honeywell login info */
char *pw_dir; /* home directory */
char *pw_shell; /* default shell */
time_t pw_expire; /* account expiration */
};
sec_passwd_rec_t A structure containing either a plain text password or a
pre-encrypted buffer of password data. The sec_passwd_rec_t
structure consists of three components:
version_number The version number of the password.
pepper A character string combined with the
password before an encryption key is
derived from the password.
key A structure consisting of the following
components:
key_type The key type can be the
following:
sec_passwd_plain
Indicates
that a
printable
string of
data is
stored in
plain.
sec_passwd_des
Indicates
that an
array of
data is
stored in
des_key.
tagged_union A structure specifying
the password. The value
of the structure depends
on key_type. If key_type
is sec_passwd_plain, the
structure contains plain,
a character string. If
key_type is
sec_passwd_des, the
structure contains
des_key, a DES key of
type
sec_passwd_des_key_t.
ΓòÉΓòÉΓòÉ 8.7.2. Login Constants ΓòÉΓòÉΓòÉ
The following constants are used in sec_login routines:
sec_login_default_handle The value of a login context handle before setup
or validation.
sec_login_remote_uid Used in the sec_login_passwd_t structure for
users from remote cells.
sec_login_remote_gid Used in the sec_login_passwd_t structure for
groups from remote cells.
The next two constants are for use with the sec_login_flags_t type:
sec_login_no_flags No special flags are set.
sec_login_credentials_private Restrict the validated network credentials to
the current process. If this flag is not set, it
is permissible to share credentials with
descendents of current process.
ΓòÉΓòÉΓòÉ 8.7.3. Login Routines ΓòÉΓòÉΓòÉ
sec_login_become_delegate
sec_login_become_impersonator
sec_login_become_initiator
sec_login_certify_identity
sec_login_cred_get_delegate
sec_login_cred_get_initiator
sec_login_cred_init_cursor
sec_login_disable_delegation
sec_login_export_context
sec_login_free_net_info
sec_login_get_current_context
sec_login_get_expiration
sec_login_get_pwent
sec_login_import_context
sec_login_init_first
sec_login_inq_pag
sec_login_inquire_net_info
sec_login_newgroups
sec_login_purge_context
sec_login_purge_context_exp
sec_login_refresh_identity
sec_login_release_context
sec_login_set_context
sec_login_set_extended_attrs
sec_login_setup_first
sec_login_setup_identity
sec_login_tkt_request_options
sec_login_valid_and_cert_ident
sec_login_valid_from_keytable
sec_login_validate_cert_auth
sec_login_validate_first
sec_login_validate_identity
ΓòÉΓòÉΓòÉ 8.7.4. sec_login_become_delegate ΓòÉΓòÉΓòÉ
Purpose
Causes an intermediate server to become a delegate in a traced
delegation chain.
Format
#include <dce/sec_login.h>
sec_login_handle_t sec_login_become_delegate(
rpc_authz_cred_handle_t callers_identity,
sec_login_handle_t my_login_context,
sec_id_delegation_type_t delegation_type_permitted,
sec_id_restriction_set_t *delegate_restrictions,
sec_id_restriction_set_t *target_restrictions,
sec_id_opt_req_t *optional_restrictions,
sec_id_opt_req_t *required_restrictions,
sec_id_compatibility_mode_t compatibility_mode,
error_status_t *status);
Parameters
Input
callers_identity A handle of type rpc_authz_cred_handle_t to the
authenticated identity of the previous delegate in the
delegation chain. The handle is supplied by the
rpc_binding_inq_auth_caller routine.
my_login_context A value of sec_login_handle_t that provides an
opaque handle to the identity of the client that is
becoming the intermediate delegate. The
sec_login_handle_t that specifies the client's identity
is supplied as output of the following routines:
o sec_login_get_current_context if the client
inherited the identity of the current context
o The sec_login_setup_identity and
sec_login_validate_identity pair that together
establish an authenticated identity if a new
identity was established Note that this identity
specified by sec_login_handle_t must be a simple login
context; it cannot be a compound identity created by a
previous call to sec_login_become_delegate.
delegation_type_permitted A value of sec_id_delegation_type_t that
specifies the type of delegation to be enabled. The
types available are:
sec_id_deleg_type_none No
delegation
sec_id_deleg_type_traced Traced
delegation
sec_id_deleg_type_impersonation Simple
(impersonation)
delegation
Note that the initiating client sets the type of
delegation. If it is set as traced, all delegates must
also specify traced delegation; they cannot specify
simple delegation. The same is true if the initiating
client sets the delegation type as simple; all
subsequent delegates must also specify simple
delegation. The intermediate delegates can, however,
specify no delegation to indicate that the delegation
chain can proceed no further.
delegate_restrictions A pointer to a sec_id_restriction_set_t that
supplies a list of servers that can act as delegates
for the intermediate client identified by
my_login_context. These servers are added to delegates
permitted by the delegate_restrictions parameter of the
sec_login_become_initiator routine.
target_restrictions A pointer to a sec_id_restriction_set_t that
supplies a list of servers that can act as targets for
the intermediate client identified by my_login_context.
These servers are added to targets specified by the
target_restrictions parameter of the
sec_login_become_initiator routine.
optional_restrictions A pointer to a sec_id_opt_req_t that supplies a
list of application-defined optional restrictions that
apply to the intermediate client identified by
my_login_context. These restrictions are added to the
restrictions identified by the optional_restrictions
parameter of the sec_login_become_initiator routine.
required_restrictions A pointer to a sec_id_opt_req_t that supplies a
list of application-defined required restrictions that
apply to the intermediate client identified by
my_login_context. These restrictions are added to the
restrictions identified by the required_restrictions
parameter of the sec_login_become_initiator routine.
compatibility_mode A value of sec_id_compatibility_mode_t that
specifies the compatibility mode to be used when the
intermediate client operates on pre-1.1 servers. The
modes available are:
sec_id_compat_mode_none Compatibility mode is off.
sec_id_compat_mode_initiator Compatibility mode is
on. The pre-1.1 PAC data is
extracted from the EPAC of the
initiating client.
sec_id_compat_mode_caller Compatibility mode is
on. The pre-1.1 PAC data extracted
from the EPAC of the last client in
the delegation chain.
Output
status A pointer to the completion status. On successful
completion, status is assigned error_status_ok.
Otherwise, it returns one of the following errors:
sec_login_s_context_invalid
sec_login_s_compound_delegate
sec_login_s_invalid_deleg_type
err_sec_login_invalid_delegate_restriction
err_sec_login_invalid_target_restriction
err_sec_login_invalid_opt_restriction
err_sec_login_invalid_req_restriction
sec_login_s_invalid_compat_mode
sec_login_s_deleg_not_enabled
Usage
The sec_login_become_delegate routine is used by intermediate servers
to become a delegate for the client identified by callers_identity.
The routine returns a new login context (of type sec_login_handle_t)
that carries delegation information. This information includes the
delegation type, delegate and target restrictions, and any
application-defined optional and required restrictions.
The new login context created by this routine can then be used to set
up an authenticated RPC with an intermediate or target server using
the rpc_binding_set_auth_info routine.
Any delegate, target, required, or optional restrictions specified in
this routine are added to the restrictions specified by the
initiating client and any intermediate clients.
The sec_login_become_delegate routine is run only if the initiating
client enabled traced delegation by setting the
delegation_type_permitted parameter in the sec_login_become_initiator
routine to sec_id_deleg_type_traced.
Notes
The DCE runtime library caches data structures from rpc activity and
authentication activity, in order to improve performance on repeated
RPC calls to the same server. This information is generally kept for
up to 10 minutes after the last call before it is freed. Under
certain circumstances, this caching can result in increased memory
usage.
If a client does repeated calls to the sec_login_become_delegate
routine with different delegations each time, new data structures are
created and cached for each new delegation. Clients or intermediate
servers that make many repeated calls like this will show memory
growth proportional to the number of new delegations created in a 10
minute interval. This memory is eventually reused for new
delegations, but the steady state process size can be large in very
active scenarios.
Related Information
Routines:
sec_login_become_initiator
sec_login_become_impersonator
rpc_binding_inq_auth_caller
rpc_binding_set_auth_info
sec_login_get_current_context
sec_login_setup_identity
sec_login_validate_identity
Files:
/usr/include/dce/sec_login.idl - The idl file from which
dce/sec_login.h was derived.
ΓòÉΓòÉΓòÉ 8.7.5. sec_login_become_impersonator ΓòÉΓòÉΓòÉ
Purpose
Causes an intermediate server to become a delegate in a simple
delegation chain.
Format
#include <dce/sec_login.h>
sec_login_handle_t sec_login_become_impersonator(
rpc_authz_cred_handle_t callers_identity,
sec_login_handle_t my_login_context,
sec_id_delegation_type_t delegation_type_permitted,
sec_id_restriction_set_t *delegate_restrictions,
sec_id_restriction_set_t *target_restrictions,
sec_id_opt_req_t *optional_restrictions,
sec_id_opt_req_t *required_restrictions,
error_status_t *status);
Parameters
Input
callers_identity A handle of type rpc_authz_cred_handle_t to the
authenticated identity of the previous delegate in the
delegation chain. The handle is supplied by the
rpc_binding_inq_auth_caller routine.
delegation_type_permitted A value of sec_id_delegation_type_t type
that specifies the type of delegation to be enabled.
The types available are:
sec_id_deleg_type_none No delegation
sec_id_deleg_type_traced Traced
delegation
sec_id_deleg_type_impersonation Simple
(impersonation)
delegation The
initiating client sets the type of delegation. If it is
set as traced, all delegates must also specify traced
delegation; they cannot specify simple delegation. The
same is true if the initiating client sets the
delegation type as simple; all subsequent delegates
must also specify simple delegation. The intermediate
delegates can, however, specify no delegation to
indicate that the delegation chain can proceed no
further.
delegate_restrictions A pointer to a sec_id_restriction_set_t that
supplies a list of servers that can act as delegates
for the client becoming the delegate. These servers are
added to the delegates permitted by the
delegate_restrictions parameter of the
sec_login_become_initiator routine
target_restrictions A pointer to a sec_id_restriction_set_t that
supplies a list of servers that can act as targets for
the client becoming the delegate. These servers are
added to targets specified by the target_restrictions
parameter of the sec_login_become_initiator routine.
optional_restrictions A pointer to a sec_id_opt_req_t that supplies a
list of application-defined optional restrictions that
apply to the client becoming the delegate. These
restrictions are added to the restrictions identified
by the optional_restrictions parameter of the
sec_login_become_initiator routine.
required_restrictions A pointer to a sec_id_opt_req_t that supplies a
list of application-defined required restrictions that
apply to the client becoming the delegate. These
restrictions are added to the restrictions identified
by the required_restrictions parameter of the
sec_login_become_initiator routine.
Output
status A pointer to the completion status. On successful
completion, status is assigned error_status_ok.
Otherwise, it returns one of the following errors:
sec_login_s_invalid_deleg_type
err_sec_login_invalid_delegate_restriction
err_sec_login_invalid_target_restriction
err_sec_login_invalid_opt_restriction
err_sec_login_invalid_req_restriction
sec_login_s_invalid_compat_mode
sec_login_s_deleg_not_enabled
Usage
The sec_login_become_impersonator routine is used by intermediate
servers to become a delegate for the client identified by
callers_identity. The routine returns a new login context (of type
sec_login_handle_t) that carries delegation information. This
information includes the delegation type, delegate, and target
restrictions, and any application-defined optional and required
restrictions.
The new login context created by this routine can then be used to set
up an authenticated RPC with an intermediate or target server using
the rpc_binding_set_auth_info routine.
The effective optional and required restrictions are the union of the
optional and required restrictions specified in this routine and
specified by the initiating client and any intermediate clients. The
effective target and delegate restrictions are the intersection of
the target and delegate restrictions specified in this routine and
specified by the initiating client and any intermediate clients.
The sec_login_become_impersonator routine is run only if the
initiating client enabled simple delegation by setting the
delegation_type_permitted parameter in the sec_login_become_initiator
routine to sec_id_deleg_type_simple.
Related Information
Routines:
sec_login_become_initiator
rpc_binding_inq_auth_caller
Files:
/usr/include/dce/sec_login.idl - The idl file from which
dce/sec_login.h was derived.
ΓòÉΓòÉΓòÉ 8.7.6. sec_login_become_initiator ΓòÉΓòÉΓòÉ
Purpose
Constructs a new login context that enables delegation for the
calling client.
Format
#include <dce/sec_login.h>
sec_login_handle_t sec_login_become_initiator(
sec_login_handle_t my_login_context,
sec_id_delegation_type_t delegation_type_permitted,
sec_id_restriction_set_t *delegate_restrictions,
sec_id_restriction_set_t *target_restrictions,
sec_id_opt_req_t *optional_restrictions,
sec_id_opt_req_t *required_restrictions,
sec_id_compatibility_mode_t compatibility_mode,
error_status_t *status);
Parameters
Input
my_login_context A value of sec_login_handle_t that provides an
opaque handle to the identity of the client that is
enabling delegation. The sec_login_handle_t that
specifies the client's identity is supplied as output
of the following routines:
o sec_login_get_current_context if the client
inherited the identity of the current context
o The sec_login_setup_identity and the
sec_login_validate_identity pair that together
establish an authenticated identity if a new
identity was established
delegation_type_permitted A value of sec_id_delegation_type_t that
specifies the type of delegation to be enabled. The
types available are:
sec_id_deleg_type_none No delegation
sec_id_deleg_type_traced Traced
delegation
sec_id_deleg_type_impersonation Simple
(impersonation)
delegation
Note each subsequent intermediate delegate of the
delegation chain started by the initiating client must
set the delegation type to traced if the initiating
client set it to traced or to simple if the initiating
client set it to simple. Intermediate delegates,
however, can set the delegation type to no delegation
to indicate that the delegation chain can proceed no
further.
delegate_restrictions A pointer to a sec_id_restriction_set_t that
supplies a list of servers that can act as delegates
for the client initiating delegation.
target_restrictions A pointer to a sec_id_restriction_set_t that
supplies a list of servers that can act as targets for
the client initiating delegation.
optional_restrictions A pointer to a sec_id_opt_req_t that supplies a
list of application-defined optional restrictions that
apply to the client initiating delegation.
required_restrictions A pointer to a sec_id_opt_req_t that supplies a
list of application-defined required restrictions that
apply to the client initiating delegation.
compatibility_mode A value of sec_id_compatibility_mode_t that
specifies the compatibility mode to be used when the
initiating client interacts with pre-1.1 servers. The
modes available are:
sec_id_compat_mode_none Compatibility mode is off.
sec_id_compat_mode_initiator Compatibility mode is
on. The pre-1.1 PAC data is
extracted from the EPAC of the
initiating client.
sec_id_compat_mode_caller Compatibility mode is
on. The pre-1.1 PAC data extracted
from the EPAC of the last client in
the delegation chain.
Output
status A pointer to the completion status. On successful
completion, status is assigned error_status_ok.
Otherwise, it returns one of the following errors:
sec_login_s_context_invalid
sec_login_s_invalid_deleg_type
err_sec_login_invalid_delegate_restriction
err_sec_login_invalid_target_restriction
err_sec_login_invalid_opt_restriction
err_sec_login_invalid_req_restriction
sec_login_s_invalid_compat_mode
Usage
The sec_login_become_initiator enables delegation for the calling
client by constructing a new login context (in a sec_login_handle_t)
that carries delegation information. This information includes the
delegation type, delegate, and target restrictions, and any
application-defined optional and required restrictions.
The new login context is then used to set up an authenticated RPC
with an intermediate server using the rpc_binding_set_auth_info
routine. The intermediary can continue the delegation chain by
calling sec_login_become_delegate (if the delegation type is
sec_id_deleg_type_traced) or sec_login_become_impersonator (if the
delegation type is sec_id_deleg_type_impersonation).
Related Information
Routines:
sec_login_become_delegate
sec_login_become_impersonator
sec_login_get_current_context
sec_login_setup_identity
sec_login_validate_identity Files:
/usr/include/dce/sec_login.idl - The idl file from which
dce/sec_login.h was derived.
ΓòÉΓòÉΓòÉ 8.7.7. sec_login_certify_identity ΓòÉΓòÉΓòÉ
Purpose
Certifies the network authentication service.
Library
\lib\dceos2.lib
Format
#include <dce/sec_login.h>
boolean32 sec_login_certify_identity(
sec_login_handle_t login_context,
error_status_t *status);
Parameters
Input
login_context An opaque handle to login context data. The login
context contains, among other data, the account
principal name and UUID, account restrictions, records
of group membership, and the process home directory.
Output
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns one of the following errors:
sec_login_s_config The DCE configuration
(dce_config) information is
not available.
sec_login_s_context_invalid The input context is
not valid.
sec_login_s_default_use It is an error to try to
certify the default context.
Usage
The sec_login_certify_identity routine certifies that the security
server used to set up and validate a login context is legitimate. A
legitimate server is one that knows the host machine's secret key. On
some systems, this can be a privileged operation.
Information can be retrieved by means of sec_login_get_pwent and
sec_login_get_expiration from an uncertified login context, but such
information cannot be trusted. All system login programs that use the
sec_login interface must call sec_login_certify_identity to certify
the security server. If they do not, they open the local file system
to attacks by imposter security servers returning suspect local
process credentials (UID and group IDs).
Return Codes
The routine returns a boolean32 value that is TRUE if the
certification was successful, and FALSE otherwise.
Examples
Applications wanting to perform a straightforward login can use the
sec_login package as follows:
if (sec_login_setup_identity(user_name, sec_login_no_flags, &login_context, &st))
{
... get password from user...
if (sec_login_validate_identity(login_context, password, &reset_passwd, &auth_src, &st))
{
if (!sec_login_certify_identity(login_context, &st))
exit(error_weird_auth_svc);
sec_login_set_context(login_context, &st);
if (auth_src != sec_login_auth_src_network)
printf("no network credentials");
if (reset_passwd)
{
... get new password from user, reset registry record ...
};
sec_login_get_pwent(login_context, &pw_entry, &st);
if (pw_entry.pw_expire < todays_date)
{
sec_login_purge_context(&login_context, &st);
exit(0)
}
... any other application specific login valid actions ...
}
} else
{
sec_login_purge_context(&login_context, &st);
... application specific login failure actions ...
}
Related Information
Routines: sec_login_get_pwent
sec_login_get_expiration
sec_login_validate_cert_auth
ΓòÉΓòÉΓòÉ 8.7.8. sec_login_cred_get_delegate ΓòÉΓòÉΓòÉ
Purpose
Returns a handle to the privilege attributes of an intermediary in a
delegation chain. Used by clients.
Format
#include <dce/sec_login.h>
sec_cred_pa_handle_t sec_login_cred_get_delegate(
sec_login_handle_t login_context,
sec_cred_cursor_t *cursor,
error_status_t *status);
Parameters
Input
login_context A value of sec_login_handle_t that provides an opaque
handle to a login context for which delegation has been
enabled. The sec_login_handle_t that specifies the
identity is supplied as output of the
sec_login_become_delegate routine.
Input/Output
cursor As input, a pointer to a cursor of type
sec_cred_cursor_t that has been initialized by the
sec_login_cred_init_cursor routine. As an output
parameter, cursor is a pointer to a cursor of type
sec_cred_cursor_t that is positioned past the principal
whose privilege attributes have been returned in this
routine.
Output
status A pointer to the completion status. On successful
completion, status is assigned error_status_ok.
Otherwise, it returns one of the following errors:
sec_cred_s_invalid_cursor
sec_cred_s_no_more_entries
Usage
The sec_login_cred_get_delegate routine returns a handle of type
sec_login_handle_t to the privilege attributes of an intermediary in
a delegation chain that performed an authenticated RPC operation.
This routine is used by clients. Servers use the
sec_cred_get_delegate routine to return the privilege attribute
handle of an intermediary in a delegation chain.
The login context identified by login_context contains all members in
the delegation chain. This routine returns a handle
(sec_cred_pa_handle_t) to the privilege attributes of one of the
delegates in the login context. The sec_cred_pa_handle_t returned by
this routine is used in other sec_cred_get_xxx routines to obtain
privilege attribute information for a single delegate.
To obtain the privilege attributes of each delegate in the credential
handle identified by callers_identity, run this routine until the
message sec_cred_s_no_more_entries is returned.
Before you run sec_login_cred_get_delegate, you must run a call to
sec_login_cred_init_cursor to initialize a cursor of type
sec_cred_cursor_t.
Use the sec_cred_free_pa_handle and sec_cred_free_cursor routines to
free the resources allocated to the sec_cred_pa_handle_t and cursor.
Related Information
Routines:
sec_login_cred_init_cursor
sec_cred_get_deleg_restrictions
sec_cred_get_delegation_type
sec_cred_get_extended_attrs
sec_cred_get_pa_data
sec_cred_get_opt_restrictions
sec_cred_get_req_restrictions
sec_cred_get_tgt_restrictions
sec_cred_get_v1_pac Files:
/usr/include/dce/sec_login.idl - The idl file from which
dce/sec_login.h was derived.
ΓòÉΓòÉΓòÉ 8.7.9. sec_login_cred_get_initiator ΓòÉΓòÉΓòÉ
Purpose
Returns information about the delegation initiator in a specified
login context.
Format
#include <dce/sec_login.h>
sec_cred_pa_handle_t sec_login_cred_get_initiator(
sec_login_handle_t login_context,
error_status_t *status);
Parameters
Input
login_context A value of sec_login_handle_t that provides an opaque
handle to a login context for which delegation has been
enabled.
Output
status A pointer to the completion status. On successful
completion, status is assigned error_status_ok.
Otherwise, it returns sec_login_s_context_invalid.
Usage
The sec_login_cred_get_initiator routine returns a handle of type
sec_cred_pa_handle_t to the privilege attributes of the delegation
initiator.
The login context identified by login_context contains all members in
the delegation chain. This routine returns a handle
(sec_cred_pa_handle_t) to the privilege attributes of the initiator.
The sec_cred_pa_handle_t returned by this routine is used in other
sec_cred_get_xxx routines to obtain privilege attribute information
for the initiator single delegate.
Use the sec_cred_free_pa_handle routine to free the resources
allocated to the sec_cred_pa_handle_t handle.
Related Information
Routines:
sec_login_cred_init_cursor
sec_cred_get_deleg_restrictions
sec_cred_get_delegation_type
sec_cred_get_extended_attrs
sec_cred_get_pa_data
sec_cred_get_opt_restrictions
sec_cred_get_req_restrictions
sec_cred_get_tgt_restrictions
sec_cred_get_v1_pac
Files:
/usr/include/dce/sec_login.idl - The idl file from which
dce/sec_login.h was derived.
ΓòÉΓòÉΓòÉ 8.7.10. sec_login_cred_init_cursor ΓòÉΓòÉΓòÉ
Purpose
Initializes a sec_cred_cursor_t cursor.
Format
#include <dce/sec_cred.h>
void sec_login_cred_init_cursor (
sec_cred_cursor_t *cursor,
error_status_t *status);
Parameters
Input/Output
cursor As input, a pointer to a sec_cred_cursor_t to be
initialized. As output, a pointer to an initialized
sec_cred_cursor_t.
Output
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns an error.
Usage
The sec_login_cred_init_cursor routine allocates and initializes a
cursor of type sec_cursor_t for use with the
sec_login_cred_get_delegate routine.
Use the sec_cred_free_cursor routine to free the resources allocated
to cursor.
Related Information
Routines:
sec_login_cred_get_delegate
ΓòÉΓòÉΓòÉ 8.7.11. sec_login_disable_delegation ΓòÉΓòÉΓòÉ
Purpose
Disables delegation for a specified login context.
Format
#include <dce/sec_login.h>
sec_logon_handle_t *sec_login_disable_delegation(
sec_login_handle_t login_context,
error_status_t *status);
Parameters
Input
login_context An opaque handle to a login context for which
delegation has been enabled.
Output
status A pointer to the completion status. On successful
completion, status is assigned error_status_ok.
Otherwise, it returns sec_login_s_context_invalid.
Usage
The sec_login_disable_delegation routine disables delegation for a
specified login context. It returns a new login context of type
sec_login_handle_t without any delegation information, which prevents
any further delegation.
Related Information
Routines:
sec_login_become_delegate
sec_login_become_impersonator
sec_login_become_initiator
Files:
/usr/include/dce/sec_login.idl - The idl file from which
dce/sec_login.h was derived.
ΓòÉΓòÉΓòÉ 8.7.12. sec_login_export_context ΓòÉΓòÉΓòÉ
Purpose
Creates an exportable login context.
Library
\lib\dceos2.lib
Format
#include <dce/sec_login.h>
void sec_login_export_context(
sec_login_handle_t login_context,
unsigned32 buf_len,
ndr_byte buf[],
unsigned32 *len_used,
unsigned32 *len_needed,
error_status_t *status);
Parameters
Input
login_context An opaque handle to login context data. The login
context contains, among other data, the account
principal name and UUID, account restrictions, records
of group membership, and the process home directory.
buf_len An unsigned 32-bit integer containing the allocated
length (in bytes) of the buffer to contain the login
context.
Output
buf An idl_byte array that contains the exportable login
context on return.
len_used A pointer to an unsigned 32-bit integer indicating the
number of bytes needed for the entire login context, up
to buf_len.
len_needed If the allocated length of the buffer is too short, an
error is issued (sec_login_s_no_memory), and on return
this pointer indicates the number of bytes necessary to
contain the login context.
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns one of the following errors:
sec_login_s_no_memory Not enough space was
allocated for the buf array.
The len_needed parameter
points to the needed length.
sec_login_s_handle_invalid The login context
handle is not valid.
sec_login_s_context_invalid The login context
specified by the input handle
is not valid.
Usage
The sec_login_export_context routine obtains an exportable version of
the login context information. This information can be passed to
another process running on the same machine.
Related Information
Routines:
sec_login_import_context
ΓòÉΓòÉΓòÉ 8.7.13. sec_login_free_net_info ΓòÉΓòÉΓòÉ
Purpose
Frees storage allocated for a principal's network information.
Library
\lib\dceos2.lib
Format
#include <dce/sec_login.h>
void sec_login_free_net_info(
sec_login_net_info_t *net_info);
Parameters
Input/Output
net_info A pointer to the sec_login_net_info_t structure to be
freed.
Usage
The sec_login_free_net_info routine frees any memory allocated for a
principal's network information. Network information is returned by a
previous successful call to sec_login_inquire_net_info.
Cautions
This routine does not return any completion codes. Ensure that you
supply a valid sec_login_net_info_t address. The routine frees a
range of storage beginning at the supplied address, without regard to
the actual contents of the storage.
Related Information
Routines:
sec_login_inquire_net_info
ΓòÉΓòÉΓòÉ 8.7.14. sec_login_get_current_context ΓòÉΓòÉΓòÉ
Purpose
Returns a handle to the current login context.
Library
\lib\dceos2.lib
Format
#include <dce/sec_login.h>
void sec_login_get_current_context(
sec_login_handle_t login_context,
error_status_t *status);
Parameters
Input
login_context A pointer to an opaque handle to login context data.
The login context contains, among other data, the
account principal name and UUID, account restrictions,
records of group membership, and the process home
directory.
Output
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns sec_login_s_no_current_context,
which indicates that there was no current context to
retrieve. See sec_login_setup_identity for information
about how to set up, validate, and implement a login
context.
Usage
The sec_login_get_current_context routine retrieves a handle to the
login context for the currently established network identity. The
context returned is created from locally cached data so subsequent
data extraction operations can return some NULL values.
Related Information
Routines:
sec_login_setup_identity
ΓòÉΓòÉΓòÉ 8.7.15. sec_login_get_expiration ΓòÉΓòÉΓòÉ
Purpose
Returns the ticket-granting ticket (TGT) lifetime for an
authenticated identity.
Library
\lib\dceos2.lib
Format
#include <dce/sec_login.h>
void sec_login_get_expiration(
sec_login_handle_t login_context,
signed32 *identity_expiration,
error_status_t *status);
Parameters
Input
login_context An opaque handle to login context data. The login
context contains, among other data, the account
principal name and UUID, account restrictions, records
of group membership, and the process home directory.
Output
identity_expiration The lifetime of the TGT that belongs to the
authenticated identity identified by login_context. It
can be used in the same way UNIX time_t is used.
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns one of the following errors:
sec_login_s_context_invalid The login context
itself is not valid.
sec_login_s_default_use Unpermitted use of the
default login handle
occurred.
sec_login_s_not_certified Indicates that the login
context has been
validated, but not
certified. Although this
code indicates successful
completion, it warns you
that the context is not
validated.
sec_login_s_no_current_context The calling process
has no context of its own.
Usage
The sec_login_get_expiration routine extracts the lifetime for the
TGT that belongs to the authenticated identity contained in the login
context. The lifetime value is filled in if available, otherwise it
is set to 0 (zero). This routine allows an application to tell an
interactive user how long the user's network login (and authenticated
identity) will last before it must be refreshed.
The routine works only on previously validated contexts.
Examples
Because the authenticated network identity for an application has a
finite lifetime, there is a risk it will expire during some long
network operation, and prevent the operation from completing. To
avoid this situation, an application can, before initiating a long
operation, use the sec_login package to check the expiration time of
its identity. The application can refresh it if there is not enough
time remaining to complete the operation. After refreshing the
identity, the process must validate it again with
sec_login_validate_identity.
sec_login_get_expiration(login_context, &expire_time, &st);
if (expire_time < (current_time + operation_duration)) {
if (!sec_login_refresh_identity(login_context, &st)) {
if (st == sec_login_s_refresh_ident_bad) {
... identity has changed ...
} else {
... login context cannot be renewed ...
exit(error_context_not_renewable);
}
if (sec_login_validate_identity(login_context, password,
&reset_passwd, &auth_src, &st)) {
... identity validated ...
} else {
... validation failed ...
exit(error_validation_failure);
}
}
}
operation();
Related Information
Routines:
sec_login_validate_identity
ΓòÉΓòÉΓòÉ 8.7.16. sec_login_get_pwent ΓòÉΓòÉΓòÉ
Purpose
Returns a passwd-style entry for a login context.
Format
#include <dce/sec_login.h>
void sec_login_get_pwent(
sec_login_handle_t login_context,
sec_login_passwd_t *pwent,
error_status_t *status);
Parameters
Input
login_context An opaque handle to login context data. The login
context contains, among other data, the account
principal name and UUID, account restrictions, records
of group membership, and the process home directory.
Output
pwent A pointer to a pointer to the returned passwd-style
structure. The particular structure depends on the
underlying system. For example, on a system with a
passwd structure similar to the one supported by 4.4BSD
and OSF/1, the structure (found in usr/include/pwd.h
is:
struct passwd {
char *pw_name; /* user name */
char *pw_passwd; /* encrypted password */
int pw_uid; /* user uid */
int pw_gid; /* user gid */
time_t pw_change; /* password change time */
char *pw_class; /* user access class */
char *pw_gecos; /* miscellaneous account info */
char *pw_dir; /* home directory */
char *pw_shell; /* default shell */
time_t pw_expire; /* account expiration */
};
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns one of the following errors:
sec_login_s_context_invalid The login context
itself is not valid.
sec_login_s_default_use Unpermitted use of the
default login handle
occurred.
sec_login_s_info_not_avail The login context has
no UNIX information.
sec_login_s_not_certified Indicates that the login
context has been validated,
but not certified. Although
this code indicates
successful completion, it
warns you that the context is
not validated.
sec_rgy_object_not_found The registry server could
not find the specified login
context data.
sec_rgy_server_e_unavailable The DCE Registry
Server is unavailable.
Usage
The sec_login_get_pwent routine creates a passwd-style file structure
for the current network login context. This is generally useful for
establishing the local operating system context. Applications that
require all of the data normally extracted by means of getpwnam
should extract that data from the login context with this routine.
This routine works only on explicitly created (not inherited or
imported) contexts.
Cautions
The returned sec_login_passwd_t structure points to data stored in
the structure indicated by the login_context pointer and must be
treated as read-only data. Writing to these data objects can cause
unexpected failures.
Examples
The following example illustrates use of the sec_login_get_pwent
routine:
#include <pwd.h>
struct passwd *pwd;
sec_login_get_pwent(login_context, &(sec_login_passwd_t*)pwd, &status);
printf ("%s",pwd->pw_name);
Related Information
Files:
/usr/include/dce/sec_login.idl - The idl file from which
dce/sec_login.h was derived.
ΓòÉΓòÉΓòÉ 8.7.17. sec_login_import_context ΓòÉΓòÉΓòÉ
Purpose
Imports a login context.
Library
\lib\dceos2.lib
Format
#include <dce/sec_login.h>
void sec_login_import_context(
unsigned32 buf_len,
ndr_byte buf[]
sec_login_handle_t *login_context,
error_status_t *status);
Parameters
Input
buf_len The allocated length (in bytes) of the buffer
containing the login context.
buf An idl_byte array containing the importable login
context.
Output
login_context An opaque handle to login context data. The login
context contains, among other data, the account
principal name and UUID, account restrictions, records
of group membership, and the process home directory.
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns one of the following errors:
sec_login_s_context_invalid The login context
itself is not valid.
sec_login_s_default_use Unpermitted use of the
default login handle
occurred.
Usage
The sec_login_import_context routine imports a context obtained by
means of a call to sec_login_export_context performed on the same
machine. To import a login context, users must have the appropriate
privileges. Non-privileged users can import only their own login
context; privileged users can import the login contexts created by
any users.
Related Information
Routines:
sec_login_export_context
ΓòÉΓòÉΓòÉ 8.7.18. sec_login_init_first ΓòÉΓòÉΓòÉ
Purpose
Initializes the default context.
Library
\lib\dceos2.lib
Format
#include <dce/sec_login.h>
void sec_login_init_first(
error_status_t *status);
Parameters
Output
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns one of the following errors:
sec_login_s_default_use The default context is
already initialized.
sec_login_s_privileged An unprivileged process was
called in.
Usage
The sec_login_init_first routine initializes the default context
inheritance mechanism. If the default inheritance mechanism is
already initialized, the operation fails. Typically, this routine is
called by the initial process at machine startup time to initialize
the default context inheritance mechanism for the host machine
process hierarchy.
Related Information
Routines:
sec_login_setup_first
sec_login_validate_first
ΓòÉΓòÉΓòÉ 8.7.19. sec_login_inq_pag ΓòÉΓòÉΓòÉ
Purpose
Obtains the pag from the login context.
Format
#include <dce/sec_login.h>
unsigned32 sec_login_inq_pag(
sec_login_handle_t *login_context,
error_status_t *status);
Parameters
Input
login_context A pointer to the sec_login_handle_t from which the pag
will be extracted.
Output
status A pointer to the completion status. On successful
completion, erro_status_ok is returned.
Usage
The sec_login_inq_pag obtains a pag from the login context.
Related Information
Files:
\usr\include\dce\sec_login.idl - The idl file from which
dce\sec_login.h was derived.
ΓòÉΓòÉΓòÉ 8.7.20. sec_login_inquire_net_info ΓòÉΓòÉΓòÉ
Purpose
Returns a principal's network information.
Library
\lib\dceos2.lib
Format
#include <dce/sec_login.h>
void sec_login_inquire_net_info(
sec_login_handle_t login_context,
sec_login_net_info_t *net_info,
error_status_t *status);
Parameters
Input
login_context An opaque handle to the login context for the desired
principal.
Output
net_info A pointer to the sec_login_net_info_t data structure
that is received from the caller. The data structure is
allocated by the caller and the contents (the
principal's network information) are supplied by this
routine. The sec_login_net_info_t structure is defined
as follows:
typedef struct {
sec_id_pac_t pac;
unsigned32 acct_expiration_date;
unsigned32 passwd_expiration_date;
unsigned32 identity_expiration_date;
} sec_login_net_info_t;
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns one of the following errors:
sec_login_s_context_invalid The login context is
not valid.
sec_login_s_no_current_context The default context
was specified, but does
not exist.
sec_login_s_auth_local The operation is not valid
on the local context. The
caller's identity was not
authenticated.
sec_login_s_not_certified Indicates that the login
context has been
validated, but not
certified. Although this
code indicates successful
completion, it warns you
that the context is not
validated.
Usage
The sec_login_inquire_net_info routine returns network information
for the principal identified by the specified login context. The
network information consists of:
o The privilege attribute certificate (PAC) that describes the
identity and group memberships of the principal.
o The expiration date for the principal's account in the DCE
Registry.
o The expiration date for the principal's password in the DCE
Registry.
o The lifetime for the principal's authenticated network identity.
This is the lifetime of the principal's ticket granting ticket
TGT (see sec_login_get_expiration).
A value of 0 (zero) for an expiration date means there is no
expiration date. In other words, the principal's account, password,
or authenticated identity is good indefinitely.
Notes
To remove the sec_login_net_info_t structure when it is no longer
needed, use sec_login_free_net_info.
Related Information
Routines:
sec_login_get_expiration
sec_login_free_net_info
ΓòÉΓòÉΓòÉ 8.7.21. sec_login_newgroups ΓòÉΓòÉΓòÉ
Purpose
Changes the group list for a login context.
Library
\lib\dceos2.lib
Format
#include <dce/sec_login.h>
boolean32 sec_login_newgroups(
sec_login_handle_t login_context,
sec_login_flags_t flags,
unsigned32 num_local_groups,
sec_id_t local_groups[],
sec_login_handle_t *restricted_context,
error_status_t *status);
Parameters
Input
login_context An opaque handle to login context data. The login
context contains, among other data, the account
principal name and UUID, account restrictions, records
of group membership, and the process home directory.
flags A set of flags of type sec_login_flags_t. These contain
information about how the new network credentials are
used. Currently, the only flag used is
sec_login_credentials_private, which, when set, implies
that the new context is only to be used by the calling
process. If this flag is not set (flags ==
sec_login_no_flags), descendants of the calling process
can also use the new network credentials.
num_local_groups An unsigned 32-bit integer containing the number of
local group identities to include in the new context.
local_groups An array of sec_id_t elements. Each element contains
the UUID of a local group identity to include in the
new context. These identities are local to the cell.
Optionally, each element can also contain a pointer to
a character string containing the name of the local
group.
Output
restricted_context An opaque handle to the login context containing
the changed group list.
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns one of the following errors:
sec_login_s_auth_local The operation is not valid
on the local context.
sec_login_s_default_use It is an error to try to
certify the default context.
sec_login_s_groupset_invalid The input list of
group names is not valid.
There may be groups to which
the caller does not belong,
or the list may contain
groups that do not exist.
Usage
The sec_login_newgroups routine changes the group list for the
specified login context. Part of a network's identity is a list of
the various groups to which a principal belongs. The groups are used
to determine user access to various objects and services. This
routine returns a new login context that contains the changed group
list. To remove the new login context when it is no longer needed,
use sec_login_purge_context.
This operation does not need to be validated, because the user
identity does not change. Consequently, knowledge of the password is
not needed.
Notes
Currently you can have only groups from the local cell.
Return Codes
This routine returns TRUE when the new login context is successfully
established, FALSE if the operation fails.
Related Information
Routines:
sec_login_purge_context
Files:
\include\dce\sec_login.idl - The idl file from which dce\sec_login.h
was derived.
ΓòÉΓòÉΓòÉ 8.7.22. sec_login_purge_context ΓòÉΓòÉΓòÉ
Purpose
Destroys the credentials file relating to a login context and frees
the storage allocated for the login context through a call to
sec_login_release_context.
Library
\lib\dceos2.lib
Format
#include <dce/sec_login.h>
void sec_login_purge_context(
sec_login_handle_t *login_context,
error_status_t *status);
Parameters
Input/Output
login_context A pointer to an opaque handle to login context data.
The login context contains, among other data, the
account principal name and UUID, account restrictions,
records of group membership, and the process home
directory. Note that a pointer to the handle is
submitted, so that the handle can be reset to NULL upon
successful completion.
Output
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns one of the following errors:
sec_login_s_context_invalid The login context
itself is not valid.
sec_login_s_default_use Unpermitted use of the
default login handle
occurred.
Usage
The sec_login_purge_context routine frees any storage allocated for
the specified login context and destroys the associated network
credentials, if any exist.
Notes
Applications must be cautious when purging the current context,
because this destroys network credentials for all processes that
share the credentials. In order to release the storage allocated for
the login context without destroying the credentials file, use the
sec_login_release_context function.
Examples
The following example illustrates use of the sec_login_purge_context
routine as part of a straightforward login process:
if (sec_login_setup_identity(user_name, sec_login_no_flags,
&login_context, &st)) {
... get password from user...
if (sec_login_validate_identity(login_context, password,
&reset_passwd, &auth_src, &st)) {
if (!sec_login_certify_identity(login_context, &st))
exit(error_wierd_auth_svc);
sec_login_set_context(login_context, &st);
if (auth_src != sec_login_auth_src_network)
printf("no network credentials");
if (reset_passwd) {
... get new password from user, reset registry record ...
};
sec_login_get_pwent(login_context, &pw_entry, &st);
if (pw_entry.pw_expire < todays_date) {
sec_login_purge_context(&login_context, &st);
exit(0)
}
... any other application specific login valid actions ...
}
} else {
sec_login_purge_context(&login_context, &st);
... application specific login failure actions ...
}
}
Related Information
Routines:
sec_login_release_context
sec_login_set_context
sec_login_setup_identity
sec_login_validate_identity
sec_login_purge_context_exp
ΓòÉΓòÉΓòÉ 8.7.23. sec_login_purge_context_exp ΓòÉΓòÉΓòÉ
Purpose
Purges expired contexts.
Format
#include <dce/sec_login.h>
void sec_login_purge_context_exp(
unsigned32 buf_len,
ndr_byte buf[],
signed32 purge_time,
error_status_t *status);
Parameters
Input
buf_len The allocated length (in bytes) of the buffer
containing the login context.
buf[] An idl_byte array containing the expired login context.
purge_time Indicates the expiration time. The name ticket is
purged if it expires before the time indicated in
purge_time.
Output
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns one of the following errors:
sec_login_s_context_invalid The login context
itself is not valid.
sec_login_s_default_use Unpermitted use of the
default login handle
occurred.
Usage
The sec_login_purge_context_exp routine frees any storage allocated
for any expired network credentials.
Related Information
Routines:
sec_login_purge_context
Files:
\usr\include\dce\sec_login.idl - The idl file from which
dce\sec_login.h was derived.
ΓòÉΓòÉΓòÉ 8.7.24. sec_login_refresh_identity ΓòÉΓòÉΓòÉ
Purpose
Refreshes an authenticated identity for a login context.
Library
\lib\dceos2.lib
Format
#include <dce/sec_login.h>
boolean32 sec_login_refresh_identity(
sec_login_handle_t login_context,
error_status_t *status);
Parameters
Input
login_context An opaque handle to login context data. The login
context contains, among other data, the account
principal name and UUID, account restrictions, records
of group membership, and the process home directory.
Output
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns one of the following errors:
sec_rgy_object_not_found Principal no longer
exists.
sec_rgy_server_unavailable Network registry not
available.
sec_login_s_auth_local Operation not valid on
local context.
sec_login_s_default_use Unpermitted use of the
default login handle
occurred.
sec_login_s_no_memory Not enough memory is
available to complete the
operation.
Usage
The sec_login_refresh_identity routine refreshes a previously
established identity. It operates on an existing valid context, and
cannot be used to change credentials associated with that identity.
The refreshed identity reflects changes that affect ticket lifetimes,
but not other changes. For example, the identity reflects a change to
maximum ticket lifetime, but does not reflect the addition of the
identity as a member to a group. Only a DCE login reflects all
administrative changes that have been made since the last login.
The refreshed identity must be validated with
sec_login_validate_identity before it can be used.
It is an error to refresh a locally authenticated context.
Notes
The routine returns TRUE even if the context had to be changed. In
this case, the status contains the sec_login_s_refresh_ident_change
warning. This warning indicates that the principal account has
changed since the login context was first established. This means
the refreshed context is different from the input context, and will
need to be validated again with sec_login_validate_identity.
Examples
Because the authenticated network identity for a process has a finite
lifetime, there is a risk it will expire during some long network
operation, and prevent the operation from completing.
If a server application must run with an authenticated network
identity because it is acting as a client of another server, the
sec_login routines can be used to check the network identity
expiration date and run sec_login_refresh_identity and
sec_login_validate_identity before the expiration date. This prevents
interruptions in the server's operation that are the result of
restrictions in the network access applied to an unauthenticated
identity.
sec_login_get_expiration(login_context, &expire_time, &st);
if (expire_time < (current_time + operation_duration)) {
if (!sec_login_refresh_identity(login_context, &st)) {
... login context cannot be renewed ...
... sleep and try again ...
{
} else {
if (sec_login_validate_identity(login_context, password,
&reset_passwd, &auth_src, &st)) {
... identity validated ...
} else {
... validation failed ...
exit(error_validation_failure);
}
}
}
operation();
Related Information
Routines:
sec_login_validate_identity
sec_login_tkt_request_options
ΓòÉΓòÉΓòÉ 8.7.25. sec_login_release_context ΓòÉΓòÉΓòÉ
Purpose
Frees storage allocated for a login context.
Library
\lib\dceos2.lib
Format
#include <dce/sec_login.h>
void sec_login_release_context(
sec_login_handle_t *login_context,
error_status_t *status);
Parameters
Input/Output
login_context A pointer to an opaque handle to login context data.
The login context contains, among other data, the
account principal name and UUID, account restrictions,
records of group membership, and the process home
directory.
Output
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns one of the following errors:
sec_login_s_default_use Unpermitted use of the
default login handle
occurred.
sec_login_s_context_invalid The login context
itself is not valid.
Usage
The sec_login_release_context routine frees any memory allocated for
a login context. Unlike sec_login_purge_context, it does not destroy
the associated network credentials that still reside in the
credential cache.
Related Information
Routines:
sec_login_purge_context
ΓòÉΓòÉΓòÉ 8.7.26. sec_login_set_context ΓòÉΓòÉΓòÉ
Purpose
Creates network credentials for a login context.
Library
\lib\dceos2.lib
Format
#include <dce/sec_login.h>
void sec_login_set_context(
sec_login_handle_t login_context,
error_status_t *status);
Parameters
Input
login_context An opaque handle to login context data. The login
context contains, among other data, the account
principal name and UUID, account restrictions, records
of group membership, and the process home directory.
Output
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns one of the following errors:
sec_login_s_context_invalid The login context
itself is not valid.
sec_login_s_default_use Unpermitted use of the
default login handle
occurred.
sec_login_s_auth_local The operation is not valid
on the local context.
Usage
The sec_login_set_context routine sets the network credentials to
those specified by the login context. This context must have been
previously validated. Contexts acquired through
sec_login_get_current_context or sec_login_newgroups do not need to
be validated, because those routines return previously validated
contexts. You cannot perform this function if the context is marked
sec_login_credentials_private. Such a context can only be used as an
explicit context in user space applications.
Examples
The following example illustrates use of the sec_login_set_context
routine as part of a straightforward login process:
if (sec_login_setup_identity(user_name, sec_login_no_flags, &login_context, &st)) {
... get password from user...
if (sec_login_validate_identity(login_context, password,
&reset_passwd, &auth_src, &st)) {
if (!sec_login_certify_identity(login_context, &st))
exit(error_wierd_auth_svc);
sec_login_set_context(login_context, &st);
if (auth_src != sec_login_auth_src_network)
printf("no network credentials");
if (reset_passwd) {
... get new password from user, reset registry record ...
};
sec_login_get_pwent(login_context, &pw_entry, &st);
if (pw_entry.pw_expire < todays_date) {
sec_login_purge_context(&login_context, &st);
exit(0)
}
... any other application specific login valid actions ....
}
} else {
sec_login_purge_context(&login_context, &st);
... application specific login failure actions ....
}
}
Related Information
Routines:
sec_login_get_current_context
sec_login_newgroups
sec_login_setup_identity
sec_login_validate_identity
ΓòÉΓòÉΓòÉ 8.7.27. sec_login_set_extended_attrs ΓòÉΓòÉΓòÉ
Purpose
Constructs a new login context that contains extended registry
attributes.
Format
#include <dce\sec_login.h>
sec_login_handle_t sec_login_set_extended_attrs(
sec_login_handle_t my_login_context,
unsigned32 num_attributes,
sec_attr_t attributes[],
error_status_t *status);
Parameters
Input
my_login_context A value of sec_login_handle_t that provides an
opaque handle to the identity of the calling client.
num_attributes An unsigned 32-bit integer that specifies the number
of elements in the attributes array. The number must
be greater than 0.
attributes An array of values of type sec_attr_t that specifies
the list of attributes to be set in the new login
context.
Output
status A pointer to the completion status. On successful
completion, status is assigned error_status_ok.
Otherwise, it returns sec_login_s_context_invalid.
Usage
The sec_login_set_extended_attrs routine constructs a login context
that contains extended registry attributes that have been established
for the object identified by my_login_context. The attributes
themselves must have been established and attached to the object
using the Extended Registry Attribute API.
The input attributes array of sec_attr_t values should specify the
attr_id field for each requested attribute. Because the lookup is by
attribute type ID only, set the attribute.attr_value.attr_encoding
field to sec_attr_enc_void for each attribute. Note that sec_attr_t
is an Extended Registry Attribute (ERA) data type. For more
information on ERAs, see DCE Extended Registry Attribute API and the
DCE for OS/2 Warp: Application Development Guide - Core Components.
You cannot use this routine to add extended registry attributes to a
delegation chain. If you pass in a login context that refers to a
delegation chain, an error is returned that indicates the context is
not valid.
The routine returns a new login context of type sec_login_handle_t
that includes the attributes specified in the attributes array.
Related Information
Routines:
sec_login_become_impersonator
sec_login_set_context
sec_login_setup_identity
sec_login_validate_identity
Books:
DCE for OS/2 Warp: Application Development Guide - Core Components
Files:
\usr\include\dce\sec_login.idl - The idl file from which
dce/sec_login.h was derived.
ΓòÉΓòÉΓòÉ 8.7.28. sec_login_setup_first ΓòÉΓòÉΓòÉ
Purpose
Sets up the default network context.
Library
\lib\dceos2.lib
Format
#include <dce\sec_login.h>
boolean32 sec_login_setup_first(
sec_login_handle_t *init_context,
error_status_t *status);
Parameters
Output
init_context A pointer to an opaque handle to login context data.
The login context contains, among other data, the
account principal name and UUID, account restrictions,
records of group membership, and the process home
directory. In this routine, the context is that of the
host machine initial process.
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns one of the following errors:
sec_login_s_default_use The default context is
already in use and does not
need to be set up again.
sec_login_s_no_current_context The calling process
has no context of its own.
sec_login_s_privileged An unprivileged process was
called in.
sec_login_s_config The DCE configuration
(dce_config) information is
not available.
sec_rgy_object_not_found The principal does not
exist.
sec_rgy_server_unavailable The network registry is
not available.
sec_login_s_no_memory Memory allocation has
failed.
Usage
The sec_login_setup_first routine sets up the default context network
identity. If the default context already contains valid credentials,
the routine fails. Typically, this routine is called from the
Security Validation Service of the dced process to enable the default
credentials for the host machine process hierarchy.
This routine uses the DCE host name available from the local
dce_config interface as the principal name for the setup, so it does
not need a principal name as input.
Return Codes
The routine returns a boolean32 value: TRUE if the setup was
successful, and FALSE otherwise.
Related Information
Routines:
sec_login_init_first
sec_login_validate_first
ΓòÉΓòÉΓòÉ 8.7.29. sec_login_setup_identity ΓòÉΓòÉΓòÉ
Purpose
Sets up the user's network identity.
Library
\lib\dceos2.lib
Format
#include <dce\sec_login.h>
boolean32 sec_login_setup_identity(
unsigned_char_p_t principal,
sec_login_flags_t flags,
sec_login_handle_t *login_context,
error_status_t *status);
Parameters
Input
principal A pointer indicating a character string containing the
principal name on the registry account corresponding to
the calling process.
The principal parameter can accept a principal name for
the local registry (for example, sandy), or it can
accept a principal name from another cell (for example,
/.../bigcell.austin.ibm.com/sandy). In the second
example, /.../bigcell.austin.ibm.com/ is the name of
the cell and sandy is the principal name within that
cell.
flags A set of flags of type sec_login_flags_t. These contain
information about how the new network credentials are
to be used.
Output
login_context A pointer to an opaque handle to login context data.
The login context contains, among other data, the
account principal name and UUID, account restrictions,
records of group membership, and the process home
directory.
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns one of the following errors:
sec_rgy_object_not_found The principal does not
exist.
sec_rgy_server_unavailable The network registry is
not available.
sec_login_s_no_memory Not enough memory is
available to complete the
operation.
Usage
The sec_login_setup_identity routine creates any local context
necessary to perform authenticated network operations. It does not
establish any local operating system context; that is the
responsibility of the caller. It is the standard network login
routine. The network identity set up by this operation cannot be used
until it is validated by means of sec_login_validate_identity.
The sec_login_setup_identity operation and the
sec_login_validate_identity operation are two halves of a single
logical operation. Together they collect the identity data needed to
establish an authenticated identity.
When a process is finished using a login context, it can issue a call
to sec_login_release_context to free storage occupied by the context
handle. When a process releases a login context, the context data in
the credentials file is still available to other processes that use
it. If an application needs to destroy a login context, it can call
sec_login_purge_context. The sec_login_purge_context routine destroys
the credentials file relating to the login context in addition to
issuing a call to sec_login_release_context to release the context
handle. Because a destroyed context file is unavailable to all
processes that use it, application developers should be careful when
using sec_login_purge_context to destroy the current context.
Return Codes
The routine returns TRUE if the identity has been successfully
established, and FALSE if the operation fails.
Examples
The following example illustrates use of the sec_login_setup_identity
routine as part of a straightforward login process:
if (sec_login_setup_identity(user_name, sec_login_no_flags, &login_context, &st)) {
... get password from user...
if (sec_login_validate_identity(login_context, password,
&reset_passwd, &auth_src, &st)) {
if (!sec_login_certify_identity(login_context, &st))
exit(error_weird_auth_svc);
sec_login_set_context(login_context, &st);
if (auth_src != sec_login_auth_src_network)
printf("no network credentials");
if (reset_passwd) {
... get new password from user, reset registry record ...
};
sec_login_get_pwent(login_context, &pw_entry, &st);
if (pw_entry.pw_expire < todays_date) {
sec_login_purge_context(&login_context, &st);
exit(0)
}
... any other application specific login valid actions ...
}
} else {
sec_login_purge_context(&login_context, &st);
... application specific login failure actions ...
}
}
Related Information
Routines:
sec_login_purge_context
sec_login_release_context
sec_login_set_context
sec_login_tkt_request_options
sec_login_validate_identity
ΓòÉΓòÉΓòÉ 8.7.30. sec_login_tkt_request_options ΓòÉΓòÉΓòÉ
Purpose
This routine is used by a client to request specific AS ticket
options.
Format
#include <dce\sec_login.h>
void sec_login_tkt_request_options (
sec_login_handle_t login_context,
sec_login_tkt_info_t *tkt_info,
error_status_t *status);
Parameters
Input
login_context A pointer to an opaque handle to login context data.
The login context contains, among other data, the
account principal name and UUID, account restrictions,
records of group membership, and the process home
directory.
tkt_info A structure which specifies the types of ticket options
requested.
Output
status A pointer to the completion status. On successful
completion, error_status_ok is returned.
Usage
This routine is used by a client to request specific AS ticket
options. This optional routine should be called after a call to
sec_login_setup_identity or sec_login_refresh_identity and before a
call to sec_login_validate_identity or
sec_login_valid_and_cert_ident. Input should consist of a login
context handle in the setup or refreshed state, and a structure which
specifies the types of ticket options requested. If the user requests
a renewable or postdated ticket, or a non-default ticket lifetime,
additional data must be provided in the renewable_lifetime,
postdated_dormanttime, and lifetime fields of the
sec_login_tkt_info_t structure, respectively.
Related Information
sec_login_setup_identity
sec_login_refresh_identity
sec_login_validate_identity
sec_login_valid_and_cert_ident
Files:
\usr\include\dce\sec_login.idl - The idl file from which
dce\sec_login.h was derived.
ΓòÉΓòÉΓòÉ 8.7.31. sec_login_valid_and_cert_ident ΓòÉΓòÉΓòÉ
Purpose
Validates and certifies a login context.
Library
\lib\dceos2.lib
Format
#include <dce\sec_login.h>
boolean32 sec_login_valid_and_cert_ident(
sec_login_handle_t login_context,
sec_passwd_rec_t *passwd,
boolean32 *reset_passwd,
sec_login_auth_src_t *auth_src,
error_status_t *status);
Parameters
Input
login_context An opaque handle to login context data. The login
context contains, among other data, the account
principal name and UUID, account restrictions, records
of group membership, and the process home directory.
passwd A password record to be checked against the password in
the principal's registry account. The routine returns
TRUE if the two match. The contents of the passwd
parameter are erased after the routine has finished
processing it.
Output
reset_passwd A pointer to a 32-bit boolean32 value. The routine
returns TRUE if the account password has expired and
must be reset.
auth_src A 32-bit set of flags identifying the source of the
authentication. Upon return after successful
authentication, the flags in auth_src indicate what
authority was used to validate the login context. If
the authentication was accomplished with the network
authority, the sec_login_auth_src_network flag is set,
and the process login context has credentials to use
the network. If the authentication was accomplished
with local data only (either the principal's account is
tailored for the local machine with overrides, or the
network authority is unavailable), the
sec_login_auth_src_local flag is set. Login contexts
that are authenticated locally must not be used to
establish network credentials because they have none.
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns one of the following errors:
sec_rgy_passwd_invalid The input string does not
match the account
password.
sec_rgy_server_unavailable The DCE Registry Server
is unavailable.
sec_rgy_s_acct_invalid The account is not valid
or has expired.
sec_login_s_privileged This is a privileged
operation and was called
by an unprivileged
process.
sec_login_s_default_use The input context was the
default context, which
cannot be validated.
sec_login_s_already_valid The login context has
already been validated.
sec_login_s_unsupp_passwd_type The password type
is not supported.
sec_login_s_null_password The zero-length password
supplied.
sec_login_s_no_memory Not enough memory is
available to complete the
operation.
sec_login_s_preauth_failed Preauthentication has
failed.
Usage
The sec_login_valid_and_cert_ident routine validates and certifies a
login context established with sec_login_setup_identity. The caller
must supply the user's password as input with the passwd parameter.
This routine combines the operations of the
sec_login_validate_identity and sec_login_certify_identity routines.
It is intended for use by system login programs that need to extract
trustworthy operating system credentials for use in setting the local
identity for a process. This operation destroys the contents of the
passwd input parameter.
If the network security service is unavailable on the host, a locally
authenticated context is created, and the auth_src parameter is set
to sec_login_auth_src_local. Data extracted from a locally
authenticated context can be used to set the local OS identity, but
it cannot be used to establish network credentials
Return Codes
The routine returns TRUE if the login identity has been successfully
validated, and FALSE if the operation fails.
Examples
The following example illustrates use of the
sec_login_valid_and_cert_ident routine as part of a system login
process:
if (sec_login_setup_identity(<user>, sec_login_no_flags, &login_context, &st)) {
... get password ...
if (sec_login_valid_and_cert_ident(login_context,
password, &st)) {
if (auth_src == sec_login_auth_src_network) {
if (GOOD_STATUS(&st)
sec_login_set_context(login_context);
}
}
if (reset_passwd) {
... reset the user's password ...
if (passwd_reset_fails) {
sec_login_purge_context(login_context)
... application login failure actions ...
}
... application specific login valid actions ...
}
}
Related Information
Routines:
sec_login_certify_identity
sec_login_setup_identity
sec_login_validate_identity
sec_login_tkt_request_options
ΓòÉΓòÉΓòÉ 8.7.32. sec_login_valid_from_keytable ΓòÉΓòÉΓòÉ
Purpose
Validates a login context's identity using input from a specified
keytable file.
Format
#include <dce\sec_login.h>
void sec_login_valid_from_keytable(
sec_login_handle_t login_context,
sec_key_mgmt_authn_service authn_service,
void *arg,
unsigned32 try_kvno,
unsigned32 *used_kvno,
boolean32 *reset_passwd,
sec_login_auth_src_t *auth_src,
error_status_t *status);
Parameters
Input
login_context An opaque handle to login context data. The login
context contains, among other data, the account
principal's name and UUID, account restrictions,
records of the account principal's group memberships,
and the account's home directory.
authn_service Identifies the authentication protocol using the key.
The possible authentication protocols are as follows:
rpc_c_authn_dce_secret DCE shared-secret key
authentication.
rpc_c_authn_dce_public DCE public key
authentication (reserved
for future use).
arg This parameter can specify either the local keytab file
or an argument to the get_key_fn key acquisition
routine of the rpc_server_register_auth_info routine.
A value of NULL specifies that the default keytab file
should be used. A keytab file name specifies that the
named file should be used as the keytab file. You must
prepend the file's absolute filename with FILE: and the
file must have been created with the rgy_edit command
or the sec_key_mgmt_set_key routine.
Any other value specifies an argument for the
get_key_fn key acquisition routine. See
rpc_server_register_auth_info for more information.
try_kvno The version number of the key in the keytab file to try
first. Specify NULL to try the current version of the
key.
Output
used_kvno A pointer to a 32-bit boolean32 value that specifies
the version number of the key from the keytab file that
was used to successfully validate the login context, if
any.
reset_passwd A pointer to a 32-bit boolean32 value. The routine
returns TRUE if the account password has expired and
should be reset.
auth_src The way the login context was authorized. The
sec_login_auth_src_t data type distinguishes the
various ways the login context was authorized. There
are three possible values:
sec_login_auth_src_network Authentication is
accomplished using the normal
network authority. A login context
authenticated this way has all the
network credentials it should have.
sec_login_auth_src_local Authentication is
accomplished using local data.
Authentication occurs locally if a
principal's account is tailored for
the local machine, or if the network
authority is unavailable. Because
login contexts authenticated locally
have no network credentials, they
can not be used for network
operations.
sec_login_auth_src_overridden Authentication is
accomplished using the override
facility.
status A pointer to the completion status. On successful
completion, status is assigned error_status_ok.
Otherwise, it returns one of the following errors:
sec_rgy_passwd_invalid The input string does not
match the account password.
sec_rgy_server_unavailable There is no data with
which to compare the input string.
sec_login_s_acct_invalid The account is not valid
or has expired.
sec_login_s_default_use The input context was the
default context, which cannot be
validated.
sec_login_s_already_valid The login context has
already been validated.
sec_login_s_unsupp_passwd_type The password type
is not supported.
sec_key_mgmt_e_key_unavailable The requested key
is not present.
sec_key_mgmt_e_authn_invalid The authentication
protocol is not valid.
sec_key_mgmt_e_unauthorized The caller is not
authorized to perform the operation.
sec_s_no_memory Memory cannot be allocated.
Usage
The sec_login_valid_from_keytable routine validates the login context
established with sec_login_setup_identity. The
sec_login_valid_from_keytable routine obtains the principal's
password from the specified keytable.
If try_kvno specifies a key version number, that version number key
is tried first; otherwise, the current key version number is tried
first. The routine tries all the keys in the keytable until it finds
one that validates the login context. This operation must be run
before the network credentials can be used.
Notes
A context is not secure and must not be set or exported until the
authentication service is authenticated with the
sec_login_certify_identity routine.
Examples
The following example illustrates use of the
sec_login_valid_from_keytable routine as part of a straightforward
login process:
if (sec_login_setup_identity(user_name, sec_login_no_flags, &login_context, &st))
{
... get password from local keytable...
if (sec_login_valid_from_keytable(login_context, authn_service, arg, try_kvno,
&used_kvno, &reset_passwd, &auth_src, &st))
{
sec_login_set_context(login_context, &st);
if (auth_src != sec_login_auth_src_network)
printf("no network credentials");
}
... any other application specific login valid actions ...
}
else
{
sec_login_purge_context(&login_context, &st);
{
... application specific login failure actions ...
}
}
Related Information
Routines:
sec_login_certify_identity
sec_login_setup_identity
sec_login_validate_identity
sec_login_valid_and_cert_ident
Files:
\usr\include\dce\sec_login.idl - The idl file from which
dce/sec_login.h was derived.
ΓòÉΓòÉΓòÉ 8.7.33. sec_login_validate_cert_auth ΓòÉΓòÉΓòÉ
Purpose
Validates certification authority.
Format
#include <dce\sec_login.h>
void sec_login_validate_cert_auth
sec_login_handle_t login_context,
error_status_t *status);
Parameters
Input
login_context A pointer to an opaque handle to login context data.
The login context contains, among other data, the
principal's identity that needs to be validated.
Output
status A pointer to the completion status. On successful
completion, error_status_ok is returned.
Usage
The sec_login_validate_cert_auth routine validates the certification
authority by making sure that the client can make an authenticated
call.
Related Information
Routines:
sec_login_certify_identity
Files:
\usr\include\dce\sec_login.idl - The idl file from which
dce\sec_login.h was derived.
ΓòÉΓòÉΓòÉ 8.7.34. sec_login_validate_first ΓòÉΓòÉΓòÉ
Purpose
Validates the initial login context.
Library
\lib\dceos2.lib
Format
#include <dce\sec_login.h>
boolean32 sec_login_validate_first(
sec_login_handle_t init_context,
boolean32 *reset_passwd,
sec_login_auth_src_t *auth_src,
error_status_t *status);
Parameters
Input
init_context An opaque handle to login context data. The login
context contains, among other data, the account
principal name and UUID, account restrictions, records
of group membership, and the process home directory. In
this routine, the context is the host machine initial
process.
Output
reset_passwd A pointer to a 32-bit boolean value. The routine
returns TRUE if the account password has expired and
must be reset.
auth_src How the login context was authorized. The
sec_login_auth_src_t data type distinguishes the
various ways the login context was authorized. There
are three possible values:
o sec_login_auth_src_network
o sec_login_auth_src_local
o sec_login_auth_src_overridden.
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns one of the following errors:
sec_login_s_privileged An unprivileged process was
called in.
sec_rgy_server_unavailable The network
authentication service was
unavailable.
Usage
The sec_login_validate_first routine validates the default login
context established by the sec_login_setup_first routine. Typically,
this operation is called from the Security Validation Service of the
dced process to validate the default credentials for the host machine
process hierarchy. Because this operation uses the password for the
local host, it does not require a password parameter.
Return Codes
The routine returns a boolean32 value that is TRUE if the setup was
successful and FALSE otherwise.
Related Information
Routines:
sec_login_init_first
sec_login_setup_first
ΓòÉΓòÉΓòÉ 8.7.35. sec_login_validate_identity ΓòÉΓòÉΓòÉ
Purpose
Validates a login context's identity.
Library
\lib\dceos2.lib
Format
#include <dce\sec_login.h>
boolean32 sec_login_validate_identity(
sec_login_handle_t login_context,
sec_passwd_rec_t *passwd,
boolean32 *reset_passwd,
sec_login_auth_src_t *auth_src,
error_status_t *status);
Parameters
Input
login_context An opaque handle to login context data. The login
context contains, among other data, the account
principal name and UUID, account restrictions, records
of group membership, and the process home directory.
passwd A password record to be checked against the password in
the principal's registry account. The routine returns
TRUE if the two match. The contents of the passwd
parameter are erased after the routine has finished
processing it.
Output
reset_passwd A pointer to a 32-bit boolean32 value. The routine
returns TRUE if the account password has expired and
must be reset.
auth_src The way the login context was authorized. The
sec_login_auth_src_t data type distinguishes the
various ways the login context was authorized. There
are three possible values:
o sec_login_auth_src_network
o sec_login_auth_src_local
o sec_login_auth_src_overridden.
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns one of the following errors:
sec_rgy_passwd_invalid The input string does not
match the account
password.
sec_rgy_server_unavailable There is no data with
which to compare the input
string.
sec_login_s_acct_invalid The account is not valid
or has expired.
sec_login_s_null_password The input string is
NULL.
sec_login_s_default_use Input context was the
default context, which
cannot be validated.
sec_login_s_already_valid The login context has
already been validated.
sec_login_s_unsupp_passwd_type The password type
is not supported.
sec_login_s_no_memory There is not enough memory
to complete the operation.
sec_login_s_preauth_failed Preauthentication had
failed.
Usage
The sec_login_validate_identity routine validates the login context
established with sec_login_setup_identity. This operation must be run
before the network credentials can be used. The caller must supply
the user's password in a sec_passwd_rec_t structure as input with the
passwd parameter. The following example sets up a plain text password
for the passwd parameter:
sec_passwd_str_t tmp_passwd;
passwd.version_number = sec_passwd_c_version_none;
passwd.pepper = NULL;
passwd.key.key_type = sec_passwd_plain;
strncpy ((char *)tmp_passwd, (char *)my_passwd, sec_passwd_str_max_len);
tmp_passwd[sec_passwd_str_max_len] = ' ';
passwd_rev.key.tagged_union.plain = &(tmp_passwd[0]);
When a network identity is set, only state information for network
operations has been established. The local operating system identity
has not been modified. It is the responsibility of the caller to
establish any local operating identity state.
The sec_login_setup_identity operation and the
sec_login_validate_identity operation are two halves of a single
logical operation. Together, they collect the identity data needed
to establish an authenticated identity. The operations are
independent, so the user's password need not be sent across the
network. The identity validation performed by
sec_login_validate_identity is a local operation.
Notes
A context is not secure and must not be set or exported until the
authentication service is authenticated with the
sec_login_certify_identity routine.
System login programs that set local operating system identity using
data extracted from a login context should use
sec_login_valid_and_cert_ident instead of
sec_login_validate_identity. If the Security server and client clocks
are not synchronized to within 2 to 3 minutes of each other, this
routine can return a password validation error.
Return Codes
The routine returns TRUE if the login identity has been successfully
validated.
Examples
The following example illustrates use of the
sec_login_validate_identity routine as part of a straightforward
login process:
if (sec_login_setup_identity(user_name, sec_login_no_flags, &login_context, &st)) {
... get password from user...
if (sec_login_validate_identity(login_context, password,
&reset_passwd, &auth_src, &st)) {
if (!sec_login_certify_identity(login_context, &st))
exit(error_wierd_auth_svc);
sec_login_set_context(login_context, &st);
if (auth_src != sec_login_auth_src_network)
printf("no network credentials");
if (reset_passwd) {
... get new password from user, reset registry record ...
};
sec_login_get_pwent(login_context, &pw_entry, &st);
if (pw_entry.pw_expire < todays_date) {
sec_login_purge_context(&login_context, &st);
exit(0)
}
... any other application specific login valid actions ...
}
} else {
sec_login_purge_context(&login_context, &st);
... application specific login failure actions ...
}
}
Related Information
Routines:
sec_login_certify_identity
sec_login_setup_identity
sec_login_valid_and_cert_ident
sec_login_tkt_request_options
ΓòÉΓòÉΓòÉ 8.8. DCE Password Management API ΓòÉΓòÉΓòÉ
The Password Management facility is intended to reduce the risk of unauthorized
users obtaining user-generated passwords by providing the tools necessary to
develop customized password management servers, and to call them from client
password change programs. This facility enables cell administrators to:
o Enforce constraints on users' password choices that are stricter than
those in the DCE Standard Policy
o Offer, or force, automatic generation of user passwords
See the following topics for more information:
Password Management Data Types
Password Management Routines
Files
ΓòÉΓòÉΓòÉ 8.8.1. Password Management Data Types ΓòÉΓòÉΓòÉ
The following data type is used in the Password Management API routines:
sec_passwd_mgmt_handle_t A pointer to an opaque handle consisting of password
management information about a principal. It is returned by
sec_pwd_mgmt_setup.
ΓòÉΓòÉΓòÉ 8.8.2. Password Management Routines ΓòÉΓòÉΓòÉ
The Password Management facility includes the following routines:
o The DCE Password Management interface, sec_pwd_mgmt..., which enables
clients to retrieve a principal's password management ERA values and to
request strength-checking and generation of passwords.
o The DCE Password Management network interface, rsec_pwd_mgmt..., which
enables a password management server to accept and process password
strength-checking and generation requests.
The following is a list of the Password Management routines:
rsec_pwd_mgmt_gen_pwd
rsec_pwd_mgmt_str_chk
rsec_pwd_propagate
sec_pwd_mgmt_free_handle
sec_pwd_mgmt_gen_pwd
sec_pwd_mgmt_get_val_type
sec_pwd_mgmt_setup
ΓòÉΓòÉΓòÉ 8.8.3. Files ΓòÉΓòÉΓòÉ
/usr/include/dce/sec_pwd_mgmt.idl - The idl file from which sec_pwd_mgmt.h was
derived.
ΓòÉΓòÉΓòÉ 8.8.4. rsec_pwd_mgmt_gen_pwd ΓòÉΓòÉΓòÉ
Purpose
Generates a set of passwords.
Format
#include <dce/rsec_pwd_mgmt.h>
void rsec_pwd_mgmt_gen_pwd(
handle_t pwd_mgmt_svr_h,
sec_rgy_name_t princ_name,
unsigned32 plcy_args,
sec_attr_t plcy[],
sec_bytes_t gen_info_in,
unsigned32 num_pwds,
unsigned32 *num_returned,
sec_passwd_rec_t gen_pwd_set[],
sec_bytes_t *gen_info_out,
error_status_t *status)
Parameters
Input
pwd_mgmt_svr_h An RPC binding handle to the password management
server exporting this operation.
princ_name The name of the principal requesting the generated
passwords.
plcy_args The size of the plcy array.
plcy[] An array of extended registry attributes, each
specifying a password management policy. The contents
of this array are as follows:
plcy[0] Effective registry password minimum
length for the principal.
plcy[1] Effective registry password policy
flags for the principal, describing
limitations on password characters.
gen_info_in An NDR pickle containing additional information needed
to generate the passwords. There are currently no
encoding types defined.
num_pwds The number of generated passwords requested.
Output
num_returned The number of generated passwords returned.
gen_pwd_set An array of generated passwords, each stored in a
sec_passwd_rec_t structure.
gen_info_out An NDR pickle containing additional information
returned by the password management server. There are
currently no encoding types defined.
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns one of the following errors:
sec_pwd_mgmt_not_authorized The user is not
authorized to call this API.
sec_pwd_mgmt_svr_error Password Management Server
generic error. Additional
information is usually logged by the
password management server.
Usage
The rsec_pwd_mgmt_gen_pwd routine returns a set of generated
passwords.
Notes
This routine is not intended to be called by application programmers.
The sec_pwd_mgmt API provides all the functions necessary to retrieve
generated passwords. This section is provided for programmers who
want to write their own password management servers.
This network interface is called on the client side using the
sec_pwd_mgmt_gen_pwd operation. Developers are responsible for
implementing the server side of this interface. A sample password
management server called pwd_strengthd is provided as part of DCE.
(The plcy parameter is intended to be expandable to allow
administrators to attach new password policy ERAs to a principal.
This feature is, however, currently unsupported, and the plcy
parameter consists only of the entries described previously.)
Related Information
Routines:
rsec_pwd_mgmt_str_chk
Files:
/usr/include/dce/rsec_pwd_mgmt.idl - The idl file from which
dce/rsec_pwd_mgmt.h was derived.
ΓòÉΓòÉΓòÉ 8.8.5. rsec_pwd_mgmt_str_chk ΓòÉΓòÉΓòÉ
Purpose
Checks the strength of a password.
Format
#include <dce/rsec_pwd_mgmt.h>
boolean32 rsec_pwd_mgmt_str_chk(
handle_t handle,
sec_rgy_name_t princ,
sec_passwd_rec_t *pwd,
signed32 pwd_val_type,
unsigned32 plcy_args,
sec_attr_t plcy[],
sec_bytes_t str_info_in,
sec_bytes_t *str_info_out,
error_status_t *status);
Parameters
Input
handle An RPC binding handle to the password management server
exporting this operation.
princ The name of the principal requesting the generated
passwords.
pwd A pointer to the password to be strength-checked.
pwd_val_type The value of the user's password validation type (as
stored in the pwd_val_type ERA).
plcy_args The size of the plcy array.
plcy[] An array of extended registry attributes, each
specifying a password management policy. The contents
of this array are:
plcy[0] Effective registry password minimum
length for the principal.
plcy[1] Effective registry password policy
flags for the principal, describing
limitations on password characters
str_info_in An NDR pickle containing additional information needed
to strength-check the password. There are currently no
encoding types defined.
Output
str_info_out An NDR pickle containing additional information
returned by the password management server. There are
currently no encoding types defined.
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns one of the following errors:
sec_pwd_mgmt_str_check_failed The password failed
the server's strength checking
algorithm.
sec_pwd_mgmt_not_authorized The user is not
authorized to call this API.
sec_pwd_mgmt_svr_error Password Management Server
generic error. Additional
information is usually logged by the
password management server.
Usage
The rsec_pwd_mgmt_str_chk routine strength-checks a password.
Notes
This routine is not intended to be called by application programmers.
The registry server provides all the functions necessary to
strength-check passwords. This reference page is provided for
programmers who want to write their own password management servers.
This network interface is called on the client side using secd.
Developers are responsible for implementing the server side of this
interface. A sample password management server called pwd_strengthd
is provided as part of DCE.
(The plcy parameter is intended to be expandable to allow
administrators to attach new password policy ERAs to a principal.
This feature is, however, currently unsupported, and the plcy
parameter consists only of the entries previously described.)
Return Codes
The rsec_pwd_mgmt_str_chk routine returns TRUE if the user's password
passes the server's strength-checking algorithm and FALSE if it does
not.
Related Information
Routines:
rsec_pwd_mgmt_gen_pwd
Files:
/usr/include/dce/rsec_pwd_mgmt.idl - The idl file from which
dce/rsec_pwd_mgmt.h was derived.
ΓòÉΓòÉΓòÉ 8.8.6. rsec_pwd_propagate ΓòÉΓòÉΓòÉ
Purpose
Propagates account password changes to foreign registries.
Format
#include <dce/rsec_pwd_prop.h>
void rsec_pwd_propagate(
handle_t h,
sec_rgy_name_t principal,
char *password,
sec_timeval_sec_t pwd_change_time,
error_status_t *status)
Parameters
Input
h An RPC binding handle to the foreign registry
principal The name of the principal
password The password of the principal
pwd_change_time The time the principal name and password information
is sent.
Output
status A pointer to the completion status. On successful
completion, a foreign registry should return
error_status_ok. If a foreign registry is unsuccessful
in processing password receipt, it should return
sec_pwd_mgmt_svr_error.
Usage
The rsec_pwd_propagate routine is used by the IBM DCE for OS/2 Warp
Password Synchronization Server to send account password changes to a
foreign registry. The foreign registry can discard the information,
or it can defer receiving the change event until later. If the
foreign registry incorporates or discards the new information, it
should return a successful status code. If for any reason it cannot
handle the notification at the time, but would like for the password
synchronization server to send the event later, the foreign registry
should return an unsuccessful status.
Foreign registries desiring to be notified when the password for an
account has changed must export this interface. See the section
"Setting Up a Password Synchronization Server" in the DCE for OS/2
Warp:Administration Guide and the Password Management and
Synchronization Application Programming Interfaces for a complete
description of how to configure the Password Synchronization Server,
Foreign Registries, accounts for which password synchronization is
required, and the programming requirements for a foreign registry
exporting this interface.
Related Information
Files:
dce\rsec_pwd_prop.idl - The idl file from which dce\rsec_pwd_prop.h
was derived.
ΓòÉΓòÉΓòÉ 8.8.7. sec_pwd_mgmt_free_handle ΓòÉΓòÉΓòÉ
Purpose
Frees storage allocated for a password management handle.
Format
#include <dce/sec_pwd_mgmt.h>
void sec_pwd_mgmt_free_handle(
sec_pwd_mgmt_handle_t *pwd_mgmt_h,
error_status_t *status);
Parameters
Input/Output
pwd_mgmt_h A handle to the password management data that is to be
freed.
Output
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns an error.
Usage
The sec_pwd_mgmt_free_handle routine frees any memory allocated for
the contents of a password management handle.
Related Information
Routines:
sec_pwd_mgmt_setup
Files:
/usr/include/dce/sec_pwd_mgmt.idl - The idl file from which
dce/sec_pwd_mgmt.h was derived.
ΓòÉΓòÉΓòÉ 8.8.8. sec_pwd_mgmt_gen_pwd ΓòÉΓòÉΓòÉ
Purpose
Generates a set of passwords.
Format
#include <dce/sec_pwd_mgmt.h>
void sec_pwd_mgmt_gen_pwd(
sec_pwd_mgmt_handle_t pwd_mgmt_h,
unsigned32 num_pwds,
unsigned32 *num_returned,
sec_passwd_rec_t gen_pwds[],
error_status_t *status);
Parameters
Input
pwd_mgmt_h A handle to the user's password management data.
num_pwds Number of generated passwords requested.
Output
num_returned Number of generated passwords returned in the gen_pwds
array.
gen_pwds[] Array of generated passwords. Each generated password
is stored in a sec_passwd_rec_t structure.
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns one of the following errors:
sec_rgy_era_pwd_mgmt_auth_type The
pwd_mgmt_binding ERA must contain
authentication information.
sec_pwd_mgmt_svr_unavail The password management
server is unavailable.
sec_pwd_mgmt_svr_error A generic error was
returned from the password
management server. An administrator
should check the password management
server's log file for more
information.
Various RPC communication errors can be returned if
failures occur when binding to the password management
server.
Usage
The sec_pwd_mgmt_gen_pwd routine retrieves a set of generated
passwords from a password management server which is exporting the
rsec_pwd_mgmt_gen_pwd routine. It obtains the binding information to
this server from the pwd_mgmt_h handle. Files:
/usr/include/dce/sec_pwd_mgmt.idl - The idl file from which
dce/sec_pwd_mgmt.h was derived.
Related Information
Routines:
sec_pwd_mgmt_setup
pwd_strengthd
ΓòÉΓòÉΓòÉ 8.8.9. sec_pwd_mgmt_get_val_type ΓòÉΓòÉΓòÉ
Purpose
Gets the user's password validation type.
Format
#include <dce/sec_pwd_mgmt.h>
void sec_pwd_mgmt_get_val_type(
sec_pwd_mgmt_handle_t pwd_mgmt_h,
signed32 *pwd_val_type,
error_status_t *status);
Parameters
Input
pwd_mgmt_h A handle to a user's password management data.
Output
pwd_val_type The user's password validation type. This is retrieved
from the pwd_val_type ERA. The possible values and
their meaning are:
0 (none) The user has no password policy.
1 (user_select) Users must choose their own
passwords.
2 (user_can_select) Users can choose their own
passwords or request a generated
password.
3 (generation_required) The user must use a
generated password.
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns an error.
Various RPC communication errors can be returned if
there are failures when binding to the password
management server.
Usage
The sec_pwd_mgmt_get_val_type routine returns the value of the user's
password validation type, as specified by the pwd_val_type ERA. If
the ERA does not exist, 0 (none) is returned in pwd_val_type.
Files
/usr/include/dce/sec_pwd_mgmt.idl The idl file from which
dce/sec_pwd_mgmt.h was derived.
Related Information
Routines:
sec_pwd_mgmt_setup
ΓòÉΓòÉΓòÉ 8.8.10. sec_pwd_mgmt_setup ΓòÉΓòÉΓòÉ
Purpose
Sets up the user's password policy information.
Format
#include <dce/sec_pwd_mgmt.h>
void sec_pwd_mgmt_setup(
sec_pwd_mgmt_handle_t *pwd_mgmt_h,
sec_rgy_handle_t context,
sec_rgy_login_name_t login_name,
sec_login_handle_t your_lc,
rpc_binding_handle_t pwd_mgmt_bind_h,
error_status_t *status);
Parameters
Input
context A registry server handle indicating the desired
registry site.
login_name The login name of the user.
your_lc The login context handle of the user currently logged
in. If NULL is specified, the default login context is
used.
pwd_mgmt_bind_h An RPC binding handle to the password management
server. Use of this parameter is currently
unsupported. The password management server binding
handle is retrieved from the pwd_mgmt_binding ERA. Set
this parameter to NULL.
Output
pwd_mgmt_h A pointer to an opaque handle to password management or
policy data. The pwd_mgmt_h parameter contains, among
other data, the account name, values of password
management ERAs, and a binding handle to the password
management server.
status A pointer to the completion status. On successful
completion, status is assigned error_status_ok.
Otherwise, it returns one of the following errors:
sec_s_no_memory Not enough memory is available to
complete the operation.
sec_rgy_server_unavailable The network registry is
not available.
Usage
The sec_pwd_mgmt_setup routine collects the data required to perform
remote password management calls to the password management server.
Files
/usr/include/dce/sec_pwd_mgmt.idl The idl file from which
dce/sec_pwd_mgmt.h was derived.
Related Information
Routines:
sec_pwd_mgmt_free_handle
sec_pwd_mgmt_gen_pwd
sec_pwd_mgmt_get_val_type
ΓòÉΓòÉΓòÉ 8.9. Registry API ΓòÉΓòÉΓòÉ
This section contains information on the data types, constants, status codes,
and sec_rgy routines associated with the Registry Application Programming
Interface.
The following is a list of topics and routines in the Registry API:
Registry Data Types
Registry Constants
sec_rgy_acct_add
sec_rgy_acct_admin_replace
sec_rgy_acct_delete
sec_rgy_acct_get_projlist
sec_rgy_acct_lookup
sec_rgy_acct_passwd
sec_rgy_acct_rename
sec_rgy_acct_replace_all
sec_rgy_acct_user_replace
sec_rgy_auth_plcy_get_effective
sec_rgy_auth_plcy_get_info
sec_rgy_auth_plcy_set_info
sec_rgy_cell_bind
sec_rgy_cursor_reset
sec_rgy_enable_nsi
sec_rgy_login_get_effective
sec_rgy_login_get_info
sec_rgy_pgo_add
sec_rgy_pgo_add_member
sec_rgy_pgo_delete
sec_rgy_pgo_delete_member
sec_rgy_pgo_get_by_eff_unix_num
sec_rgy_pgo_get_by_id
sec_rgy_pgo_get_by_name
sec_rgy_pgo_get_by_unix_num
sec_rgy_pgo_get_members
sec_rgy_pgo_get_next
sec_rgy_pgo_id_to_name
sec_rgy_pgo_id_to_unix_num
sec_rgy_pgo_is_member
sec_rgy_pgo_name_to_id
sec_rgy_pgo_name_to_unix_num
sec_rgy_pgo_rename
sec_rgy_pgo_replace
sec_rgy_pgo_unix_num_to_id
sec_rgy_pgo_unix_num_to_name
sec_rgy_plcy_get_effective
sec_rgy_plcy_get_info
sec_rgy_plcy_get_override_info
sec_rgy_plcy_set_info
sec_rgy_plcy_set_override_info
sec_rgy_properties_get_info
sec_rgy_properties_set_info
sec_rgy_rep_admin_become_master
sec_rgy_rep_admin_become_slave
sec_rgy_rep_admin_change_master
sec_rgy_rep_admin_destroy
sec_rgy_rep_admin_get_sw_vers
sec_rgy_rep_admin_info
sec_rgy_rep_admin_info_vers
sec_rgy_rep_admin_init_replica
sec_rgy_rep_admin_maint
sec_rgy_rep_admin_mkey
sec_rgy_rep_admin_set_sw_vers
sec_rgy_rep_admin_stop
sec_rgy_site_bind
sec_rgy_site_bind_query
sec_rgy_site_bind_update
sec_rgy_site_binding_get_info
sec_rgy_site_close
sec_rgy_site_get
sec_rgy_site_is_readonly
sec_rgy_site_open
sec_rgy_site_open_query
sec_rgy_site_open_update
sec_rgy_unix_getgrent
sec_rgy_unix_getgrgid
sec_rgy_unix_getgrnam
sec_rgy_unix_getpwent
sec_rgy_unix_getpwnam
sec_rgy_unix_getpwuid
sec_rgy_wait_until_consistent
ΓòÉΓòÉΓòÉ 8.9.1. Registry Data Types ΓòÉΓòÉΓòÉ
The following data types are used in sec_rgy calls:
sec_rgy_handle_t A pointer to the registry server handle. The registry server
is bound to a handle with sec_rgy_site_open.
sec_rgy_bind_auth_info_type_t An enumeration that defines whether the binding
is authenticated. This data type is used in conjunction with the
sec_rgy_bind_auth_info_t data type to set up the authorization
method and parameters for a binding. The
sec_rgy_bind_auth_info_type_t type consists of:
sec_rgy_bind_auth_none The binding is not authenticated.
sec_rgy_bind_auth_dce The binding uses DCE shared-secret key
authentication.
sec_rgy_bind_auth_info_t A discriminated union that defines authorization and
authentication parameters for a binding. This data type is used in
conjunction with the sec_rgy_bind_auth_info_type_t data type to set
up the authorization method and parameters for a binding. The
sec_rgy_bind_auth_info_t data type consists of:
info_type A sec_rgy_bind_auth_info_type_t data type that
specifies whether the binding is authenticated. The
contents of the union depend on the value of
sec_rgy_bind_auth_info_type_t.
For unauthenticated bindings
(sec_rgy_bind_auth_info_type_t =
sec_rgy_bind_auth_none), no parameters are supplied.
For authenticated bindings
(sec_rgy_bind_auth_info_type_t =
sec_rgy_bind_auth_dce), the dce_info structure is
supplied.
dce_info A structure that consists of:
authn_level An unsigned 32 bit integer
indicating the protection level for
RPC calls made using the server
binding handle. The protection level
determines the degree to which
authenticated communications between
the client and the server are
protected by the authentication
service specified by authn_svc.
If the RPC runtime or the RPC protocol
in the bound protocol sequence does
not support a specified level, the
level is automatically upgraded to the
next higher supported level. The
possible protection levels are:
rpc_c_protect_level_default Uses
the default protection
level for the specified
authentication service.
The default protection
level for DCE
shared-secret key
authentication is
rpc_c_protect_level_pkt_value
rpc_c_protect_level_none Performs
no authentication:
tickets are not
exchanged, session keys
are not established,
client PACs or names
are not certified, and
transmissions are in
the clear. Note that
although uncertified
PACs should not be
trusted, they can be
useful for debugging,
tracing, and
measurement purposes.
rpc_c_protect_level_connect
Authenticates only when
the client establishes
a relationship with the
server.
rpc_c_protect_level_call
Authenticates only at
the beginning of each
remote procedure call
when the server
receives the request.
This level does not
apply to remote
procedure calls made
over a connection-based
protocol sequence (that
is, ncacn_ip_tcp). If
this level is specified
and the binding handle
uses a connection-based
protocol sequence, the
routine uses the
rpc_c_protect_level_pkt
level instead.
rpc_c_protect_level_pkt Ensures
that all data received
is from the expected
client.
rpc_c_protect_level_pkt_integ
Ensures and verifies
that none of the data
transferred between
client and server has
been modified. This is
the highest protection
level that is
guaranteed to be
present in the RPC
runtime.
rpc_c_protect_level_pkt_privacy
Authenticates as
specified by all of the
previous levels and
also encrypts each RPC
argument value. This is
the highest protection
level, but is not
guaranteed to be
present in the RPC
runtime.
authn_svc Specifies the authentication service
to use. The exact level of protection
provided by the authentication service
is specified by protect_level. The
supported authentication services are
as follows:
rpc_c_authn_none No
authentication: no
tickets are exchanged,
no session keys
established, client
PACs or names are not
transmitted, and
transmissions are in
the clear. Specify
rpc_c_authn_none to
turn authentication off
for remote procedure
calls made using this
binding.
rpc_c_authn_dce_secret DCE
shared-secret key
authentication.
rpc_c_authn_default Default
authentication service.
The current default
authentication service
is a DCE shared-secret
key; specifying
rpc_c_authn_default is
equivalent to
specifying
rpc_c_authn_dce_secret.
rpc_c_authn_dce_public DCE public
key authentication
(reserved for future
use).
authz_svc Specifies the authorization service
implemented by the server for the
interface. The validity and
trustworthiness of authorization data,
similar to any application data, is
dependent on the authentication
service and protection level
specified. The supported authorization
services are:
rpc_c_authz_none The server
performs no
authorization. This is
valid only if authn_svc
is set to
rpc_c_authn_none, which
specifies that no
authentication is being
performed.
rpc_c_authz_name The server
performs authorization
based on the client
principal name. This
value cannot be used if
authn_svc is
rpc_c_authn_none.
rpc_c_authz_dce Server performs
authorization using the
client's DCE Privilege
Attribute Certificate
(PAC) sent to the
server with each remote
procedure call made
with this binding.
Generally, access is
checked against DCE
Access Control Lists
(ACLs).
identity A value of type sec_login_handle_t
that represents a complete login
context.
sec_timeval_sec_t A 32-bit integer that contains the seconds portion of a UNIX
sec_timeval_t, to be used when expressing absolute dates.
sec_timeval_t A structure that contains the full UNIX time. The structure
contains two 32-bit integers indicating seconds (sec) and
microseconds (usec) since 0:00, January 1, 1970.
sec_timeval_period_t A 32-bit integer expressing seconds relative to some well
known time.
sec_rgy_acct_key_t Specifies the number of parts (person, group, organization)
of an account login name that are sufficient to specify a unique
abbreviation for that account.
sec_rgy_cursor_t A structure that provides a pointer into a registry database.
This type is used for iterative operations on the registry
information. For example, a call to sec_rgy_pgo_get_members may
return the 10 account names following the input sec_rgy_cursor_t
position. Upon return, the cursor position is updated, so the next
call to that routine returns the next 10 names. The components of
this structure are not used by application programs.
sec_rgy_pname_t A character string of length sec_rgy_pname_t_size.
sec_rgy_name_t A character string of length sec_rgy_name_t_size.
sec_rgy_login_name_t A structure representing an account login name. It
contains three strings of type sec_rgy_name_t:
pname The person name for the account.
gname The group name for the account.
oname The organization name for the account.
sec_rgy_member_t A character string of length sec_rgy_name_t_size.
sec_rgy_foreign_id_t The representation of a foreign ID. This structure
contains two components:
cell A string of type uuid_t representing the UUID of the
foreign cell.
principal A string of type uuid_t representing the UUID of the
principal.
sec_rgy_sid_t A structure identifying an account. It contains three fields:
person The UUID of the person part of the account.
group The UUID of the group part of the account.
org The UUID of the organization part of the account.
sec_rgy_unix_sid_t A structure identifying an account with UNIX ID numbers.
It contains three fields:
person The UNIX ID of the person part of the account.
group The UNIX ID of the group part of the account.
org The UNIX ID of the organization part of the account.
sec_rgy_domain_t This 32-bit integer specifies the naming domain a character
string refers to: person, group, or organization.
sec_rgy_pgo_flags_t A 32-bit bitset that contains flags pertaining to registry
entries. This type contains the following three flags:
sec_rgy_pgo_is_an_alias If set, indicates the registry entry is
an alias of another entry.
sec_rgy_pgo_is_required If set, the registry item is required
and cannot be deleted. An example of a required
account is the one for the registry server itself.
sec_rgy_pgo_projlist_ok If the accompanying item is a person
entry, this flag indicates the person can have
concurrent group sets. If the item is a group entry,
the flag means this group can be part of a concurrent
group set. The flag is undefined for organization
items.
sec_rgy_pgo_item_t The structure identifying a registry item. It contains five
components:
id The UUID of the registry item, in uuid_t form.
unix_num A 32-bit integer that contains the UNIX ID number of
the registry item.
quota A 32-bit integer representing the maximum number of
user-defined registry objects the account owner can
create.
flags A sec_rgy_pgo_flags_t bitset that contains
information about the entry.
fullname A sec_rgy_pname_t character string that contains a
full name for the registry entry. For a person entry,
this field can contain the real name of the account
owner. For a group, it can contain a description of
the group. This is a data-only field, and registry
queries cannot search on the fullname entry.
sec_rgy_acct_admin_flags_t A 32-bit bitset that contains administration flags
used as part of the administrator's information for any registry
account. The set contains three flags:
sec_rgy_acct_admin_valid Specifies that the account is valid
for login.
sec_rgy_acct_admin_server If set, the account's name can be
used as a server name in a TGT.
sec_rgy_acct_admin_client If set, the account's name can be
used as a client name in a TGT. Note that you can
prevent the principal from being authenticated by turning off both
the sec_rgy_acct_admin_server and the sec_rgy_acct_admin_client
flags.
sec_rgy_acct_auth_flags_t A 32-bit bitset that contains account authorization
flags used to implement authentication policy as defined by the
Kerberos version 5 protocol. The set contains six flags:
sec_rgy_acct_auth_post_dated Allows issuance of post-dated
certificates.
sec_rgy_acct_auth_forwardable Allows issuance of forwardable
certificates.
sec_rgy_acct_auth_tgt Allows issuance of certificates based on
TGT authentication. If this flag is not set, a client
requesting a service may have to supply a password
directly to the server.
sec_rgy_acct_auth_renewable Allows issuance of renewable
certificates.
sec_rgy_acct_auth_proxiable Allows issuance of proxiable
certificates.
sec_rgy_acct_auth_dup_session_key Allows issuance of duplicate
session keys.
sec_rgy_acct_admin_t The portion of a registry account item that contains
components relevant to administrators. Note that only
expiration_date, good_since_date, flags, and authentication_flags
can be modified by an administrator ; the remaining fields are set
by the Security server.
creator This field, in foreign_id_t format, identifies the
administrator who created the registry account.
creation_date Specifies the creation date of the account, in
sec_timeval_sec_t format.
last_changer Identifies the last person to change any of the
account information, in foreign_id_t format.
change_date Specifies the date of the last modification of the
account information, in sec_timeval_sec_t format.
expiration_date The date the account expires, in
sec_timeval_sec_t format.
good_since_date The Kerberos version 5 TGT revocation date.
TGTs issued before this date are not honored. In
sec_timeval_sec_t format.
flags Administrative flags in sec_rgy_acct_admin_flags_t
format.
authentication_flags Authentication flags in
sec_rgy_acct_auth_flags_t format.
sec_rgy_acct_user_flags_t A 32-bit bitset that contains flags controlling
user-modifiable information. There is only one flag currently
implemented. If sec_rgy_acct_user_passwd_valid is set, it indicates
the user password is valid. If it is not set, this flag forces the
user to change the password on the next login attempt.
sec_rgy_acct_user_t A structure that contains registry account information.
The structure consists of the fields in the following list. Note
that only the gecos, homedir, shell, and flags can be modified by
the account owner or other authorized users. The remaining fields
are set by the Security server. It contains seven components:
gecos This is a character string (in sec_rgy_pname_t
format) that contains information about the account
user. It generally consists of everything after the
full name in the UNIX gecos format.
homedir The login directory for the account user, in
sec_rgy_pname_t format.
shell The default shell for the account user, in
sec_rgy_pname_t format.
passwd_version_number An unsigned 32-bit integer that indicates
the password version number. This value is used as
output only.
passwd The UNIX encoded account password, in
sec_rgy_unix_passwd_buf_t format. This value is used
as output only.
passwd_dtm The date the password was established, in
sec_timeval_sec_t format.
flags Account user flags, in sec_rgy_acct_user_flags_t
format.
sec_rgy_plcy_pwd_flags_t A 32-bit bitset that contains two flags about
password policy:
sec_rgy_plcy_pwd_no_spaces If set, does not allow spaces in a
password.
sec_rgy_plcy_pwd_non_alpha If set, requires at least one
nonalphanumeric character in the password.
sec_rgy_plcy_t A structure defining aspects of the registry account policy.
It contains five components:
passwd_min_len A 32-bit integer that describes the minimum
number of characters in the account password.
passwd_lifetime The number of seconds from a password's
creation until it expires, in sec_timeval_period_t
format.
passwd_exp_date The expiration date of the account password, in
sec_timeval_sec_t format.
acct_lifespan The number of seconds after the creation of an
account until it expires, in sec_timeval_period_t
format.
passwd_flags Account password policy flags, in
sec_rgy_plcy_pwd_flags_t format.
sec_rgy_policy_auth_t This type describes authentication policy. It is a
structure that contains two time periods (in sec_timeval_period_t
format):
max_ticket_lifetime Specifies the maximum length of the period
a TGT is valid.
max_renewable_lifetime Specifies the maximum length of time a
TGT can be renewed. This authentication policy
applies both to the registry as a whole and individual accounts. The
effective policy for a given account is defined to be the more
restrictive of the site and account authentication policy.
sec_rgy_properties_t A structure that describes some registry properties. It
contains the following:
read_version A 32-bit integer that describes the earliest
version of the secd software that can read this
registry.
write_version A 32-bit integer that describes the version of
the secd software that wrote this registry.
minimum_ticket_lifetime The minimum lifetime of an
authentication certificate, in sec_timeval_period_t
format.
default_certificate_lifetime The normal lifetime of an
authentication certificate (ticket-granting ticket in
Kerberos parlance), in sec_timeval_period_t format.
Processes can request authentication certificates
with longer lifetimes up to, but not in excess of,
the maximum allowable lifetime as determined by the
effective policy for the account.
low_unix_id_person The lowest UNIX number permissible for a
person item in the registry.
low_unix_id_group The lowest UNIX number permissible for a
group item in the registry.
low_unix_id_org The lowest UNIX number permissible for an
organization item in the registry.
max_unix_id The largest UNIX number permissible for any
registry entry.
flags Property flags, in sec_rgy_properties_flags_t format.
realm The name of the cell, in sec_rgy_name_t form, for
which this registry is the authentication service.
realm_uuid The UUID of the same cell.
sec_rgy_properties_flags_t A 32-bit bitset, that contains flags concerning
registry properties.
sec_rgy_prop_readonly If set (TRUE), indicates that this
registry is a query site.
sec_rgy_prop_auth_cert_unbound If set (TRUE), the registry
server accepts requests from any site.
sec_rgy_prop_shadow_passwd If the shadow password flag is set
(TRUE), the registry server does not include the
account password when responding to a request for the
user data from a specified account. This minimizes
the risk of an account password being intercepted
while travelling over the network.
sec_rgy_prop_embedded_unix_id Indicates that all UUIDs in this
registry contain a UNIX number embedded. This implies
that the UNIX numbers of objects in the registry
cannot be changed, because UUIDs are immutable.
sec_rgy_override_t A 32-bit integer used as a flag for registry override mode.
Currently, its possible values are the constants sec_rgy_no_override
and sec_rgy_override. When this mode is enabled, override data
supplied by the node administrator replaces some of the data
received from the registry for a given person or account under
certain conditions. These conditions are:
o The registry permits the requested overrides to be set for this
machine.
o The override data is intended for the person or account at
hand. When the mode is sec_rgy_no_override, data from the
registry is returned to the end user or application untouched.
sec_rgy_mode_resolve_t A 32-bit integer used as a flag for resolve mode.
Currently, its possible values are the constants
sec_rgy_no_resolve_pname and sec_rgy_resolve_pname. When the mode is
enabled, path names that contains leading slashes (//) are
translated into a form understandable by the local machine's NFS.
sec_rgy_unix_passwd_buf_t A character array of UNIX password strings.
ΓòÉΓòÉΓòÉ 8.9.2. Registry Constants ΓòÉΓòÉΓòÉ
The following constants are used in sec_rgy routines:
sec_rgy_default_handle The value of an unbound registry server handle.
sec_rgy_pname_t_size The maximum number of characters in a sec_rgy_pname_t.
sec_rgy_name_t_size The maximum number of characters in a sec_rgy_name_t.
Note: The sec_rgy_name_t structure allows a maximum
length of 1024 characters. However, when
specifying a pgo name size, 1010 characters is
the actual safe limit.
sec_rgy_pgo_flags_t A 32-bit constant equal to a variable of type
sec_rgy_pgo_flags_t with no flags set.
sec_rgy_quota_unlimited A 32-bit integer. Set the quota field of the
sec_rgy_pgo_item_t type to this constant to override the
registry quota limitation.
sec_rgy_acct_admin_flags_t A 32-bit integer. This is the value of the
sec_rgy_acct_admin_flags_t bitset when none of its flags
are set.
sec_rgy_acct_auth_flags_none A 32-bit integer. This is the value of the
sec_rgy_acct_auth_flags_t bitset when none of its flags
are set.
sec_rgy_acct_user_flags_t A 16-bit integer. This is the value of the
sec_rgy_acct_user_flags_t bitset when none of its flags
are set.
sec_rgy_plcy_pwd_flags_t A 16-bit integer. This is the value of the
sec_rgy_policy_pwd_flags_t bitset when none of its flags
are set.
sec_rgy_properties_flags_t A 16-bit integer. This is the value of the
sec_rgy_properties_flags_t bitset when none of its flags
are set.
sec_rgy_override A 32-bit integer that turns the registry override mode
on. When this mode is enabled, override data supplied by
the node administrator replaces some of the data gotten
from the registry for a given person/account under
certain conditions.
sec_rgy_no_override A 32-bit integer that turns off the registry override
mode.
sec_rgy_resolve_pname A 32-bit integer that turns on the registry resolve
mode. When the mode is enabled, path names that
contains leading // (slashes) are translated into a form
understandable by the local machine's NFS.
sec_rgy_no_resolve_pname A 32-bit integer that turns off the registry resolve
mode.
The following 32-bit integer constants are used with the sec_rgy_acct_key_t
data type:
sec_rgy_acct_key_none The key is not valid.
sec_rgy_acct_key_person The person name alone is adequate.
sec_rgy_acct_key_group The person and group names are both necessary for the
account abbreviation.
sec_rgy_acct_key_org The person, group, and organization names are all
necessary.
sec_rgy_acct_key_last Key values must be less than this constant.
The following 32-bit integer constants are the possible values of the
sec_rgy_domain_t data type.
sec_rgy_domain_person The name refers to a person.
sec_rgy_domain_group The name refers to a group.
sec_rgy_domain_org The name refers to an organization.
ΓòÉΓòÉΓòÉ 8.9.3. sec_rgy_acct_add ΓòÉΓòÉΓòÉ
Purpose
Adds an account for a login name.
Library
\lib\dceos2.lib
Format
#include <dce/acct.h>
void sec_rgy_acct_add(
sec_rgy_handle_t context,
sec_rgy_login_name_t *login_name,
sec_rgy_acct_key_t *key_parts,
sec_rgy_acct_user_t *user_part,
sec_rgy_acct_admin_t *admin_part,
sec_passwd_rec_t *caller_key,
sec_passwd_rec_t *new_key,
sec_passwd_type_t new_keytype,
sec_passwd_version_t *new_key_version,
error_status_t *status);
Parameters
Input
context An opaque handle bound to a registry server. Use
sec_rgy_site_open to acquire a bound handle.
login_name A pointer to the account login name. A login name is
composed of three character strings that contains the
principal, group, and organization (PGO) names
corresponding to the account. All three names must be
completely specified.
key_parts A pointer to the minimum abbreviation allowed when
logging in to the account. Abbreviations are not
currently implemented and the only legal value is
sec_rgy_acct_key_person.
user_part A pointer to the sec_rgy_acct_user_t structure that
contains the user part of the account data. This
represents such information as the account password,
home directory, and default shell.
admin_part A pointer to the sec_rgy_acct_admin_t structure that
contains the administrative part of an account's data.
This information includes the account creation and
expiration dates and flags describing limits to the use
of privilege attribute certificates, among other
information.
caller_key A key to use to encrypt new_key for transmission to the
registry server.
new_key The password for the new account. During transmission
to the registry server, it is encrypted with
caller_key.
new_keytype The type of the new key. The server uses this
parameter to decide how to encode new_key if it is sent
as plain text.
Output
new_key_version The key version number returned by the server. If
the client requests a particular key version number
(using the version_number field of the new_key input
parameter), the server returns the requested version
number back to the client.
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns one of the following errors:
sec_rgy_not_authorized The client program is not
authorized to add an account
to the registry.
sec_rgy_not_member_group The indicated principal
is not a member of the
indicated group.
sec_rgy_not_member_org The indicated principal is
not a member of the
indicated organization.
sec_rgy_not_member_group_org The indicated
principal is not a member of
the indicated group or
organization.
sec_rgy_object exists The account to be added
already exists.
sec_rgy_server_unavailable The DCE Registry Server
is unavailable.
Usage
The sec_rgy_acct_add routine adds an account with the specified login
name. The login name is given in three parts, corresponding to the
principal, group, and organization names for the account.
The key_parts parameter specifies the minimum login abbreviation for
the account. If the requested abbreviation duplicates an existing
abbreviation for another account, the routine supplies the next
shortest unique abbreviation and returns this abbreviation in
key_parts. Abbreviations are not currently implemented.
Permissions Required
The sec_rgy_acct_add routine requires the following permissions on
the account (principal) that is to be added:
o The mgmt_info (m) permission to change management information
o The auth_info (a) permission to change authentication
information
o The user_info (u) permission to change user information.
Notes
The constituent principal, group, and organization (PGO) items for an
account must be added before the account can be created. Also, the
principal must have been added as a member of the specified group and
organization. See sec_rgy_pgo_add_member.
Related Information
Routines: sec_rgy_acct_delete
sec_rgy_pgo_add
sec_rgy_pgo_add_member
sec_rgy_site_open
ΓòÉΓòÉΓòÉ 8.9.4. sec_rgy_acct_admin_replace ΓòÉΓòÉΓòÉ
Purpose
Replaces administrative account data.
Library
\lib\dceos2.lib
Format
#include <dce/acct.h>
void sec_rgy_acct_admin_replace(
sec_rgy_handle_t context,
sec_rgy_login_name_t *login_name,
sec_rgy_acct_key_t *key_parts,
sec_rgy_acct_admin_t *admin_part,
error_status_t *status);
Parameters
Input
context An opaque handle bound to a registry server. Use
sec_rgy_site_open to acquire a bound handle.
login_name A pointer to the account login name. A login name is
composed of three character strings, that contains the
principal, group, and organization (PGO) names
corresponding to the account. For the group and
organization names, blank strings serve as wildcards,
matching any entry. The principal name must be input.
key_parts A pointer to the minimum abbreviation allowed when
logging in to the account. Abbreviations are not
currently implemented and the only legal value is
sec_rgy_acct_key_person.
admin_part A pointer to the sec_rgy_acct_admin_t structure that
contains the administrative part of an account's data.
This information includes the account creation and
expiration dates and flags describing limits to the use
of privilege attribute certificates, among other
information, and can be modified only by an
administrator. The sec_rgy_acct_admin_t structure
contains the following fields:
creator The identity of the principal who
created this account, in
sec_rgy_foreign_id_t form. This
field is set by the registry
server.
creation_date The date (sec_timeval_sec_t) the
account was created. This field
is set by the registry server.
last_changer The identity of the principal who
last modified any of the account
information (user or
administrative). This field is
set by the registry server.
change_date The date (sec_timeval_sec_t) the
account was last modified (either
user or administrative data).
This field is set by the registry
server.
expiration_date The date (sec_timeval_sec_t) the
account ceases to be valid.
good_since_date This date (sec_timeval_sec_t) is
for Kerberos-style TGT
revocation. Ticket-granting
tickets (TGTs) issued before this
date are not honored by
authenticated network services.
flags Contains administration flags
used as part of the
administrator's information for
any registry account. This field
is in sec_rgy_acct_admin_flags_t
form. (See Registry API for a
complete description of these
flags.)
authentication_flags These two fields, in
sec_rgy_acct_admin_flags_t and
sec_rgy_acct_auth_flags_t form,
respectively, contain flags
controlling account use of
authentication services. See
"Registry API" under Registry
Constants for a complete
description of these flags.
Output
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns one of the following errors:
sec_rgy_not_authorized The client program is not
authorized to change the
administrative information
for the specified account.
sec_rgy_object_not_found The registry server could
not find the specified name.
sec_rgy_server_unavailable The DCE Registry Server
is unavailable.
Usage
The sec_rgy_acct_admin_replace routine replaces the administrative
information in the account record specified by the input login name.
The administrative information contains limitations on the account's
use and privileges. It can be modified only by a registry
administrator - that is, a user with the auth_info (abbreviated as a)
privilege for an account.
The key_parts parameter identifies how many of the login_name parts
to use as the unique abbreviation for the account. If the requested
abbreviation duplicates an existing abbreviation for another account,
the routine supplies the next shortest unique abbreviation and
returns this abbreviation using key_parts.
Permissions Required
The sec_rgy_acct_admin_replace routine requires the following
permissions on the account principal:
o The mgmt_info (m) permission, if flags or expiration_date is to
be changed
o The auth_info (a) permission, if authentication_flags or
good_since_date is to be changed.
Notes
All users need the write (w) privilege in the appropriate ACL entry
to modify any account information.
Related Information
Routines: sec_rgy_acct_user_replace
sec_rgy_acct_replace_all
sec_rgy_acct_lookup
sec_rgy_site_open
ΓòÉΓòÉΓòÉ 8.9.5. sec_rgy_acct_delete ΓòÉΓòÉΓòÉ
Purpose
Deletes an account.
Library
\lib\dceos2.lib
Format
#include <dce/acct.h>
void sec_rgy_acct_delete(
sec_rgy_handle_t context,
sec_rgy_login_name_t *login_name,
error_status_t *status);
Parameters
Input
context A pointer to an opaque handle bound to a registry
server. Use sec_rgy_site_open to acquire a bound
handle.
login_name A pointer to the account login name. A login name is
composed of three character strings, containing the
principal, group, and organization (PGO) names
corresponding to the account. Only the principal name
is required to perform the deletion.
Output
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns one of the following errors:
sec_rgy_not_authorized The client program is not
authorized to delete the
specified account.
sec_rgy_object_not_found No PGO item was found
with the given name.
sec_rgy_server_unavailable The DCE Registry Server
is unavailable.
Usage
The sec_rgy_acct_delete routine deletes from the registry the account
corresponding to the specified login name.
Permissions Required
The sec_rgy_acct_delete routine requires the following permissions on
the account principal:
o The m (mgmt_info) permission to remove management information
o The a (auth_info) permission to remove authentication
information
o The u (user_info) permission to remove user information.
Notes
Even though the account is deleted, the PGO items corresponding to
the account remain. They must be deleted with separate calls to
sec_rgy_pgo_delete.
Related Information
Routines: sec_rgy_acct_add
sec_rgy_pgo_delete
sec_rgy_cursor_reset
sec_rgy_site_open
ΓòÉΓòÉΓòÉ 8.9.6. sec_rgy_acct_get_projlist ΓòÉΓòÉΓòÉ
Purpose
Returns the projects (groups) in an account's project list.
Library
\lib\dceos2.lib
Format
#include <dce/acct.h>
void sec_rgy_acct_get_projlist(
sec_rgy_handle_t context,
sec_rgy_login_name_t *login_name,
sec_rgy_cursor_t *projlist_cursor,
unsigned32 max_number,
unsigned32 *supplied_number,
uuid_t id_projlist[],
unsigned32 unix_projlist[],
unsigned32 *num_projects,
error_status_t *status);
Parameters
Input
context An opaque handle bound to a registry server. Use
sec_rgy_site_open to acquire a bound handle.
login_name A pointer to the account login name. A login name is
composed of three character strings, containing the
principal, group, and organization (PGO) names
corresponding to the account. For the group and
organization names, blank strings can serve as
wildcards, matching any entry. The principal name must
be input.
max_number The maximum number of projects to be returned by the
routine. This must be no larger than the allocated size
of the projlist arrays.
Input/Output
projlist_cursor An opaque pointer indicating a specific project in an
account's project list. The sec_rgy_acct_get_projlist
routine returns the project indicated by
projlist_cursor, and advances the cursor to point to
the next project on the list. When the end of the list
is reached, the routine returns the value
sec_rgy_no_more_entries in the status parameter. Use
sec_rgy_cursor_reset to reset the cursor.
Output
supplied_number A pointer to the actual number of projects returned.
This is always less than or equal to the max_number
supplied on input. If there are more projects in the
account list, sec_rgy_acct_get_projlist sets
projlist_cursor to point to the next entry after the
last one in the returned list.
id_projlist An array to receive the UUID of each project returned.
The size allocated for the array is given by
max_number. If this value is less than the total
number of projects in the account project list,
multiple calls must be made to return all of the
projects.
unix_projlist An array to receive the UNIX number of each project
returned. The size allocated for the array is given by
max_number. If this value is less than the total
number of projects in the account project list,
multiple calls must be made to return all of the
projects.
num_projects A pointer indicating the total number of projects in
the specified account's project list.
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns one of the following errors:
sec_rgy_no_more_entries The cursor is at the end
of the list of projects.
sec_rgy_not_authorized The client program is not
authorized to see a project
list for this principal.
sec_rgy_server_unavailable The DCE Registry Server
is unavailable.
Usage
The sec_rgy_acct_get_projlist routine returns members of the project
list for the specified account. It returns the project information
in two arrays. The id_projlist array contains the UUIDs for the
returned projects. The unix_projlist array contains the UNIX numbers
for the returned projects.
The project list cursor, projlist_cursor, provides an automatic place
holder in the project list. The sec_rgy_acct_get_projlist routine
automatically updates this parameter to point to the next project in
the project list. To return an entire project list, reset
projlist_cursor with sec_rgy_cursor_reset on the initial call and
then issue successive calls until all the projects are returned.
Permissions Required
The sec_rgy_acct_get_projlist routine requires the r (read)
permission on the account principal for which the project list data
is to be returned.
Cautions
There are several different types of cursors used in the Registry
API. Some cursors point to PGO items, others point to members in a
membership list, and others point to account data. Do not use a
cursor for one type of object in a call expecting another type of
object. For example, you cannot use the same cursor on a call to
sec_rgy_acct_get_projlist and sec_rgy_pgo_get_next. The behavior in
this case is undefined.
Furthermore, cursors are specific to a server.
Use sec_rgy_cursor_reset to renew a cursor for use with another call
or for another server.
Related Information
Routines: sec_rgy_cursor_reset
sec_rgy_pgo_get_next
ΓòÉΓòÉΓòÉ 8.9.7. sec_rgy_acct_lookup ΓòÉΓòÉΓòÉ
Purpose
Returns data for a specified account.
Library
\lib\dceos2.lib
Format
#include <dce/acct.h>
void sec_rgy_acct_lookup(
sec_rgy_handle_t context,
sec_rgy_login_name_t *name_key,
sec_rgy_cursor_t *account_cursor,
sec_rgy_login_name_t *name_result,
sec_rgy_sid_t *id_sid,
sec_rgy_unix_sid_t *unix_sid,
sec_rgy_acct_key_t *key_parts,
sec_rgy_acct_user_t *user_part,
sec_rgy_acct_admin_t *admin_part,
error_status_t *status);
Parameters
Input
context An opaque handle bound to a registry server. Use
sec_rgy_site_open to acquire a bound handle.
name_key A pointer to the account login name. A login name is
composed of three character strings, containing the
principal, group, and organization (PGO) names
corresponding to the account. Blank strings serve as
wildcards, matching any entry.
Input/Output
account_cursor An opaque pointer to a specific account in the
registry database. If name_key is blank,
sec_rgy_acct_lookup returns information about the
account to which the cursor is pointing. On return,
the cursor points to the next account in the database
after the returned account. If name_key is blank and
the account_cursor has been reset with
sec_rgy_cursor_reset, sec_rgy_acct_lookup returns
information about the first account in the database.
When the end of the list of accounts in the database is
reached, the routine returns the value
sec_rgy_no_more_entries in the status parameter. Use
sec_rgy_cursor_reset to refresh the cursor.
Output
name_result A pointer to the full login name of the account
(including all three names) for which the information
is returned. The remaining parameters contain the
information belonging to the returned account.
id_sid A structure containing the three UUIDs of the
principal, group, and organization for the account.
unix_sid A structure containing the three UNIX numbers of the
principal, group, and organization for the account.
key_parts A pointer to the minimum abbreviation allowed when
logging in to the account. Abbreviations are not
currently implemented and the only legal value is
sec_rgy_acct_key_person.
user_part A pointer to the sec_rgy_acct_user_t structure
containing the user part of the account data. This
represents such information as the account password,
home directory, and default shell, all of which are
accessible to, and can be modified by, the account
owner.
admin_part A pointer to the sec_rgy_acct_admin_t structure
containing the administrative part of an account's
data. This information includes the account creation
and expiration dates and flags describing limits to the
use of privilege attribute certificates, among other
information, and can be modified only by an
administrator.
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns one of the following errors:
sec_rgy_no_more_entries The cursor is at the end
of the accounts in the
registry.
sec_rgy_object_not_found The input account could
not be found by the registry
server.
sec_rgy_server_unavailable The DCE Registry Server
is unavailable.
Usage
The sec_rgy_acct_lookup routine returns all the information about an
account in the registry database. The account can be specified
either with name_key or account_cursor. If name_key is completely
blank, the routine uses the account_cursor value instead.
For name_key, a zero-length principal, group, or organization key
serves as a wildcard. For example, a login name key with the
principal and organization fields blank returns the next (possibly
first) account whose group matches the input group field. The full
login name of the returned account is passed back in name_result.
The account_cursor provides an automatic place holder in the registry
database. The routine automatically updates this parameter to point
to the next account in the database, after the account for which the
information was returned. If name_key is blank and the
account_cursor has been reset with sec_rgy_cursor_reset,
sec_rgy_acct_lookup returns information about the first account in
the database.
Permissions Required
The sec_rgy_acct_lookup routine requires the r (read) permission on
the account principal to be viewed.
Cautions
There are several different types of cursors used in the Registry
Application Programmer Interface. Some cursors point to PGO items,
others point to members in a membership list, and others point to
account data. Do not use a cursor for one type of object in a call
expecting another type of object. For example, you cannot use the
same cursor on a call to sec_rgy_acct_get_projlist and
sec_rgy_pgo_get_next. The behavior in this case is undefined.
Furthermore, cursors are specific to a server.
Use sec_rgy_cursor_reset to renew a cursor for use with another call
or for another server.
Related Information
Routines: sec_rgy_cursor_reset
sec_rgy_site_open
ΓòÉΓòÉΓòÉ 8.9.8. sec_rgy_acct_passwd ΓòÉΓòÉΓòÉ
Purpose
Changes the password for an account.
Library
\lib\dceos2.lib
Format
#include <dce/acct.h>
void sec_rgy_acct_passwd(
sec_rgy_handle_t context,
sec_rgy_login_name_t *login_name,
sec_passwd_rec_t *caller_key,
sec_passwd_rec_t *new_key,
sec_passwd_type_t new_keytype,
sec_passwd_version_t *new_key_version,
error_status_t *status);
Parameters
Input
context An opaque handle bound to a registry server. Use
sec_rgy_site_open to acquire a bound handle.
login_name A pointer to the account login name. A login name is
composed of three character strings, containing the
principal, group, and organization names corresponding
to the account. You can specify a login_name using the
following form:
principal_name
group_name
org_name
You can use blanks for group_name and org_name.
caller_key A key to use to encrypt the key for transmission to the
registry server. If communications secure to the
rpc_c_authn_level_pkt_privacy level are available on a
system, this parameter is not necessary, and the packet
encryption is sufficient to ensure security.
new_key The password for the new account. During transmission
to the registry server, it is encrypted with
caller_key.
new_keytype The type of the new key. The server uses this
parameter to decide how to encode new_key if it is sent
as plain text.
Output
new_key_version The key version number, returned by the server. If
the client requests a particular key version number
(using the version_number field of the new_key input
parameter), the server returns the requested version
number back to the client.
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns one of the following errors:
sec_rgy_not_authorized The client program is not
authorized to change the
password of this account.
sec_rgy_object_not_found The account to be
modified was not found by
the registry server.
sec_rgy_server_unavailable The DCE Registry Server
is unavailable.
Usage
The sec_rgy_acct_passwd routine changes an account password to the
input password character string. Wildcards (blank fields) are not
permitted in the specified account name. You can specify a login_name
using the following form:
principal_name
group_name
org_name
You can use blanks for group_name and org_name.
Permissions Required
The sec_rgy_acct_passwd routine requires the u (user_info) permission
on the account principal whose password is to be changed.
ΓòÉΓòÉΓòÉ 8.9.9. sec_rgy_acct_rename ΓòÉΓòÉΓòÉ
Purpose
Changes an account login name.
Library
\lib\dceos2.lib
Format
#include <dce/acct.h>
void sec_rgy_acct_rename(
sec_rgy_handle_t context,
sec_rgy_login_name_t *old_login_name,
sec_rgy_login_name_t *new_login_name,
sec_rgy_acct_key_t *new_key_parts,
error_status_t *status);
Parameters
Input
context An opaque handle bound to a registry server. Use
sec_rgy_site_open to acquire a bound handle.
old_login_name A pointer to the current account login name. The login
name is composed of three character strings containing
the principal, group, and organization names
corresponding to the account. All three strings must be
completely specified.
new_login_name A pointer to the new account login name. Again, all
three component names must be completely specified.
Input/Output
new_key_parts A pointer to the minimum abbreviation allowed when
logging in to the account. Abbreviations are not
currently implemented and the only legal value is
sec_rgy_acct_key_person.
Output
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns one of the following errors:
sec_rgy_status_not_authorized The client program
is not authorized to make
the changes.
sec_rgy_object_not_found The account to be
modified was not found by
the registry server.
sec_rgy_status_name_exists The new account name is
already in use by another
account.
sec_rgy_server_unavailable The DCE Registry Server
is unavailable.
sec_rgy_bad_data The old_login_name or the
new_login_name is NULL.
Usage
The sec_rgy_acct_rename routine changes an account login name from
old_login_name to new_login_name. Wildcards (empty fields) are not
permitted in either input name; both the old and new login names must
completely specify their component principal, group, and organization
names. Note, though, that the principal component in a login name
cannot be changed.
The new_key_parts parameter identifies the number of the
new_login_name parts to use as the unique abbreviation for the
account. If the requested abbreviation duplicates an existing
abbreviation for another account, the routine identifies the next
shortest unique abbreviation and returns this abbreviation using
new_key_parts.
Permissions Required
The sec_rgy_acct_rename routine requires the m (mgmt_info) permission
on the account principal to be renamed.
Notes
The sec_rgy_acct_rename routine does not affect any of the registry
PGO data. The constituent principal, group, and organization (PGO)
items for an account must be added before the account can be created.
Also, the principal must have been added as a member of the specified
group and organization. See sec_rgy_pgo_add_member.
Related Information
Routines: sec_rgy_acct_add
sec_rgy_site_open
ΓòÉΓòÉΓòÉ 8.9.10. sec_rgy_acct_replace_all ΓòÉΓòÉΓòÉ
Purpose
Replaces all account data for an account.
Library
\lib\dceos2.lib
Format
#include <dce/acct.h>
void sec_rgy_acct_replace_all(
sec_rgy_handle_t context,
sec_rgy_login_name_t *login_name,
sec_rgy_acct_key_t *key_parts,
sec_rgy_acct_user_t *user_part,
sec_rgy_acct_admin_t *admin_part,
boolean32 *set_password,
sec_passwd_rec_t *caller_key,
sec_passwd_rec_t *new_key,
sec_passwd_type_t new_keytype,
sec_passwd_version_t *new_key_version,
error_status_t *status);
Parameters
Input
context An opaque handle bound to a registry server. Use
sec_rgy_site_open to acquire a bound handle.
login_name A pointer to the account login name. A login name is
composed of three character strings, containing the
principal, group, and organization (PGO) names
corresponding to the account. Blank strings serve as
wildcards, matching any entry.
user_part A pointer to the sec_rgy_acct_user_t structure
containing the user part of the account data. This
represents information such as the account password,
home directory, and default shell, all of which are
accessible to, and can be modified by, the account
owner.
admin_part A pointer to the sec_rgy_acct_admin_t structure
containing the administrative part of an account's
data. This information includes the account creation
and expiration dates and flags describing limits to the
use of privilege attribute certificates, among other
information, and can be modified only by an
administrator.
set_passwd The password reset flag. If you set this parameter to
TRUE, the account's password is changed to the value
specified in new_key.
caller_key A key to use to encrypt the key for transmission to the
registry server. If communications secure to the
rpc_c_authn_level_pkt_privacy level are available on a
system, this parameter is not necessary, and the packet
encryption is sufficient to ensure security.
new_key The password for the new account. During transmission
to the registry server, it is encrypted with
caller_key.
new_keytype The type of the new key. The server uses this
parameter to decide how to encode the plaintext key.
Input/Output
key_parts A pointer to the minimum abbreviation allowed when
logging in to the account. Abbreviations are not
currently implemented and the only legal value is
sec_rgy_acct_key_person.
Output
new_key_version The key version number returned by the server. If
the client requests a particular key version number
(using the version_number field of the new_key input
parameter), the server returns the requested version
number back to the client.
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns one of the following errors:
sec_rgy_not_authorized The client program is not
authorized to change account
information.
sec_rgy_object_not_found The specified account
could not be found.
sec_rgy_server_unavailable The DCE Registry Server
is unavailable.
sec_rgy_homedir_too_long The home directory is too
long.
Usage
The sec_rgy_acct_replace_all routine replaces both the user and
administrative information in the account record specified by the
input login name. The administrative information contains limitations
on the account's use and privileges. The user information contains
information such as the account home directory and default shell.
Typically, the administrative information can only be modified by a
registry administrator (users with auth_info (a) privileges for an
account), but the user information can be modified by the account
owner (users with user_info (u) privileges for an account).
Use the set_passwd parameter to reset the password. If you set this
parameter to TRUE, the account's password is changed to the value
specified in new_key.
The key_parts parameter identifies how many of the login_name parts
to use as the unique abbreviation for the replaced account. If the
requested abbreviation duplicates an existing abbreviation for
another account, the routine identifies the next shortest unique
abbreviation and returns this abbreviation using key_parts.
Permissions Required
The sec_rgy_acct_replace_all routine requires the following
permissions on the account principal:
o The m (mgmt_info) permission, if flags or expiration_date is to
be changed
o The a (auth_info) permission, if authentication_flags or
good_since_date is to be changed
o The u (user_info) permission, if user_flags, gecos,
home_directory, shell, or password is to be changed.
Notes
All users need the write (w) privilege to modify any account
information.
Related Information
Routines:
sec_rgy_acct_add
sec_rgy_acct_admin_replace
sec_rgy_acct_user_replace
ΓòÉΓòÉΓòÉ 8.9.11. sec_rgy_acct_user_replace ΓòÉΓòÉΓòÉ
Purpose
Replaces user account data.
Library
\lib\dceos2.lib
Format
#include <dce/acct.h>
void sec_rgy_acct_user_replace(
sec_rgy_handle_t context,
sec_rgy_login_name_t *login_name,
sec_rgy_acct_user_t *user_part,
boolean32 set_passwd,
sec_passwd_rec_t *caller_key,
sec_passwd_rec_t *new_key,
sec_passwd_type_t new_keytype,
sec_passwd_version_t *new_key_version,
error_status_t *status);
Parameters
Input
context An opaque handle bound to a registry server. Use
sec_rgy_site_open to acquire a bound handle.
login_name A pointer to the account login name. A login name is
composed of three character strings containing the
principal, group, and organization (PGO) names
corresponding to the account. For the group and
organization names, blank strings can serve as
wildcards, matching any entry. The principal name must
be input.
user_part A pointer to the sec_rgy_acct_user_t structure
containing the user part of the account data. This
represents such information as the account password,
home directory, and default shell, all of which are
accessible to, and can be modified by, the account
owner. The structure contains the following fields:
gecos A character string containing
information about the account
owner. This often includes
such information as their name
and telephone number.
homedir The default directory at login
for the account.
shell The default shell to use at
login.
passwd_version_number The password version number,
a 32-bit integer, set by the
registry server.
passwd_dtm The date and time of the last
password change (in
sec_timeval_sec_t form), also
set by the registry server.
flags A flag set of type
sec_rgy_acct_user_flags_t.
passwd The encrypted password of the
account.
set_passwd The password reset parameter. If you set this parameter
to TRUE, the user's password is changed to the value
specified in new_key.
caller_key A key to use to encrypt the key for transmission to the
registry server. If communications secure to the
rpc_c_authn_level_pkt_privacy level are available on a
system, then this parameter is not necessary, and the
packet encryption is sufficient to ensure security.
new_key The password for the new account. During transmission
to the registry server, it is encrypted with
caller_key.
new_keytype The type of the new key. The server uses this
parameter to decide how to encode the plaintext key.
Output
new_key_version The key version number returned by the server. If
the client requests a particular key version number (by
means of the version_number field of the new_key input
parameter), the server returns the requested version
number back to the client.
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns one of the following errors:
sec_rgy_not_authorized The client program is not
authorized to modify the
account data.
sec_rgy_object_not_found The specified account
could not be found.
sec_rgy_server_unavailable The DCE Registry Server
is unavailable.
sec_rgy_homedir_too_long The home directory is too
long.
Usage
The sec_rgy_acct_user_replace routine replaces the user information
in the account record specified by the input login name. The user
information contains such information as the account home directory
and default shell. Typically, the user information can be modified by
the account owner (users with user_info (u) privileges for an
account).
Use the set_passwd parameter to reset the user's password. If you set
this parameter to TRUE, the user's password is changed to the value
specified in new_key.
Permissions Required
The sec_rgy_acct_user_replace routine requires the u (user_info)
permission on the account principal.
Notes
All users need the write (w) privilege to modify any account
information.
Related Information
Routines: sec_rgy_acct_add
sec_rgy_acct_admin_replace
sec_rgy_site_open
sec_rgy_acct_replace_all
ΓòÉΓòÉΓòÉ 8.9.12. sec_rgy_auth_plcy_get_effective ΓòÉΓòÉΓòÉ
Purpose
Returns the effective authentication policy for an account.
Library
\lib\dceos2.lib
Format
#include <dce/policy.h>
void sec_rgy_auth_plcy_get_effective(
sec_rgy_handle_t context,
sec_rgy_login_name_t *account,
sec_rgy_plcy_auth_t *auth_policy,
error_status_t *status);
Parameters
Input
context An opaque handle bound to a registry server. Use
sec_rgy_site_open to acquire a bound handle.
account A pointer to the account login name (type
sec_rgy_login_name_t). A login name is composed of
three character strings containing the principal,
group, and organization (PGO) names corresponding to
the account. If all three fields contain empty strings,
the authentication policy returned is that of the
registry.
Output
auth_policy A pointer to the sec_rgy_plcy_auth_t structure to
receive the authentication policy. The authentication
policy structure contains the maximum lifetime for an
authentication ticket, and the maximum amount of time
for which one can be renewed.
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns one of the following errors:
sec_rgy_object_not_found The specified account
could not be found.
sec_rgy_server_unavailable The DCE Registry Server
is unavailable.
sec_rgy_bad_data The old_login_name or the
new_login_name is NULL.
Usage
The sec_rgy_auth_plcy_get_effective routine returns the effective
authentication policy for the specified account. The authentication
policy in effect is the more restrictive of the registry and the
account policies for each policy category. If no account is
specified, the registry's authentication policy is returned.
Permissions Required
The sec_rgy_auth_plcy_get_effective routine requires the r (read)
permission on the policy object from which the data is to be
returned. If an account is specified and an account policy exists,
the routine also requires the read (r) permission on the account
principal.
Related Information
Routines: sec_rgy_auth_plcy_get_info
sec_rgy_auth_plcy_set_info
ΓòÉΓòÉΓòÉ 8.9.13. sec_rgy_auth_plcy_get_info ΓòÉΓòÉΓòÉ
Purpose
Returns the authentication policy for an account.
Library
\lib\dceos2.lib
Format
#include <dce/policy.h>
void sec_rgy_auth_plcy_get_info(
sec_rgy_handle_t context,
sec_rgy_login_name_t *account,
sec_rgy_plcy_auth_t *auth_policy,
error_status_t *status);
Parameters
Input
context An opaque handle bound to a registry server. Use
sec_rgy_site_open to acquire a bound handle.
account A pointer to the account login name (type
sec_rgy_login_name_t). A login name is composed of
three character strings containing the principal,
group, and organization (PGO) names corresponding to
the account.
Output
auth_policy A pointer to the sec_rgy_plcy_auth_t structure to
receive the authentication policy. The authentication
policy structure contains the maximum lifetime for an
authentication ticket, and the maximum amount of time
for which one can be renewed.
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns the following errors:
sec_rgy_object_not_found No account with this
login name could be found.
sec_rgy_server_unavailable The DCE Registry Server
is unavailable.
sec_rgy_bad_data The old_login_name or the
new_login_name is NULL.
Usage
The sec_rgy_auth_plcy_get_info routine returns the authentication
policy for the specified account. If no account is specified, the
registry's authentication policy is returned.
Permissions Required
The sec_rgy_auth_plcy_get_info routine requires the r (read)
permission on the policy object or account principal from which the
data is to be returned.
Notes
The actual policy in effect does not correspond precisely to what is
returned by this call if the overriding registry authentication
policy is more restrictive than the policy for the specified account.
Use sec_rgy_auth_plcy_get_effective to return the policy currently in
effect for the given account.
Related Information
Routines: sec_rgy_auth_plcy_get_effective
sec_rgy_auth_plcy_set_info
sec_rgy_site_open
ΓòÉΓòÉΓòÉ 8.9.14. sec_rgy_auth_plcy_set_info ΓòÉΓòÉΓòÉ
Purpose
Sets the authentication policy for an account.
Library
\lib\dceos2.lib
Format
#include <dce/policy.h>
void sec_rgy_auth_plcy_set_info(
sec_rgy_handle_t context,
sec_rgy_login_name_t *account,
sec_rgy_plcy_auth_t *auth_policy,
error_status_t *status);
Parameters
Input
context An opaque handle bound to a registry server. Use
sec_rgy_site_open to acquire a bound handle.
account A pointer to the account login name (type
sec_rgy_login_name_t). A login name is composed of
three character strings, containing the principal,
group, and organization (PGO) names corresponding to
the account. All three names must be completely
specified.
auth_policy A pointer to the sec_rgy_plcy_auth_t structure
containing the authentication policy. The
authentication policy structure contains the maximum
lifetime for an authentication ticket, and the maximum
amount of time for which one can be renewed.
Output
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns one of the following errors:
sec_rgy_object_not_found No account with the given
login name could be found.
sec_rgy_not_authorized The user is not authorized
to update the specified
record.
sec_rgy_server_unavailable The DCE Registry Server
is unavailable.
sec_rgy_bad_data The old_login_name or the
new_login_name is NULL.
Usage
The sec_rgy_auth_plcy_set_info routine sets the indicated
authentication policy for the specified account. If no account is
specified, the authentication policy is set for the registry as a
whole.
Permissions Required
The sec_rgy_auth_plcy_set_info routine requires the auth_info (a)
permission on the policy object or account principal for which the
data is to be set.
Notes
The policy set on an account can be less restrictive than the policy
set for the registry as a whole. In this case, the change in policy
has no effect, because the effective policy is the most restrictive
combination of the principal and registry authentication policies.
See sec_rgy_auth_plcy_get_effective.
Related Information
Routines: sec_rgy_auth_plcy_get_effective
sec_rgy_auth_plcy_get_info
ΓòÉΓòÉΓòÉ 8.9.15. sec_rgy_cell_bind ΓòÉΓòÉΓòÉ
Purpose
Binds to a registry in a cell.
Library
\lib\dceos2.lib
Format
#include <dce/binding.h>
void sec_rgy_cell_bind(
unsigned_char_p_t *cell_name,
sec_rgy_bind_auth_info_t *auth_info,
sec_rgy_handle_t *context,
error_status_t *status);
Parameters
Input
cell_name A character string (type unsigned_char_t) containing
the name of the cell in question. Upon return, a
security server for that cell is associated with
context, the registry server handle. The cell must be
specified completely and precisely. This routine
offers none of the path name resolving services of
sec_rgy_site_bind.
auth_info A pointer to the sec_rgy_bind_auth_info_t structure
that identifies the authentication protocol, protection
level, and authorization protocol to use in
establishing the binding. See
rpc_binding_set_auth_info.
Output
context A pointer to a sec_rgy_handle_t. Upon return, this
contains a registry server handle indicating (bound to)
the desired registry site.
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns sec_rgy_server_unavailable, which
indicates that the DCE Registry Server is unavailable.
Usage
The sec_rgy_cell_bind routine establishes a relationship with a
registry site at an arbitrary level of security. The cell_name
parameter identifies the target cell.
Related Information
Routines:
sec_rgy_site_bind
ΓòÉΓòÉΓòÉ 8.9.16. sec_rgy_cursor_reset ΓòÉΓòÉΓòÉ
Purpose
Resets the registry database cursor.
Library
\lib\dceos2.lib
Format
#include <dce/misc.h>
void sec_rgy_cursor_reset(
sec_rgy_cursor_t *cursor);
Parameters
Input/Output
cursor A pointer into the registry database.
Usage
The sec_rgy_cursor_reset routine resets the database cursor to return
the first suitable entry. A cursor is a pointer into the registry.
It serves as a place holder when returning successive items from the
registry.
A cursor that is in use with one call cannot be used with another.
For example, you cannot use the same cursor on a call to
sec_rgy_acct_get_projlist and sec_rgy_pgo_get_next. The behavior in
this case is undefined.
Examples
The following example illustrates use of the cursor within a loop.
The initial sec_rgy_cursor_reset call resets the cursor to point to
the first item in the registry. Successive calls to
sec_rgy_pgo_get_next return the next PGO item and update the cursor
to reflect the last item returned. When the end of the list of PGO
items is reached, the routine returns the value
sec_rgy_no_more_entries in the status parameter.
sec_rgy_cursor_reset();
do {
sec_rgy_pgo_get_next(context, domain, scope, ,
&item, name, &status);
if (status == error_status_ok) {
/* Print formatted PGO item info */
}
}while (status==error_status_ok);
Related Information
Routines: sec_rgy_acct_get_projlist
sec_rgy_acct_lookup
sec_rgy_pgo_get_by_id
sec_rgy_pgo_get_by_name
sec_rgy_pgo_get_by_unix_num
sec_rgy_pgo_get_members
sec_rgy_pgo_get_next
Files:
\include\dce\misc.idl - The idl file from which dce\misc.h was
derived.
ΓòÉΓòÉΓòÉ 8.9.17. sec_rgy_enable_nsi ΓòÉΓòÉΓòÉ
Purpose
Enables and disables Name Service Interface (NSI) bindings.
Format
#include <dce\binding.h>
boolean32 sec_rgy_enable_nsi(
boolean32 flag);
Parameters
Input/Output
flag As input, a boolean32 flag that contains the code to
enable or disable the use of NSI binding by the
security code. Upon return, flag contains the previous
state of this flag. When TRUE, NSI is enabled; when
FALSE, NSI is disabled.
Usage
Enable or disable the use of NSI for security binding operations to
prevent security from attempting to access the namespace while
connecting to the registry server.
Related Information
Files:
\usr\include\dce\binding.idl - The idl file from which dce\binding.h
was derived.
ΓòÉΓòÉΓòÉ 8.9.18. sec_rgy_login_get_effective ΓòÉΓòÉΓòÉ
Purpose
Returns the effective login data for an account.
Note: For the IBM DCE for OS/2 time frame, this API will return the
same information as sec_rgy_login_get_info, as local overrides
are not supported.
Library
\lib\dceos2.lib
Format
#include <dce/misc.h>
void sec_rgy_login_get_effective(
sec_rgy_handle_t context,
sec_rgy_login_name_t *login_name,
sec_rgy_acct_key_t *key_parts,
sec_rgy_sid_t *sid,
sec_rgy_unix_sid_t *unix_sid,
sec_rgy_acct_user_t *user_part,
sec_rgy_acct_admin_t *admin_part,
sec_rgy_plcy_t *policy_data,
signed32 max_number,
signed32 *supplied_number,
uuid_t id_projlist[],
signed32 unix_projlist[],
signed32 *num_projects,
sec_rgy_name_t cell_name,
uuid_t *cell_uuid,
sec_override_fields_t *overridden,
error_status_t *status);
Parameters
Input
context The registry server handle.
max_number The maximum number of projects to be returned by the
routine. This must be no larger than the allocated size
of the projlist array.
Input/Output
login_name A pointer to the account login name. A login name is
composed of the names for the account's principal,
group, and organization (PGO) items.
Output
key_parts A pointer to the minimum abbreviation allowed when
logging in to the account. Abbreviations are not
currently implemented and the only permitted value is
sec_rgy_acct_key_person.
sid A pointer to a sec_rgy_sid_t structure to receive the
returned subject identifier (SID) for the account.
This structure consists of the UUIDs for the account's
PGO items.
unix_sid A pointer to a sec_rgy_unix_sid_t structure to receive
the returned UNIX subject identifier (SID) for the
account. This structure consists of the UNIX numbers
for the account's PGO items.
user_part A pointer to a sec_rgy_acct_user_t structure to receive
the returned user data for the account.
admin_part A pointer to a sec_rgy_acct_admin_t structure to
receive the returned administrative data for the
account.
policy_data A pointer to a sec_rgy_policy_t structure to receive
the policy data for the account. The policy data is
associated with the account's organization, as
identified in the login name.
supplied_number A pointer to the actual number of projects returned.
This is always less than or equal to the max_number
supplied on input.
id_projlist[] An array to receive the UUID of each project returned.
The size allocated for the array is given by
max_number. If this value is less than the total number
of projects in the account project list, multiple calls
must be made to return all of the projects.
unix_projlist[] An array to receive the UNIX number of each project
returned. The size allocated for the array is given by
max_number. If this value is less than the total number
of projects in the account project list, multiple calls
must be made to return all of the projects.
num_projects A pointer indicating the total number of projects in
the specified account's project list.
cell_name The name of the account's cell.
cell_uuid The UUID for the account's cell.
overridden A pointer to a 32-bit set of flags identifying the
local overrides, if any, for the account login
information.
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns one of the following errors:
sec_rgy_object_not_found The specified account
could not be found.
sec_rgy_server_unavailable The DCE Registry Server
is unavailable.
Usage
The sec_rgy_login_get_effective routine returns effective login
information for the specified account. Login information is extracted
from the account's entry in the registry database. Effective login
information is a combination of the login information from the
registry database and any login overrides defined for the account on
the local machine.
This API returns the same information as sec_rgy_login_get_info,
since local overrides are not supported.
Related Information
Routines: sec_rgy_acct_add
sec_rgy_login_get_info
ΓòÉΓòÉΓòÉ 8.9.19. sec_rgy_login_get_info ΓòÉΓòÉΓòÉ
Purpose
Returns login information for an account.
Library
\lib\dceos2.lib
Format
#include <dce/misc.h>
void sec_rgy_login_get_info(
sec_rgy_handle_t context,
sec_rgy_login_name_t *login_name,
sec_rgy_acct_key_t *key_parts,
sec_rgy_sid_t *sid,
sec_rgy_unix_sid_t *unix_sid,
sec_rgy_acct_user_t *user_part,
sec_rgy_acct_admin_t *admin_part,
sec_rgy_plcy_t *policy_data,
signed32 max_number,
signed32 *supplied_number,
uuid_t id_projlist[],
signed32 unix_projlist[],
signed32 *num_projects,
sec_rgy_name_t cell_name,
uuid_t *cell_uuid,
error_status_t *status);
Parameters
Input
context The registry server handle.
max_number The maximum number of projects to be returned by the
routine. This must be no larger than the allocated size
of the projlist array.
Input/Output
login_name A pointer to the account login name. A login name is
composed of the names for the account's principal,
group, and organization (PGO) items.
Output
key_parts A pointer to the minimum abbreviation allowed when
logging in to the account. Abbreviations are not
currently implemented and the only permitted value is
sec_rgy_acct_key_person.
sid A pointer to a sec_rgy_sid_t structure to receive the
UUIDs representing the account's PGO items.
unix_sid A pointer to a sec_rgy_unix_sid_t structure to receive
the UNIX numbers for the account's PGO items.
user_part A pointer to a sec_rgy_acct_user_t structure to receive
the returned user data for the account.
admin_part A pointer to a sec_rgy_acct_admin_t structure to
receive the returned administrative data for the
account.
policy_data A pointer to a sec_rgy_policy_t structure to receive
the policy data for the account. The policy data is
associated with the account's organization, as
identified in the login name.
supplied_number A pointer to the actual number of projects returned.
This is always less than or equal to the max_number
supplied on input.
id_projlist[] An array to receive the UUID of each project returned.
The size allocated for the array is given by
max_number. If this value is less than the total number
of projects in the account project list, multiple calls
must be made to return all of the projects.
unix_projlist[] An array to receive the UNIX number of each project
returned. The size allocated for the array is given by
max_number. If this value is less than the total number
of projects in the account project list, multiple calls
must be made to return all of the projects.
num_projects A pointer indicating the total number of projects in
the specified account's project list.
cell_name The name of the account's cell.
cell_uuid The UUID for the account's cell.
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns one of the following errors:
sec_rgy_object_not_found The specified account
could not be found.
sec_rgy_server_unavailable The DCE Registry Server
is unavailable.
Usage
The sec_rgy_login_get_info routine returns login information for the
specified account. This information is extracted from the account's
entry in the registry database.
Permissions Required
The sec_rgy_login_get_info routine requires the read (r) permission
on the account principal from which the data is to be returned.
Related Information
Routines: sec_rgy_acct_add
sec_rgy_login_get_effective
ΓòÉΓòÉΓòÉ 8.9.20. sec_rgy_pgo_add ΓòÉΓòÉΓòÉ
Purpose
Adds a principal, group, or organization (PGO) item to the registry
database.
Library
\lib\dceos2.lib
Format
#include <dce/pgo.h>
void sec_rgy_pgo_add(
sec_rgy_handle_t context,
sec_rgy_domain_t name_domain,
sec_rgy_name_t name,
sec_rgy_pgo_item_t *pgo_item,
error_status_t *status);
Parameters
Input
context An opaque handle bound to a registry server. Use
sec_rgy_site_open to acquire a bound handle.
name_domain This parameter identifies the type of the PGO item
identified by the given name. The valid values are as
follows:
sec_rgy_domain_person The name identifies a
principal.
sec_rgy_domain_group The name identifies a
group.
sec_rgy_domain_org The name identifies an
organization.
name A pointer to a sec_rgy_name_t character string
containing the name of the new PGO item.
pgo_item A pointer to a sec_rgy_pgo_item_t structure containing
the data for the new PGO item. The data in this
structure includes the PGO item's name, UUID, UNIX
number (if any), and administrative data, such as
whether the item belongs (or has belonged) to a
concurrent group set.
Output
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns one of the following errors:
sec_rgy_not_authorized The client program is
not authorized to add
the specified PGO item.
sec_rgy_object_exists A PGO item already
exists with the name
given in name.
sec_rgy_server_unavailable The DCE Registry Server
is unavailable.
Usage
The sec_rgy_pgo_add routine adds a PGO item to the registry database.
The PGO data consists of:
o The universal unique identifier (UUID) of the PGO item. Specify
NULL to have the registry server create a new UUID for an item.
o The UNIX number for the PGO item. If the registry uses embedded
UNIX IDs (where a subset of the UUID bits represent the UNIX
ID), the specified ID must match the UUID, if both are
specified. Use a value of -1 for the UNIX number to match any
value.
o The quota for subaccounts allowed for this item entry.
o The full name of the PGO item.
o Flags (in the sec_rgy_pgo_flags_t format) indicating whether:
- A person item is an alias.
- The PGO item can be deleted from the registry.
- A person item can have a concurrent group set.
- A group item can appear in a concurrent group set.
Permissions Required
The sec_rgy_pgo_add routine requires the insert (i) permission on the
parent directory in which the PGO item is to be created.
Notes
An account can be added to the registry database only when all its
constituent PGO items are already in the database, and the
appropriate membership relationships between them are established.
For example, to establish an account with person name tom, group name
writers, and organization name ibm, all three names must exist as
independent PGO items in the database. Also, tom must be a member of
the group writers, which in return, must be a member of ibm. See
sec_rgy_acct_add to add an account to the registry.
Related Information
Routines: sec_rgy_pgo_delete
sec_rgy_pgo_rename
sec_rgy_pgo_replace
sec_rgy_pgo_add_member
sec_rgy_acct_add
ΓòÉΓòÉΓòÉ 8.9.21. sec_rgy_pgo_add_member ΓòÉΓòÉΓòÉ
Purpose
Adds a person to a group or organization.
Library
\lib\dceos2.lib
Format
#include <dce/pgo.h>
void sec_rgy_pgo_add_member(
sec_rgy_handle_t context,
sec_rgy_domain_t name_domain,
sec_rgy_name_t go_name,
sec_rgy_name_t person_name,
error_status_t *status);
Parameters
Input
context An opaque handle bound to a registry server. Use
sec_rgy_site_open to acquire a bound handle.
name_domain This parameter identifies the type of the PGO item
identified by the given name. The valid values are:
sec_rgy_domain_group The go_name identifies a
group.
sec_rgy_domain_org go_name identifies an
organization.
go_name A character string (type sec_rgy_name_t) that contains
the name of the group or organization to which the
specified person is added.
person_name A character string (type sec_rgy_name_t) that contains
the name of the person to be added to the membership
list of the group or organization specified by go_name.
Output
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns one of the following errors:
sec_rgy_not_authorized The client program is not
authorized to add members to
the specified group or
organization.
sec_rgy_bad_domain The specified domain is not
valid. A member can be added
to a group or organization
only, not a person.
sec_rgy_object_not_found The registry server could
not find the specified name.
sec_rgy_server_unavailable The DCE Registry Server
is unavailable.
Usage
The sec_rgy_pgo_add_member routine adds a member to the membership
list of a group or organization in the registry database.
Permissions Required
The sec_rgy_pgo_add_member routine requires the Member_list (M)
permission on the group or organization item specified by go_name. If
go_name specifies a group, the routine also requires the groups (g)
permission on the principal person_name.
Notes
An account can be added to the registry database only when all its
constituent PGO items are already in the database, and the
appropriate membership relationships between them are established.
For example, to establish an account with person name tom, group name
writers, and organization name ibm, all three names must exist as
independent PGO items in the database. Also, tom must be a member of
the group writers, which, in turn, must be a member of ibm. See
sec_rgy_acct_add to add an account to the registry.
Related Information
Routines: sec_rgy_pgo_add
sec_rgy_pgo_delete_member
sec_rgy_pgo_get_members
sec_rgy_pgo_is_member
sec_rgy_acct_add
ΓòÉΓòÉΓòÉ 8.9.22. sec_rgy_pgo_delete ΓòÉΓòÉΓòÉ
Purpose
Deletes a principal, group, or organization (PGO) item from the
registry database.
Library
\lib\dceos2.lib
Format
#include <dce/pgo.h>
void sec_rgy_pgo_delete(
sec_rgy_handle_t context,
sec_rgy_domain_t name_domain,
sec_rgy_name_t name,
error_status_t *status);
Parameters
Input
context An opaque handle bound to a registry server. Use
sec_rgy_site_open to acquire a bound handle.
name_domain This parameter identifies the type of the PGO item
identified by the given name. The valid values are:
sec_rgy_domain_person The name identifies a
principal.
sec_rgy_domain_group The name identifies a group.
sec_rgy_domain_org The name identifies an
organization.
name A pointer to a sec_rgy_name_t character string that
contains the name of the PGO item to be deleted.
Output
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns one of the following errors:
sec_rgy_not_authorized The client program is not
authorized to delete the
specified item.
sec_rgy_object_not_found The registry server could
not find the specified item.
sec_rgy_server_unavailable The DCE Registry Server
is unavailable.
Usage
The sec_rgy_pgo_delete routine deletes a PGO item from the registry
database. Any account depending on the deleted PGO item is also
deleted.
Permissions Required
The sec_rgy_pgo_delete routine requires the following permissions:
o The delete (d) permission on the parent directory that contains
the PGO item to be deleted.
o The Delete_object (D) permission on the PGO item itself.
Related Information
Routines: sec_rgy_site_open
sec_rgy_pgo_add
Files:
\include\dce\pgo.idl - The idl file from which dce\pgo.h was derived.
ΓòÉΓòÉΓòÉ 8.9.23. sec_rgy_pgo_delete_member ΓòÉΓòÉΓòÉ
Purpose
Deletes a member of a group or organization.
Library
\lib\dceos2.lib
Format
#include <dce/pgo.h>
void sec_rgy_pgo_delete_member(
sec_rgy_handle_t context,
sec_rgy_domain_t name_domain,
sec_rgy_name_t go_name,
sec_rgy_name_t person_name,
error_status_t *status);
Parameters
Input
context An opaque handle bound to a registry server. Use
sec_rgy_site_open to acquire a bound handle.
name_domain This parameter identifies the type of the group or
organization item identified by the given name. The
valid values are:
sec_rgy_domain_group The go_name parameter
identifies a group.
sec_rgy_domain_org The go_name parameter
identifies an organization.
go_name A character string (type sec_rgy_name_t) that contains
the name of the group or organization from which the
specified person is deleted.
person_name A character string (type sec_rgy_name_t) that contains
the name of the person to be deleted from the
membership list of the group or organization specified
by go_name.
Output
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns one of the following errors:
sec_rgy_not_authorized The client program is not
authorized to delete the
specified member.
sec_rgy_bad_domain The specified domain is
not valid. Members can
exist for groups and
organizations only, not
for persons.
sec_rgy_object_not_found The specified group or
organization was not
found.
sec_rgy_server_unavailable The DCE registry server
is unavailable.
Usage
The sec_rgy_pgo_delete_member routine deletes a member from the
membership list of a group or organization. Any accounts where the
person holds the deleted group or organization membership are also
deleted.
Permissions Required
The sec_rgy_pgo_delete_member routine requires the Member_list (M)
permission on the group or organization item specified by go_name.
Related Information
Routines: sec_rgy_pgo_add
sec_rgy_pgo_add_member
sec_rgy_site_open
ΓòÉΓòÉΓòÉ 8.9.24. sec_rgy_pgo_get_by_eff_unix_num ΓòÉΓòÉΓòÉ
Purpose
Returns the name and data for a principal, group, or organization
(PGO) item identified by its effective UNIX number.
Library
\lib\dceos2.lib
Format
#include <dce/pgo.h>
void sec_rgy_pgo_get_by_eff_unix_num(
sec_rgy_handle_t context,
sec_rgy_domain_t name_domain,
sec_rgy_name_t scope,
signed32 unix_id,
boolean32 allow_aliases,
sec_rgy_cursor_t *item_cursor,
sec_rgy_pgo_item_t *pgo_item,
sec_rgy_name_t name,
boolean32 *overridden,
error_status_t *status);
Parameters
Input
context An opaque handle bound to a registry server. Use
sec_rgy_site_open to acquire a bound handle.
name_domain This variable identifies the type of the PGO item
identified by the given name. The valid values are:
sec_rgy_domain_person The UNIX number
identifies a principal.
sec_rgy_domain_group The UNIX number
identifies a group.
Note: This routine does not support the value
sec_rgy_domain_org.
scope A character string (type sec_rgy_name_t) that contains
the scope of the desired search. The registry database
is designed to accommodate a tree-structured name
hierarchy. The scope of a search is the name of the
branch where the search takes place. For example, all
names in a registry may start with \alpha, and be
divided further into \beta or \gamma. To search only
the part of the database under \beta, the scope of the
search would be \alpha\beta, and any resulting PGO
items would have names beginning with this string.
Note: These naming conventions do not need to have
anything to do with group or organization PGO
item membership lists.
unix_id The UNIX number of the desired registry PGO item.
allow_aliases A boolean32 value that indicates whether to search for
a primary PGO item, or whether the search can be
satisfied with an alias. If TRUE, the routine returns
the next entry found for the PGO item. If FALSE, the
routine returns only the primary entry.
Input/Output
item_cursor An opaque pointer that indicates a specific PGO item
entry in the registry database. The
sec_rgy_pgo_get_next routine returns the PGO item
indicated by item_cursor, and advances the cursor to
point to the next item in the database. When the end
of the list of entries is reached, the routine returns
the value sec_rgy_no_more_entries in the status
parameter. Use sec_rgy_cursor_reset to reset the
cursor.
Output
pgo_item A pointer to a sec_rgy_pgo_item_t structure to receive
the data for the returned PGO item. The data in this
structure includes the PGO item's name, UUID, UNIX
number (if any), and administrative data, such as
whether the item, if a principal, has a concurrent
group set. The data is as it is found in the registry,
for that UNIX number, even though some of the fields
may have been overridden locally.
name A pointer to a sec_rgy_name_t character string that
contains the returned name for the PGO item. This
string may contain a local override value if the
supplied UNIX number is found in the passwd_override or
group_override file.
overridden A pointer to a boolean32 value that indicates whether
the supplied UNIX number has an entry in the local
override file (passwd_override or group_override).
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns one of the following errors:
sec_rgy_no_more_entries The cursor is at the end
of the list of PGO items.
sec_rgy_object_not_found The specified PGO item
was not found.
sec_rgy_server_unavailable The DCE Registry Server
is unavailable.
Usage
The sec_rgy_pgo_get_by_eff_unix_num routine returns the name and data
for a PGO item. The desired item is identified by its type (domain)
and its UNIX number.
This routine is similar to the sec_rgy_pgo_get_by_unix_num routine.
The difference between the routines is that
sec_rgy_pgo_get_by_eff_unix_num first searches the local override
files for the respective name_domain for a match with the supplied
UNIX number. If an override match is found, and an account or group
name is found in that entry, that name is used to obtain PGO data
from the registry and the value of the overridden parameter is set to
TRUE.
The item_cursor parameter specifies the starting point for the search
through the registry database. It provides an automatic place holder
in the database. The routine automatically updates this variable to
point to the next PGO item after the returned item. The returned
cursor location can be supplied in a subsequent database access call
that also uses a PGO item cursor.
Permissions Required
The sec_rgy_pgo_get_by_eff_unix_num routine requires the read (r)
permission on the PGO item to be viewed.
Notes
There are several different types of cursors used in the registry
Application Programmer Interface (API). Some cursors point to PGO
items, others point to members in a membership list, and others point
to account data. Do not use a cursor for one type of object in a
routine expecting another type of object. For example, you cannot use
the same cursor on a call to sec_rgy_acct_get_projlist and
sec_rgy_pgo_get_next. The behavior in this case is undefined.
Furthermore, cursors are specific to a server. A cursor pointing
into one replica of the registry database is useless as a pointer
into another replica.
Use sec_rgy_cursor_reset to renew a cursor for use with another
routine or for another server.
Related Information
Routines: sec_rgy_pgo_add
sec_rgy_pgo_get_by_id
sec_rgy_pgo_get_by_name
sec_rgy_pgo_get_by_unix_num
sec_rgy_pgo_get_next
sec_rgy_pgo_id_to_name
sec_rgy_pgo_id_to_unix_num
sec_rgy_pgo_name_to_id
sec_rgy_pgo_unix_num_to_id
sec_rgy_cursor_reset
Files:
/usr/include/dce/pgo.idl - The idl file from which dce/pgo.h was
derived.
group_override - The local group override file.
passwd_override - The local password override file.
ΓòÉΓòÉΓòÉ 8.9.25. sec_rgy_pgo_get_by_id ΓòÉΓòÉΓòÉ
Purpose
Returns the name and data for a principal, group, or organization
(PGO) item identified by its UUID.
Library
\lib\dceos2.lib
Format
#include <dce/pgo.h>
void sec_rgy_pgo_get_by_id(
sec_rgy_handle_t context,
sec_rgy_domain_t name_domain,
sec_rgy_name_t scope,
uuid_t *item_id,
boolean32 allow_aliases,
sec_rgy_cursor_t *item_cursor,
sec_rgy_pgo_item_t *pgo_item,
sec_rgy_name_t name,
error_status_t *status);
Parameters
Input
context An opaque handle bound to a registry server. Use
sec_rgy_site_open to acquire a bound handle.
name_domain This parameter identifies the type of the PGO item
identified by the given name. The valid values are:
sec_rgy_domain_person The UUID identifies a
principal.
sec_rgy_domain_group The UUID identifies a group.
sec_rgy_domain_org The UUID identifies an
organization.
scope A character string (type sec_rgy_name_t) that contains
the scope of the desired search. The registry database
is designed to accommodate a tree-structured name
hierarchy. The scope of a search is the name of the
branch where the search takes place. For example, all
names in a registry may start with \alpha, and be
divided further into \beta or \gamma. To search only
the part of the database under \beta, the scope of the
search would be \alpha\beta, and any resulting PGO
items would have names beginning with this string. Note
that these naming conventions do not need to have
anything to do with group or organization PGO item
membership lists.
item_id A pointer to the uuid_t parameter that contains the
universal unique identifier (UUID) of the desired PGO
item.
allow_aliases A boolean32 value that indicates whether to search for
a primary PGO item, or whether the search can be
satisfied with an alias. If TRUE, the routine returns
the next entry found for the PGO item. If FALSE, the
routine returns only the primary entry.
Input/Output
item_cursor An opaque pointer that indicates a specific PGO item
entry in the registry database. The
sec_rgy_pgo_get_by_id routine returns the PGO item
indicated by item_cursor, and advances the cursor to
point to the next item in the database. When the end of
the list of entries is reached, the routine returns
sec_rgy_no_more_entries in the status parameter. Use
sec_rgy_cursor_reset to reset the cursor.
Output
pgo_item A pointer to a sec_rgy_pgo_item_t structure to receive
the data for the returned PGO item. The data in this
structure includes the PGO item's name, UUID, UNIX
number (if any), and administrative data, such as
whether the item, if a principal, has a concurrent
group set.
name A pointer to a sec_rgy_name_t character string that
contains the returned name for the PGO item.
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns the following errors:
sec_rgy_no_more_entries The cursor is at the end
of the list of PGO items.
sec_rgy_object_not_found The specified PGO item
was not found.
sec_rgy_server_unavailable The DCE Registry Server
is unavailable.
Usage
The sec_rgy_pgo_get_by_id routine returns the name and data for a PGO
item. The desired item is identified by its type (domain) and its
UUID.
The item_cursor specifies the starting point for the search through
the registry database. It provides an automatic place holder in the
database. The routine automatically updates this parameter to point
to the next PGO item after the returned item. The returned cursor
location can be supplied on a subsequent database access call that
also uses a PGO item cursor.
Permissions Required
The sec_rgy_pgo_get_by_id routine requires the read (r) permission on
the PGO item to be viewed.
Notes
There are several different types of cursors used in the Registry
Application Programmer Interface. Some cursors point to PGO items,
others point to members in a membership list, and others point to
account data. Do not use a cursor for one type of object in a call
expecting another type of object. For example, you cannot use the
same cursor on a call to sec_rgy_acct_get_projlist and
sec_rgy_pgo_get_next. The behavior in this case is undefined.
Use sec_rgy_cursor_reset to renew a cursor for use with another call
or for another server.
Related Information
Routines: sec_rgy_pgo_add
sec_rgy_pgo_get_by_name
sec_rgy_pgo_get_by_unix_num
sec_rgy_pgo_get_next
sec_rgy_pgo_id_to_name
sec_rgy_pgo_id_to_unix_num
sec_rgy_pgo_name_to_id
sec_rgy_pgo_unix_num_to_id
sec_rgy_site_open
sec_rgy_cursor_reset
ΓòÉΓòÉΓòÉ 8.9.26. sec_rgy_pgo_get_by_name ΓòÉΓòÉΓòÉ
Purpose
Returns the data for a named principal, group, or organization (PGO)
item.
Library
\lib\dceos2.lib
Format
#include <dce/pgo.h>
void sec_rgy_pgo_get_by_name(
sec_rgy_handle_t context,
sec_rgy_domain_t name_domain,
sec_rgy_name_t pgo_name,
sec_rgy_cursor_t *item_cursor,
sec_rgy_pgo_item_t *pgo_item,
error_status_t *status);
Parameters
Input
context An opaque handle bound to a registry server. Use
sec_rgy_site_open to acquire a bound handle.
name_domain This parameter identifies the type of the PGO item
identified by the given name. The valid values are:
sec_rgy_domain_person The name identifies a
principal.
sec_rgy_domain_group The name identifies a group.
sec_rgy_domain_org The name identifies an
organization.
pgo_name A character string (type sec_rgy_name_t) that contains
the name of the principal, group, or organization for
which to search.
Output
item_cursor An opaque pointer that indicates a specific PGO item
entry in the registry database. The
sec_rgy_pgo_get_next routine returns the PGO item entry
indicated by item_cursor, and advances the cursor to
the point to the next item in the database. When the
end of the list of entries is reached, the routine
returns sec_rgy_no_more_entries in the status
parameter. Use sec_rgy_cursor_reset to reset the
cursor.
pgo_item A pointer to a sec_rgy_pgo_item_t structure to receive
the data for the returned PGO item. The data in this
structure includes the PGO item's name, UUID, UNIX
number (if any), and administrative data, such as
whether the item, if a principal, has a concurrent
group set.
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns one of the following errors:
sec_rgy_no_more_entries The cursor is at the end
of the list of PGO items.
sec_rgy_object_not_found The specified PGO item
was not found.
sec_rgy_server_unavailable The DCE Registry Server
is unavailable.
Usage
The sec_rgy_pgo_get_by_name routine returns the data for a named PGO
item from the registry database. The desired item is identified by
its type (name_domain) and name.
The item_cursor parameter specifies the starting point for the search
through the registry database. It provides an automatic place holder
in the database. The routine automatically updates this parameter to
point to the next PGO item after the returned item. The returned
cursor location can be supplied on a subsequent database access call
that also uses a PGO item cursor.
Permissions Required
The sec_rgy_pgo_get_by_name routine requires the read (r) permission
on the PGO item to be viewed.
Notes
There are several different types of cursors used in the Registry
Application Programmer Interface. Some cursors point to PGO items,
others point to members in a membership list, and others point to
account data. Do not use a cursor for one type of object in a call
expecting another type of object. For example, you cannot use the
same cursor on a call to sec_rgy_acct_get_projlist and
sec_rgy_pgo_get_next. The behavior in this case is undefined.
Use sec_rgy_cursor_reset to renew a cursor for use with another call
or for another server.
Related Information
Routines: sec_rgy_pgo_add
sec_rgy_pgo_get_by_id
sec_rgy_pgo_get_by_unix_num
sec_rgy_pgo_get_next
sec_rgy_pgo_id_to_name
sec_rgy_pgo_id_to_unix_num
sec_rgy_pgo_name_to_id
sec_rgy_pgo_unix_num_to_id
sec_rgy_site_open
sec_rgy_cursor_reset
ΓòÉΓòÉΓòÉ 8.9.27. sec_rgy_pgo_get_by_unix_num ΓòÉΓòÉΓòÉ
Purpose
Returns the name and data for a PGO item identified by its UNIX ID.
Library
\lib\dceos2.lib
Format
#include <dce/pgo.h>
void sec_rgy_pgo_get_by_unix_num(
sec_rgy_handle_t context,
sec_rgy_domain_t name_domain,
sec_rgy_name_t scope,
signed32 unix_id,
boolean32 allow_aliases,
sec_rgy_cursor_t *item_cursor,
sec_rgy_pgo_item_t *pgo_item,
sec_rgy_name_t name,
error_status_t *status);
Parameters
Input
context An opaque handle bound to a registry server. Use
sec_rgy_site_open to acquire a bound handle.
name_domain This parameter identifies the type of the PGO item
identified by the given name. The valid values are:
sec_rgy_domain_person The UNIX number identifies a
principal.
sec_rgy_domain_group The UNIX number identifies a
group.
sec_rgy_domain_org The UNIX number identifies an
organization.
scope A character string (type sec_rgy_name_t) that contains
the scope of the desired search. The registry database
is designed to accommodate a tree-structured name
hierarchy. The scope of a search is the name of the
branch where the search takes place. For example, all
names in a registry may start with \alpha, and be
divided further into \beta or \gamma. To search only
the part of the database under \beta, the scope of the
search would be \alpha\beta, and any resulting PGO
items would have names beginning with this string.
Note: These naming conventions do not need to have
anything to do with group or organization PGO
item membership lists.
unix_id The UNIX number of the desired registry PGO item.
allow_aliases A boolean32 value that indicates whether to search for
a primary PGO item, or whether the search can be
satisfied with an alias. If TRUE, the routine returns
the next entry found for the PGO item. If FALSE, the
routine returns the primary entry only.
Input/Output
item_cursor An opaque pointer that indicates a specific PGO item
entry in the registry database. The
sec_rgy_pgo_get_by_unix_num routine returns the PGO
item indicated by item_cursor, and advances the cursor
to point to the next item in the database. When the
end of the list of entries is reached, the routine
returns sec_rgy_no_more_entries in the status
parameter. Use sec_rgy_cursor_reset to reset the
cursor.
Output
pgo_item A pointer to a sec_rgy_pgo_item_t structure to receive
the data for the returned PGO item. The data in this
structure includes the PGO item's name, UUID, UNIX
number (if any), and administrative data, such as
whether the item, if a principal, can have a concurrent
group set.
name A pointer to a sec_rgy_name_t character string that
contains the returned name for the PGO item.
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns one of the following errors:
sec_rgy_no_more_entries The cursor is at the end
of the list of PGO items.
sec_rgy_object_not_found The specified PGO item
was not found.
sec_rgy_server_unavailable The DCE Registry Server
is unavailable.
Usage
The sec_rgy_pgo_get_by_unix_num routine returns the name and data for
a PGO item. The desired item is identified by its type (domain) and
its UNIX number.
The item_cursor parameter specifies the starting point for the search
through the registry database. It provides an automatic place holder
in the database. The routine automatically updates this parameter to
point to the next PGO item after the returned item. The returned
cursor location can be supplied on a subsequent database access call
that also uses a PGO item cursor.
Permissions Required
The sec_rgy_pgo_get_by_unix_num routine requires the read (r)
permission on the PGO item to be viewed.
Notes
There are several different types of cursors used in the Registry
Application Programmer Interface. Some cursors point to PGO items,
others point to members in a membership list, and others point to
account data. Do not use a cursor for one type of object in a call
expecting another type of object. For example, you cannot use the
same cursor on a call to sec_rgy_acct_get_projlist and
sec_rgy_pgo_get_next. The behavior in this case is undefined.
Use sec_rgy_cursor_reset to renew a cursor for use with another call
or for another server.
Related Information
Routines: sec_rgy_pgo_add
sec_rgy_pgo_get_by_id
sec_rgy_pgo_get_by_name
sec_rgy_pgo_get_next
sec_rgy_pgo_id_to_name
sec_rgy_pgo_name_to_id
sec_rgy_cursor_reset
ΓòÉΓòÉΓòÉ 8.9.28. sec_rgy_pgo_get_members ΓòÉΓòÉΓòÉ
Purpose
Returns the membership list for a specified group or organization or
returns the set of groups in which the specified principal is a
member.
Library
\lib\dceos2.lib
Format
#include <dce/pgo.h>
void sec_rgy_pgo_get_members(
sec_rgy_handle_t context,
sec_rgy_domain_t name_domain,
sec_rgy_name_t go_name,
sec_rgy_cursor_t *member_cursor,
signed32 max_members,
sec_rgy_member_t member_list[],
signed32 *number_supplied,
signed32 *number_members,
error_status_t *status);
Parameters
Input
context An opaque handle bound to a secd server. Use
sec_rgy_site_open to acquire a bound handle.
name_domain This parameter specifies whether go_name identifies a
principal, group, or organization. The valid values
are:
sec_rgy_domain_group The go_name parameter
identifies a group.
sec_rgy_domain_org The go_name parameter
identifies an organization.
sec_rgy_domain_person The go_name parameter
identifies a principal.
go_name A character string (type sec_rgy_name_t) that contains
the name of a principal, group, or organization. If
go_name is the name of a group or organization, the
routine returns the group's or organization's member
list. If go_name is the name of a principal, the
routine returns a list of all groups in which the
principal is a member. (Contrast this with the
sec_rgy_acct_get_projlist routine, which returns only
those groups in which the principal is a member and
that also have been marked to be included in the
principal's project list.)
max_members A signed32 parameter that contains the allocated
dimension of the member_list array. This is the
maximum number of members or groups that can be
returned by a single call.
Input/Output
member_cursor An opaque pointer to a specific entry in the membership
list or list of groups. The returned list begins with
the entry specified by member_cursor. Upon return, the
cursor points to the next entry after the last one
returned. If there are no more entries, the routine
returns the value sec_rgy_no_more_entries in the status
parameter. Use sec_rgy_cursor_reset to reset the cursor
to the beginning of the list.
Output
member_list An array of character strings to receive the returned
member or group names. The size allocated for the array
is given by max_members. If this value is less than the
total number of members or group names, multiple calls
must be made to return all of the members or groups.
number_supplied A pointer to a signed32 parameter to receive the
number of members or groups actually returned in
member_list.
number_members A pointer to a signed32 parameter to receive the total
number of members or groups. If this number is greater
than number_supplied, multiple calls to
sec_rgy_pgo_get_members are necessary. Use the
member_cursor parameter to coordinate successive calls.
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns one of the following errors:
sec_rgy_object_not_found The specified group,
organization, or principal
could not be found.
sec_rgy_no_more_entries The cursor points to the
end of the membership list
for a group or organization
or to the end of the list of
groups for a principal.
sec_rgy_server_unavailable The DCE Registry Server
is unavailable.
sec_rgy_bad_data The old_login_name or the
new_login_name is NULL.
Usage
The sec_rgy_pgo_get_members routine returns a list of the members in
the specified group or organization, or a list of groups in which a
specified principal is a member.
The member_cursor parameter specifies the starting point for the
search through the registry database. It provides an automatic place
holder in the database. The routine automatically updates
member_cursor to point to the next member or group (if any) after the
returned list. If not all of the members or groups are returned, the
updated cursor can be supplied on successive calls to return the
remainder of the list.
Permissions Required
The sec_rgy_pgo_get_members routine requires the read (r) permission
on the principal, group, or organization object specified by go_name.
Notes
There are several different types of cursors used in the Registry
Application Programmer Interface. Some cursors point to PGO items,
others point to members in a membership list, and others point to
account data. Do not use a cursor for one type of object in a call
expecting another type of object. For example, you cannot use the
same cursor on a call to sec_rgy_acct_get_projlist and
sec_rgy_pgo_get_next. The behavior in this case is undefined.
Use sec_rgy_cursor_reset to renew a cursor for use with another call
or for another server.
Related Information
Routines: sec_rgy_pgo_add_member
sec_rgy_cursor_reset
sec_rgy_pgo_is_member
sec_rgy_acct_get_projlist
ΓòÉΓòÉΓòÉ 8.9.29. sec_rgy_pgo_get_next ΓòÉΓòÉΓòÉ
Purpose
Returns the next principal, group, or organization (PGO) item in the
registry database.
Library
\lib\dceos2.lib
Format
#include <dce/pgo.h>
void sec_rgy_pgo_get_next(
sec_rgy_handle_t context,
sec_rgy_domain_t name_domain,
sec_rgy_name_t scope,
sec_rgy_cursor_t *item_cursor,
sec_rgy_pgo_item_t *pgo_item,
sec_rgy_name_t name,
error_status_t *status);
Parameters
Input
context An opaque handle bound to a registry server. Use
sec_rgy_site_open to acquire a bound handle.
name_domain This parameter identifies the type of the PGO item
identified by the given name. The valid values are:
sec_rgy_domain_person Returns the next principal
item.
sec_rgy_domain_group Returns the next group item.
sec_rgy_domain_org Returns the next organization
item.
scope A character string (type sec_rgy_name_t) containing the
scope of the desired search. The registry database is
designed to accommodate a tree-structured name
hierarchy. The scope of a search is the name of the
branch where the search takes place. For example, all
names in a registry may start with \alpha, and be
divided further into \beta or \gamma. To search only
the part of the database under \beta, the scope of the
search would be \alpha\beta, and any resulting PGO
items would have names beginning with this string.
Note: These naming conventions do not need to have
anything to do with group or organization PGO
item membership lists.
Input/Output
item_cursor An opaque pointer indicating a specific PGO item entry
in the registry database. The sec_rgy_pgo_get_next
routine returns the PGO item indicated by item_cursor,
and advances the cursor to point to the next item in
the database. When the end of the list of entries is
reached, the routine returns sec_rgy_no_more_entries in
the status parameter. Use sec_rgy_cursor_reset to reset
the cursor.
Output
pgo_item A pointer to a sec_rgy_pgo_item_t structure to receive
the data for the returned PGO item. The data in this
structure includes the PGO item's name, UUID, UNIX
number (if any), and administrative data, such as
whether the item, if a principal, may have a concurrent
group set.
name A pointer to a sec_rgy_name_t character string
containing the name of the returned PGO item.
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns one of the following errors:
sec_rgy_no_more_entries The cursor is at the end
of the list of PGO items.
sec_rgy_server_unavailable The DCE Registry Server
is unavailable.
Usage
The sec_rgy_pgo_get_next routine returns the data and name for the
person, group, or organization (PGO) item in the registry database
indicated by item_cursor. It also advances the cursor to point to
the next PGO item in the database. Successive calls to this routine
return all the PGO items in the database of the specified type (given
by name_domain), in storage order.
The PGO data consists of:
o The universal unique identifier (UUID) of the PGO item
o The UNIX number for the PGO item
o The quota for subaccounts
o The full name of the PGO item
o Flags indicating whether
- A principal item is an alias.
- The PGO item can be deleted.
- A principal item can have a concurrent group set.
- A group item can appear on a concurrent group set.
Permissions Required
The sec_rgy_pgo_get_next routine requires the read (r) permission on
the PGO item to be viewed.
Notes
There are several different types of cursors used in the Registry
Application Programmer Interface. Some cursors point to PGO items,
others point to members in a membership list, and others point to
account data. Do not use a cursor for one type of object in a call
expecting another type of object. For example, you cannot use the
same cursor on a call to sec_rgy_acct_get_projlist and
sec_rgy_pgo_get_next. The behavior in this case is undefined.
Use sec_rgy_cursor_reset to renew a cursor for use with another call
or for another server.
Related Information
Routines: sec_rgy_pgo_add
sec_rgy_cursor_reset
sec_rgy_pgo_get_by_id
sec_rgy_pgo_get_by_name
sec_rgy_pgo_get_by_unix_num
sec_rgy_pgo_id_to_unix_num
sec_rgy_pgo_unix_num_to_id
sec_rgy_site_open
ΓòÉΓòÉΓòÉ 8.9.30. sec_rgy_pgo_id_to_name ΓòÉΓòÉΓòÉ
Purpose
Returns the name for a principal, group, or organization (PGO) item
identified by its universal unique identifier (UUID).
Library
\lib\dceos2.lib
Format
#include <dce/pgo.h>
void sec_rgy_pgo_id_to_name(
sec_rgy_handle_t context,
sec_rgy_domain_t name_domain,
uuid_t *item_id,
sec_rgy_name_t pgo_name,
error_status_t *status);
Parameters
Input
context An opaque handle bound to a registry server. Use
sec_rgy_site_open to acquire a bound handle.
name_domain This parameter identifies the type of the PGO item
identified by the given name. The valid values are:
sec_rgy_domain_person The item_id parameter
identifies a principal.
sec_rgy_domain_group The item_id parameter
identifies a group.
sec_rgy_domain_org The item_id parameter
identifies an organization.
item_id A pointer to the uuid_t parameter containing the input
UUID.
Output
pgo_name A character string (type sec_rgy_name_t) containing the
name of the principal, group, or organization with the
input UUID.
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns one of the following errors:
sec_rgy_object_not_found No item with the
specified UUID could be
found.
sec_rgy_server_unavailable The DCE Registry Server
is unavailable.
Usage
The sec_rgy_pgo_id_to_name routine returns the name of the principal,
group, or organization (PGO) item having the specified UUID.
Permissions Required
The sec_rgy_pgo_id_to_name routine requires at least one permission
of any kind on the PGO item to be viewed.
Related Information
Routines: sec_rgy_pgo_add
sec_rgy_pgo_get_by_id
sec_rgy_pgo_get_by_name
sec_rgy_pgo_get_by_unix_num
sec_rgy_pgo_id_to_unix_num
sec_rgy_pgo_name_to_id
sec_rgy_pgo_unix_num_to_id
sec_rgy_site_open
ΓòÉΓòÉΓòÉ 8.9.31. sec_rgy_pgo_id_to_unix_num ΓòÉΓòÉΓòÉ
Purpose
Returns the UNIX number for a principal, group, or organization (PGO)
item identified by its universal unique identifier (UUID).
Library
\lib\dceos2.lib
Format
#include <dce/pgo.h>
void sec_rgy_pgo_id_to_unix_num(
sec_rgy_handle_t context,
sec_rgy_domain_t name_domain,
uuid_t *item_id,
signed32 *item_unix_id,
error_status_t *status);
Parameters
Input
context An opaque handle bound to a registry server. Use
sec_rgy_site_open to acquire a bound handle.
name_domain This parameter identifies the type of the PGO item
identified by the given name. The valid values are:
sec_rgy_domain_person The item_id parameter
identifies a principal.
sec_rgy_domain_group The item_id parameter
identifies a group.
sec_rgy_domain_org The item_id parameter
identifies an organization.
item_id A pointer to the uuid_t parameter containing the input
UUID.
Output
item_unix_id A pointer to the signed32 parameter to receive the
returned UNIX number for the PGO item.
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns one of the following errors:
sec_rgy_object_not_found No item with the
specified UUID could be
found.
sec_rgy_server_unavailable The DCE Registry Server
is unavailable.
Usage
The sec_rgy_pgo_id_to_unix_num routine returns the UNIX number for
the principal, group, or organization (PGO) item having the specified
UUID.
Related Information
Routines: sec_rgy_pgo_add
sec_rgy_pgo_get_by_id
sec_rgy_pgo_get_by_name
sec_rgy_pgo_get_by_unix_num
sec_rgy_pgo_id_to_name
sec_rgy_pgo_name_to_id
sec_rgy_pgo_unix_num_to_id
sec_rgy_site_open
ΓòÉΓòÉΓòÉ 8.9.32. sec_rgy_pgo_is_member ΓòÉΓòÉΓòÉ
Purpose
Checks group or organization membership.
Library
\lib\dceos2.lib
Format
#include <dce/pgo.h>
boolean32 sec_rgy_pgo_is_member(
sec_rgy_handle_t context,
sec_rgy_domain_t name_domain,
sec_rgy_name_t go_name,
sec_rgy_name_t person_name,
error_status_t *status);
Parameters
Input
context An opaque handle bound to a registry server. Use
sec_rgy_site_open to acquire a bound handle.
name_domain This parameter identifies the type of the principal,
group, or organization (PGO) item identified by the
given name. The valid values are:
sec_rgy_domain_group The go_name identifies a
group.
sec_rgy_domain_org The go_name identifies an
organization.
go_name A character string (type sec_rgy_name_t) containing the
name of the group or organization whose membership list
is in question.
person_name A character string (type sec_rgy_name_t) containing the
name of the principal whose membership in the group or
organization specified by go_name is in question.
Output
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns one of the following errors:
sec_rgy_object_not_found The named group or
organization was not
found.
sec_rgy_server_unavailable The DCE Registry Server
is unavailable.
Usage
The sec_rgy_pgo_is_member routine tests whether the specified
principal is a member of the named group or organization.
Permissions Required
The sec_rgy_pgo_is_member routine requires the test (t) permission on
the group or organization item specified by go_name.
Return Codes
The routine returns TRUE if the principal is a member of the named
group or organization. If the person is not a member, the routine
returns FALSE.
Related Information
Routines: sec_rgy_pgo_add_member
sec_rgy_pgo_get_members
sec_rgy_site_open
ΓòÉΓòÉΓòÉ 8.9.33. sec_rgy_pgo_name_to_id ΓòÉΓòÉΓòÉ
Purpose
Returns the universal unique identifier (UUID) for a named principal,
group, or organization (PGO) item.
Library
\lib\dceos2.lib
Format
#include <dce/pgo.h>
void sec_rgy_pgo_name_to_id(
sec_rgy_handle_t context,
sec_rgy_domain_t name_domain,
sec_rgy_name_t pgo_name,
uuid_t *item_id,
error_status_t *status);
Parameters
Input
context An opaque handle bound to a registry server. Use
sec_rgy_site_open to acquire a bound handle.
name_domain This parameter identifies the type of the PGO item
identified by the given name. The valid values are:
sec_rgy_domain_person The name identifies a
principal.
sec_rgy_domain_group The name identifies a group.
sec_rgy_domain_org The name identifies an
organization.
pgo_name A character string (type sec_rgy_name_t) containing the
name of the principal, group, or organization whose
UUID is sought.
Output
item_id A pointer to the uuid_t parameter containing the UUID
of the PGO item.
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns one of the following errors:
sec_rgy_object_not_found The specified PGO item
could not be found.
sec_rgy_server_unavailable The DCE Registry Server
is unavailable.
Usage
The sec_rgy_pgo_name_to_id routine returns the UUID associated with
the named PGO item.
Related Information
Routines: sec_rgy_pgo_add
sec_rgy_pgo_get_by_id
sec_rgy_pgo_get_by_name
sec_rgy_pgo_get_by_unix_num
sec_rgy_pgo_id_to_name
sec_rgy_pgo_id_to_unix_num
sec_rgy_pgo_unix_num_to_id
sec_rgy_site_open
ΓòÉΓòÉΓòÉ 8.9.34. sec_rgy_pgo_name_to_unix_num ΓòÉΓòÉΓòÉ
Purpose
Returns the UNIX number for a principal, group, or organization (PGO)
item identified by its name.
Library
\lib\dceos2.lib
Format
#include <dce/pgo.h>
void sec_rgy_pgo_name_to_unix_num(
sec_rgy_handle_t context,
sec_rgy_domain_t name_domain,
sec_rgy_name_t pgo_name,
signed32 *item__id,
error_status_t *status);
Parameters
Input
context An opaque handle bound to a registry server. Use
sec_rgy_site_open to acquire a bound handle.
name_domain This parameter identifies the type of the PGO item
identified by the given name. The valid values are:
sec_rgy_domain_person The pgo_name parameter
identifies a principal.
sec_rgy_domain_group The pgo_name parameter
identifies a group.
sec_rgy_domain_org The pgo_name parameter
identifies an organization.
pgo_name A character string containing the name of the PGO item
in question.
Output
item_id A pointer to the signed32 parameter to receive the
returned UNIX number for the PGO item.
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns one of the following errors:
sec_rgy_object_not_found No item with the
specified UUID could be
found.
sec_rgy_server_unavailable The DCE Registry Server
is unavailable.
Usage
The sec_rgy_pgo_name_to_unix_num routine returns the UNIX number for
the person, group, or organization (PGO) item that has the specified
name.
Related Information
Routines: sec_rgy_pgo_add
sec_rgy_pgo_get_by_id
sec_rgy_pgo_get_by_name
sec_rgy_pgo_get_by_unix_num
sec_rgy_pgo_id_to_name
sec_rgy_pgo_name_to_id
sec_rgy_pgo_unix_num_to_id
sec_rgy_site_open
ΓòÉΓòÉΓòÉ 8.9.35. sec_rgy_pgo_rename ΓòÉΓòÉΓòÉ
Purpose
Changes the name of a principal, group, or organization (PGO) item in
the registry database.
Library
\lib\dceos2.lib
Format
#include <dce/pgo.h>
void sec_rgy_pgo_rename(
sec_rgy_handle_t context,
sec_rgy_domain_t name_domain,
sec_rgy_name_t old_name,
sec_rgy_name_t new_name,
error_status_t *status);
Parameters
Input
context An opaque handle bound to a registry server. Use
sec_rgy_site_open to acquire a bound handle.
name_domain This parameter identifies the type of the PGO item
identified by the given name. The valid values are:
sec_rgy_domain_person The name identifies a
principal.
sec_rgy_domain_group The name identifies a group.
sec_rgy_domain_org The name identifies an
organization.
old_name A pointer to a sec_rgy_name_t character string
containing the existing name of the PGO item.
new_name A pointer to a sec_rgy_name_t character string
containing the new name for the PGO item.
Output
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns one of the following errors:
sec_rgy_not_authorized The client program is not
authorized to change the name
of the specified PGO item.
sec_rgy_object_not_found The registry server could
not find the specified PGO
item.
sec_rgy_server_unavailable The DCE Registry Server
is unavailable.
Usage
The sec_rgy_pgo_rename routine renames a person, group, or
organization (PGO) item in the registry database.
Permissions Required
If the sec_rgy_pgo_rename routine is performing a rename within a
directory, it requires the name (n) permission on the old name of the
PGO item. If the routine is performing a move between directories, it
requires the following permissions:
o The delete (d) permission on the parent directory that contains
the PGO item
o The name (n) permission on the old name of the PGO item
o The insert (i) permission on the parent directory in which the
PGO item is to be added under the new name
Related Information
Routines: sec_rgy_pgo_add
sec_rgy_pgo_replace
sec_rgy_site_open
ΓòÉΓòÉΓòÉ 8.9.36. sec_rgy_pgo_replace ΓòÉΓòÉΓòÉ
Purpose
Replaces the data in an existing principal, group, or organization
(PGO) item.
Library
\lib\dceos2.lib
Format
#include <dce/pgo.h>
void sec_rgy_pgo_replace(
sec_rgy_handle_t context,
sec_rgy_domain_t name_domain,
sec_rgy_name_t pgo_name,
sec_rgy_pgo_item_t *item,
error_status_t *status);
Parameters
Input
context An opaque handle bound to a registry server. Use
sec_rgy_site_open to acquire a bound handle.
name_domain This parameter identifies the type of the PGO item
identified by the given name. The valid values are:
sec_rgy_domain_person The name identifies a
principal.
sec_rgy_domain_group The name identifies a group.
sec_rgy_domain_org The name identifies an
organization.
pgo_name A character string (type sec_rgy_name_t) containing the
name of the principal, group, or organization whose
data is to be replaced.
item A pointer to a sec_rgy_pgo_item_t structure containing
the new data for the PGO item. The data in this
structure includes the PGO item's name, UUID, UNIX
number (if any), and administrative data, such as
whether the item, if a principal, may have a concurrent
group set.
Output
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns one of the following errors:
sec_rgy_not_authorized The client program is not
authorized to replace the
specified PGO item.
sec_rgy_object_not_found No PGO item was found
with the given name.
sec_rgy_unix_id_changed The UNIX number of the PGO
item was changed.
sec_rgy_server_unavailable The DCE Registry Server
is unavailable.
Usage
The sec_rgy_pgo_replace routine replaces the data associated with a
principal, group, or organization (PGO) item in the registry
database.
The UNIX ID and UUID of a PGO item cannot be replaced. To change the
UNIX ID or UUID, the existing PGO item must be deleted and a new PGO
item added in its place. The one exception to this rule is that the
UNIX ID can be replaced in the PGO item for a cell principal. The
reason for this exception is that the UUID for a cell principal does
not contain an embedded UNIX ID.
Permissions Required
The sec_rgy_pgo_replace routine requires at least one of the
following permissions:
o The mgmt_info (m) permission on the PGO item, if quota or flags
is being set.
o The fullname (f) permission on the PGO item, if fullname is
being set.
Related Information
Routines: sec_rgy_pgo_add
sec_rgy_pgo_delete
sec_rgy_pgo_rename
sec_rgy_site_open
ΓòÉΓòÉΓòÉ 8.9.37. sec_rgy_pgo_unix_num_to_id ΓòÉΓòÉΓòÉ
Purpose
Returns the universal unique identifier (UUID) for a principal,
group, or organization (PGO) item identified by its UNIX number.
Library
\lib\dceos2.lib
Format
#include <dce/pgo.h>
void sec_rgy_pgo_unix_num_to_id(
sec_rgy_handle_t context,
sec_rgy_domain_t name_domain,
signed32 item_unix_id,
uuid_t *item_id,
error_status_t *status);
Parameters
Input
context An opaque handle bound to a registry server. Use
sec_rgy_site_open to acquire a bound handle.
name_domain This parameter identifies the type of the PGO item
identified by the given name. The valid values are:
sec_rgy_domain_person The item_unix_id parameter
identifies a principal.
sec_rgy_domain_group The item_unix_id parameter
identifies a group.
sec_rgy_domain_org The item_unix_id parameter
identifies an organization.
item_unix_id The signed32 parameter containing the UNIX number for
the PGO item.
Output
item_id A pointer to the uuid_t parameter containing the UUID
of the resulting PGO item.
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns one of the following errors:
sec_rgy_object_not_found No item with the
specified UNIX number could
be found.
sec_rgy_server_unavailable The DCE Registry Server
is unavailable.
Usage
The sec_rgy_pgo_unix_num_to_id routine returns the UUID for a PGO
item that has the specified UNIX number.
Related Information
Routines: sec_rgy_pgo_add
sec_rgy_pgo_get_by_id
sec_rgy_pgo_get_by_name
sec_rgy_pgo_get_by_unix_num
sec_rgy_pgo_id_to_name
sec_rgy_pgo_id_to_unix_num
sec_rgy_pgo_name_to_id
sec_rgy_site_open
ΓòÉΓòÉΓòÉ 8.9.38. sec_rgy_pgo_unix_num_to_name ΓòÉΓòÉΓòÉ
Purpose
Returns the name for a principal, group, or organization (PGO) item
identified by its UNIX number.
Library
\lib\dceos2.lib
Format
#include <dce/pgo.h>
void sec_rgy_pgo_unix_num_to_name(
sec_rgy_handle_t context,
sec_rgy_domain_t name_domain,
signed32 item_id,
sec_rgy_name_t pgo_name,
error_status_t *status);
Parameters
Input
context An opaque handle bound to a registry server. Use
sec_rgy_site_open to acquire a bound handle.
name_domain The type of the PGO item identified by item_id. Valid
values are:
sec_rgy_domain_person The item_id parameter
identifies a principal.
sec_rgy_domain_group The item_id parameter
identifies a group.
sec_rgy_domain_org The item_id parameter
identifies an organization.
item_id The UNIX number for the PGO item.
Output
pgo_name A character string that contains the name of the PGO
item in question.
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns one of the following errors:
sec_rgy_object_not_found No item with the
specified UNIX number could
be found.
sec_rgy_server_unavailable The DCE Registry Server
is unavailable.
Usage
The sec_rgy_pgo_unix_num_to_name routine returns the name for a PGO
item that has the specified UNIX number.
Permissions Required
The sec_rgy_pgo_unix_num_to_name routine requires at least one
permission of any kind on the PGO item identified by item_id.
Related Information
Routines: sec_rgy_pgo_add
sec_rgy_pgo_get_by_id
sec_rgy_pgo_get_by_name
sec_rgy_pgo_get_by_unix_num
sec_rgy_pgo_id_to_name
sec_rgy_pgo_id_to_unix_num
sec_rgy_pgo_name_to_id
sec_rgy_site_open
ΓòÉΓòÉΓòÉ 8.9.39. sec_rgy_plcy_get_effective ΓòÉΓòÉΓòÉ
Purpose
Returns the effective policy for an organization.
Library
\lib\dceos2.lib
Format
#include <dce/policy.h>
void sec_rgy_plcy_get_effective(
sec_rgy_handle_t context,
sec_rgy_name_t organization,
sec_rgy_plcy_t *policy_data,
error_status_t *status);
Parameters
Input
context An opaque handle bound to a registry server. Use
sec_rgy_site_open to acquire a bound handle.
organization A character string (type sec_rgy_name_t) that contains
the name of the organization for which the policy data
is to be returned. If this string is empty, the routine
returns the registry's policy data.
Output
policy_data A pointer to the sec_rgy_plcy_t structure to receive
the authentication policy. This structure contains the
minimum length of a user's password, the lifetime of a
password, the expiration date of a password, the
lifetime of the entire account, and some flags
describing limitations on the password spelling.
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns one of the following errors:
sec_rgy_object_not_found The registry server could
not find the specified
organization.
sec_rgy_server_unavailable The DCE Registry Server
is unavailable.
Usage
The sec_rgy_plcy_get_effective routine returns the effective policy
for the specified organization.
The effective policy data is the most restrictive combination of the
registry and the organization policies.
The policy data consists of:
o The password expiration date. This is the date when account
passwords expire.
o The minimum length allowed for account passwords.
o The period of time (life span) account passwords are valid.
o The period of time (life span) accounts are valid.
o Flags indicating whether account passwords can consist entirely
of spaces or entirely of alphanumeric characters.
Permissions Required
The sec_rgy_plcy_get_effective routine requires the r (read)
permission on the policy object from which the data is to be
returned. If an organization is specified, the routine also requires
the r (read) permission on the organization.
Notes
If no organization is specified, the routine returns the registry's
policy data. To return the effective policy, an organization must be
specified. This is because the routine compares the registry's policy
data with that of the organization to determine which is more
restrictive.
Related Information
Routines:
sec_rgy_plcy_get_info
sec_rgy_plcy_set_info
sec_rgy_site_open
ΓòÉΓòÉΓòÉ 8.9.40. sec_rgy_plcy_get_info ΓòÉΓòÉΓòÉ
Purpose
Returns the policy for an organization.
Library
\lib\dceos2.lib
Format
#include <dce/policy.h>
void sec_rgy_plcy_get_info(
sec_rgy_handle_t context,
sec_rgy_name_t organization,
sec_rgy_plcy_t *policy_data,
error_status_t *status);
Parameters
Input
context An opaque handle bound to a registry server. Use
sec_rgy_site_open to acquire a bound handle.
organization A character string (type sec_rgy_name_t) that contains
the name of the organization for which the policy data
is to be returned. If this string is empty, the routine
returns the registry's policy data.
Output
policy_data A pointer to the sec_rgy_plcy_t structure to receive
the authentication policy. This structure contains the
minimum length of a user's password, the lifetime of a
password, the expiration date of a password, the
lifetime of the entire account, and some flags
describing limitations on the password spelling.
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns one of the following errors:
sec_rgy_object_not_found Either the registry
server could not find the
specified organization, or
the organization exists but
does not have its own
policy.
sec_rgy_server_unavailable The DCE Registry Server
is unavailable.
Usage
The sec_rgy_plcy_get_info routine returns the policy data for the
specified organization. If no organization is specified, the
registry's policy data is returned.
The policy data consists of:
o The password expiration date. This is the date when account
passwords expire.
o The minimum length allowed for account passwords.
o The period of time (life span) account passwords are valid.
o The period of time (life span) accounts are valid.
o Flags indicating whether account passwords can consist entirely
of spaces or entirely of alphanumeric characters.
Permissions Required
The sec_rgy_plcy_get_info routine requires the read (r) permission on
the policy object or organization from which the data is to be
returned.
Notes
The returned policy may not be in effect if the overriding registry
authorization policy is more restrictive. See
sec_rgy_auth_plcy_get_effective.
Related Information
Routines:
sec_rgy_plcy_get_effective
sec_rgy_plcy_set_info
sec_rgy_site_open
ΓòÉΓòÉΓòÉ 8.9.41. sec_rgy_plcy_get_override_info ΓòÉΓòÉΓòÉ
Purpose
Collects the information to be overridden from the policy.
Format
#include <dce\policy.h>
void sec_rgy_plcy_get_override_info(
sec_rgy_handle_t context,
sec_rgy_name_t policy_category,
boolean32 *exclude_passwd,
boolean32 *root_passwd,
boolean32 *other_passwd,
boolean32 *custom_data,
error_status_t *status);
Parameters
Input
context An opaque handle bound to a registry server. Use
sec_rgy_site_open to acquire a bound handle.
policy_category A charcater string containing the name of the
category of the policy data.
Input
exclude_passwd A pointer to the exclude password.
root_passwd A pointer to the root password.
other_passwd A pointer to other passwords.
custom_data A pointer to custom data.
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns an error.
Usage
The sec_rgy_plcy_get_override_info routine collects information from
the policy that will be overridden if their respective flags are set
to true.
Related Information
Routines: sec_rgy_plcy_set_override_info
sec_rgy_site_open
Files:
\usr\include\dce\policy.idl - The idl file from which dce\policy.h
was derived.
ΓòÉΓòÉΓòÉ 8.9.42. sec_rgy_plcy_set_info ΓòÉΓòÉΓòÉ
Purpose
Sets the policy for an organization.
Library
\lib\dceos2.lib
Format
#include <dce/policy.h>
void sec_rgy_plcy_set_info(
sec_rgy_handle_t context,
sec_rgy_name_t organization,
sec_rgy_plcy_t *policy_data,
error_status_t *status);
Parameters
Input
context An opaque handle bound to a registry server. Use
sec_rgy_site_open to acquire a bound handle.
organization A character string (type sec_rgy_name_t) that contains
the name of the organization for which the policy data
is to be returned. If this string is empty, the routine
sets the registry's policy data.
policy_data A pointer to the sec_rgy_plcy_t structure that contains
the authentication policy. This structure contains the
minimum length of a user's password, the lifetime of a
password, the expiration date of a password, the
lifetime of the entire account, and some flags
describing limitations on the password spelling.
Output
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns one of the following errors:
sec_rgy_not_authorized The user is not authorized
to perform this operation.
sec_rgy_object_not_found The registry server could
not find the specified
organization.
sec_rgy_server_unavailable The DCE Registry Server
is unavailable.
Usage
The sec_rgy_plcy_set_info routine sets the authentication policy for
a specified organization. If no organization is specified, the
registry's policy data is set.
Policy data can be returned or set for individual organizations and
for the registry as a whole.
Permissions Required
The sec_rgy_plcy_set_info routine requires the m (mgmt_info)
permission on the policy object or organization for which the data is
to be set.
Notes
The policy set on an account can be less restrictive than the policy
set for the registry as a whole. In this case, the changes in policy
have no effect, because the effective policy is the most restrictive
combination of the organization and registry authentication policies.
See sec_rgy_auth_plcy_get_effective.
Related Information
Routines: sec_rgy_plcy_get_effective
sec_rgy_plcy_get_info
sec_rgy_site_open
ΓòÉΓòÉΓòÉ 8.9.43. sec_rgy_plcy_set_override_info ΓòÉΓòÉΓòÉ
Purpose
Writes the information collected by sec_rgy_plcy_get_override_info.
Format
#include <dce\policy.h>
void sec_rgy_plcy_set_override_info(
sec_rgy_handle_t context,
sec_rgy_name_t policy_category,
boolean32 *exclude_passwd,
boolean32 *root_passwd,
boolean32 *other_passwd,
boolean32 *custom_data,
error_status_t *status);
Parameters
Input
context An opaque handle bound to a registry server. Use
sec_rgy_site_open to acquire a bound handle.
policy_category A character string containing the name of the
category of the policy data.
exclude_passwd A pointer to the exclude password.
root_passwd A pointer to the root password.
other_passwd A pointer to other passwords.
custom_data A pointer to custom data.
Output
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns an error.
Usage
The sec_rgy_plcy_set_override_info routine writes the information
collected by the sec_rgy_plcy_get_override_info routine.
Related Information
Routines:
sec_rgy_plcy_get_override_info
Files:
\usr\include\dce\policy.idl - The idl file from which dce\policy.h
was derived.
ΓòÉΓòÉΓòÉ 8.9.44. sec_rgy_properties_get_info ΓòÉΓòÉΓòÉ
Purpose
Returns registry properties.
Library
\lib\dceos2.lib
Format
#include <dce/policy.h>
void sec_rgy_properties_get_info(
sec_rgy_handle_t context,
sec_rgy_properties_t *properties,
error_status_t *status);
Parameters
Input
context An opaque handle bound to a registry server. Use
sec_rgy_site_open to acquire a bound handle.
Output
properties A pointer to a sec_rgy_properties_t structure to
receive the returned property information. Registry
property information contains information such as the
default and minimum lifetime and other restrictions on
privilege attribute certificates.
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns sec_rgy_server_unavailable, which
indicates that the DCE Registry Server is unavailable.
Usage
The sec_rgy_properties_get_info routine returns a list of the
registry properties.
The property information consists of the following:
read_version A stamp that specifies the earliest version of the
registry server software that can read from this
registry.
write_version A stamp that specifies the earliest version of the
registry server software that can write to this
registry.
minimum_ticket_lifetime The minimum period of time for which an
authentication ticket remains valid.
default_certificate_lifetime The default period of time for which an
authentication certificate (ticket-granting ticket)
remains valid. A process can request an
authentication certificate with a longer lifetime.
Note that the maximum lifetime for an
authentication certificate cannot exceed the
lifetime established by the effective policy for
the requesting account.
low_unix_id_person The lowest UNIX ID that can be assigned to a
principal in the registry.
low_unix_id_group The lowest UNIX ID that can be assigned to a group
in the registry.
low_unix_id_org The lowest UNIX ID that can be assigned to an
organization in the registry.
max_unix_id The maximum UNIX ID that can be used for any item
in the registry.
realm A character string naming the cell controlled by
this registry.
realm_uuid The UUID of the cell controlled by this registry.
flags Flags indicating the following:
sec_rgy_prop_readonly If TRUE, the registry
database is read-only.
sec_rgy_prop_auth_cert_unbound If TRUE,
privilege attribute certificates
can be generated for use at any
site.
sec_rgy_prop_shadow_password If FALSE,
passwords can be distributed
over the network. If this flag
is TRUE, passwords are stripped
from the data returned to the
sec_rgy_acct_lookup routine, and
other routines that return an
account's encoded password.
sec_rgy_prop_embedded_unix_id All registry
UUIDs contain embedded UNIX IDs.
This implies that the UNIX ID of
any registry object cannot be
changed, because UUIDs are
immutable.
Permissions Required
The sec_rgy_properties_get_info routine requires the read (r)
permission on the policy object from which the property information
is to be returned.
Related Information
Routines: sec_rgy_properties_set_info
ΓòÉΓòÉΓòÉ 8.9.45. sec_rgy_properties_set_info ΓòÉΓòÉΓòÉ
Purpose
Sets registry properties.
Library
\lib\dceos2.lib
Format
#include <dce/policy.h>
void sec_rgy_properties_set_info(
sec_rgy_handle_t context,
sec_rgy_properties_t *properties,
error_status_t *status);
Parameters
Input
context An opaque handle bound to a registry server. Use
sec_rgy_site_open to acquire a bound handle.
properties A pointer to a sec_rgy_properties_t structure that
contains the registry property information to be set.
Registry property information contains information such
as the default and minimum lifetime and other
restrictions on privilege attribute certificates, and
the realm authentication name.
Output
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns one of the following errors:
sec_rgy_not_authorized The user is not authorized
to change the registry
properties.
sec_rgy_server_unavailable The DCE Registry Server
is unavailable.
Usage
The sec_rgy_properties_set_info routine sets the registry properties.
The property information consists of the following:
read_version A stamp that specifies the earliest version of the
registry server software that can read from this
registry.
write_version A stamp that specifies the earliest version of the
registry server software that can write to this
registry.
minimum_ticket_lifetime The minimum period of time an authentication
ticket remains valid.
default_certificate_lifetime The default period of time an
authentication certificate (ticket-granting ticket)
remains valid. A process can request an
authentication certificate with a longer lifetime.
Note that the maximum lifetime for an
authentication certificate cannot exceed the
lifetime established by the effective policy for
the requesting account.
low_unix_id_person The lowest UNIX ID that can be assigned to a
principal in the registry.
low_unix_id_group The lowest UNIX ID that can be assigned to a group
in the registry.
low_unix_id_org The lowest UNIX ID that can be assigned to an
organization in the registry.
max_unix_id The maximum UNIX ID that can be used for any item
in the registry.
realm A character string naming the cell controlled by
this registry.
realm_uuid The UUID of the cell controlled by this registry.
flags Flags indicating whether:
sec_rgy_prop_readonly If TRUE, the registry
database is read-only.
sec_rgy_prop_auth_cert_unbound If TRUE,
privilege attribute certificates
can be generated for use at any
site.
sec_rgy_prop_shadow_password If this flag is
TRUE, passwords are stripped
from the data returned to the
sec_rgy_acct_lookup routine, and
other routines that return an
account's encoded password. If
FALSE, passwords can be
distributed over the network.
sec_rgy_prop_embedded_unix_id All registry
UUIDs contain embedded UNIX IDs.
This implies that the UNIX ID of
any registry object cannot be
changed, since UUIDs are
immutable.
Permissions Required
The sec_rgy_properties_set_info routine requires the mgmt_info (m)
permission on the policy object for which the property information is
to be set.
Related Information
Routines:
sec_rgy_properties_get_info
ΓòÉΓòÉΓòÉ 8.9.46. sec_rgy_rep_admin_become_master ΓòÉΓòÉΓòÉ
Purpose
Converts a slave replica into a master replica.
Format
#include <dce/repadm.h>
void sec_rgy_rep_admin_become_master(
sec_rgy_handle_t context,
error_status_t *status);
Parameters
Input
context An opaque handle bound to the registry server. Use the
sec_rgy_site_open routine to acquire a bound handle.
Output
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Usage
The sec_rgy_rep_admin_become_master routine is a drastic operation
used to make the slave replica become the master replica because the
master replica died. Normally the sec_rgy_rep_admin_change_master
routine is used to designate a new master.
Related Information
Routines: sec_rgy_rep_admin_change_master
sec_rgy_site_open
Files:
/user/include/dce/repadm.idl - The idl file from which dce/repadm.h
was derived.
ΓòÉΓòÉΓòÉ 8.9.47. sec_rgy_rep_admin_become_slave ΓòÉΓòÉΓòÉ
Purpose
Converts a master replica into a slave replica.
Format
#include <dce/repadm.h>
void sec_rgy_rep_admin_become_slave(
sec_rgy_handle_t context,
error_status_t *status);
Parameters
Input
context An opaque handle bound to the registry server.
Output
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Usage
The sec_rgy_rep_admin_become_slave routine converts the master
replica into a slave replica.
Related Information
Files:
/user/include/dce/repadm.idl - The idl file from which dce/repadm.h
was derived.
ΓòÉΓòÉΓòÉ 8.9.48. sec_rgy_rep_admin_change_master ΓòÉΓòÉΓòÉ
Purpose
Changes the master replica to a different master replica.
Format
#include <dce/repadm.h>
void sec_rgy_rep_admin_change_master(
sec_rgy_handle_t context,
uuid_p_t new_master_id,
error_status_t *status);
Parameters
Input
context An opaque handle bound to the registry server.
new_master_id The UUID of the new master replica.
Output
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Usage
The sec_rgy_rep_admin_change_master routine changes the master
replica to new_master_id. The original master replica passes its
replica list state and the propagation queue to the new master.
Related Information
Routines:
sec_rgy_rep_admin_become_master
Files:
/user/include/dce/repadm.idl - The idl file from which dce/repadm.h
was derived.
ΓòÉΓòÉΓòÉ 8.9.49. sec_rgy_rep_admin_destroy ΓòÉΓòÉΓòÉ
Purpose
Destroys a replica's database.
Format
#include <dce/repadm.h>
void sec_rgy_rep_admin_destroy(
sec_rgy_handle_t context,
error_status_t *status);
Parameters
Input
context An opaque handle bound to the registry server to be
destroyed.
Output
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Usage
The sec_rgy_rep_admin_destroy routine tells a replica to destroy its
databases and to exit.
Related Information
Files:
/user/include/dce/repadm.idl - The idl file from which dce/repadm.h
was derived.
ΓòÉΓòÉΓòÉ 8.9.50. sec_rgy_rep_admin_get_sw_vers ΓòÉΓòÉΓòÉ
Purpose
Retrieves software version information.
Format
#include <dce/repadm.h>
void sec_rgy_rep_admin_get_sw_vers(
sec_rgy_handle_t context,
unsigned32 *num_sw_vers,
rs_replica_sw_vers_info_t **sw_vers_info,
unsigned32 *current_sw_vers_offset,
error_status_t *status);
Parameters
Input
context An opaque handle bound to the registry server.
Output
num_sw_vers A count of the number of elements in the array pointed
to by sw_vers_info.
sw_vers_info A pointer to an array that contains the software
versions supported.
current_sw_vers_offset An index into the sw_vers_info array. It
identifies the element containing the replica's current
operating software version.
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Usage
The sec_rgy_rep_admin_get_sw_vers routine retrieves the software
version of the security registry server specified in the context
parameter.
Memory is allocated for the array pointed to by sw_vers_info. This
memory must be freed by a call to dce_free.
Related Information
Routines:
dce_free
Files:
/user/include/dce/repadm.idl - The idl file from which dce/repadm.h
was derived.
ΓòÉΓòÉΓòÉ 8.9.51. sec_rgy_rep_admin_info ΓòÉΓòÉΓòÉ
Purpose
Retrieves replica information.
Format
#include <dce/repadm.h>
void sec_rgy_rep_admin_info(
sec_rgy_handle_t context,
rs_replica_sw_info_t *rep_info,
error_status_t *status);
Parameters
Input
context An opaque handle bound to the registry server.
Output
rep_info A pointer to the rs_replica_info_t structure containing
the replica's information.
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Usage
The sec_rgy_rep_admin_info routine retrieves a replica's information.
Related Information
Files:
/user/include/dce/repadm.idl - The idl file from which dce/repadm.h
was derived.
ΓòÉΓòÉΓòÉ 8.9.52. sec_rgy_rep_admin_info_vers ΓòÉΓòÉΓòÉ
Purpose
Obtains information about a replica.
Format
#include <dce\repadm.h>
void sec_rgy_rep_admin_info_vers(
sec_rgy_handle_t context,
rs_replica_info_t *rep_info,
rs_replica_twr_vec_p_t *rep_twrs,
rs_replica_twr_vec_p_t *master_twrs,
unsigned32 *num_sw_vers,
rs_replica_sw_vers_info_t **sw_vers_info[],
unsigned32 *current_sw_vers_offset,
error_status_t *status);
Parameters
Input
context An opaque handle bound to a registry server.
Output
rep_info A pointer to a rs_replica_info_t structure containing
the replica's information.
rep_twrs A pointer to a rs_replica_twr_vec_p_t containing the
replica's protocol towers.
master_twrs A pointer to a rs_replica_tw_vec_p_t structure
containing the master's protocol towers.
num_sw_vers A count of the number of elements in the array pointed
to by sw_vers_info.
sw_vers_info[] A pointer to an array of numeric_to_printstring
software version mapping.
current_sw_vers_offset An index into the sw_vers_info array. This
index identifies the element that contains the software
version at which the replica is currently operating.
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Usage
The sec_rgy_rep_admin_info_vers routine gets complete information
about a replica such as its state, uuid, protocol towers, latest
update sequence number and timestamp, and whether it is the master.
This routine also gets the replica's information about the master's
uuid, protocol towers, and the sequence number when the master was
designated.
Related Information
Files:
\usr\include\dce\repadm.idl - The idl file from which dce\repadm.h
was derived.
ΓòÉΓòÉΓòÉ 8.9.53. sec_rgy_rep_admin_init_replica ΓòÉΓòÉΓòÉ
Purpose
Initializes a replica.
Format
#include <dce/repadm.h>
void sec_rgy_rep_admin_init_replica(
sec_rgy_handle_t context,
uuid_p_t rep_id,
error_status_t *status);
Parameters
Input
context An opaque handle bound to the registry server.
rep_id A variable of type uuid_p_t containing the UUID of the
slave replica.
Output
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Usage
The sec_rgy_rep_admin_init_replica routine initializes the slave
replica identified by rep_id.
Related Information
Files:
/user/include/dce/repadm.idl - The idl file from which dce/repadm.h
was derived.
ΓòÉΓòÉΓòÉ 8.9.54. sec_rgy_rep_admin_maint ΓòÉΓòÉΓòÉ
Purpose
Puts a replica into or out of maintenance mode.
Format
#include <dce/repadm.h>
void sec_rgy_rep_admin_maint(
sec_rgy_handle_t context,
boolean32 in_maintenance,
error_status_t *status);
Parameters
Input
context An opaque handle bound to the registry server.
in_maintenance Set to TRUE when the replica is in maintenance mode;
set to FALSE when the replica is not in maintenance
mode.
Output
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Usage
The sec_rgy_rep_admin_maint routine puts a replica into or out of
maintenance mode.
Related Information
Files:
/user/include/dce/repadm.idl - The idl file from which dce/repadm.h
was derived.
ΓòÉΓòÉΓòÉ 8.9.55. sec_rgy_rep_admin_mkey ΓòÉΓòÉΓòÉ
Purpose
Changes the master key and encrypts the database again.
Format
#include <dce/repadm.h>
void sec_rgy_rep_admin_mkey(
sec_rgy_handle_t context,
error_status_t *status);
Parameters
Input
context An opaque handle to the registry server. This is the
register that will get a new master key.
Output
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Usage
The sec_rgy_rep_admin_mkey routine changes the master key and
encrypts again the database pointed to by context.
Related Information
Files:
/user/include/dce/repadm.idl - The idl file from which dce/repadm.h
was derived.
ΓòÉΓòÉΓòÉ 8.9.56. sec_rgy_rep_admin_set_sw_vers ΓòÉΓòÉΓòÉ
Purpose
Sets the software version.
Format
#include <dce/repadm.h>
void sec_rgy_rep_admin_set_sw_vers(
sec_rgy_handle_t context,
unsigned32 sw_rev,
error_status_t *status);
Parameters
Input
context An opaque handle to the registry server.
sw_rev The current version specification that describes the
range of software versions supported by the server.
Output
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Usage
The sec_rgy_rep_admin_set_sw_vers routine sets the cell-wide software
version.
Related Information
Files:
/user/include/dce/repadm.idl - The idl file from which dce/repadm.h
was derived.
ΓòÉΓòÉΓòÉ 8.9.57. sec_rgy_rep_admin_stop ΓòÉΓòÉΓòÉ
Purpose
Stop the replica.
Format
#include <dce/repadm.h>
void sec_rgy_rep_admin_stop(
sec_rgy_handle_t context,
error_status_t *status);
Parameters
Input
context An opaque handle to the registry server to be stopped.
Output
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Usage
The sec_rgy_rep_admin_stop routine stops the replica identified by
the context handle.
Related Information
Files:
/user/include/dce/repadm.idl - The idl file from which dce/repadm.h
was derived.
ΓòÉΓòÉΓòÉ 8.9.58. sec_rgy_site_bind ΓòÉΓòÉΓòÉ
Purpose
Binds to a registry site.
Library
\lib\dceos2.lib
Format
#include <dce/binding.h>
void sec_rgy_site_bind(
unsigned_char_p_t *site_name,
sec_rgy_bind_auth_info_t *auth_info,
sec_rgy_handle_t *context,
error_status_t *status);
Parameters
Input
site_name A character string (type unsigned_char_t) that contains
the name of the registry site to bind to. Supply this
name in any of the following forms:
o To randomly choose a site to bind to in the named
cell, specify a cell name (for example,
\...\r_d.com or \.: for the local cell)
o To bind to a specific site in a specific cell,
specify either the site's global name (for
example,
\...\r_d.com\subsys\dce\sec\rs_server_250_2) or
the site's network address (for example,
ncadg_ip_udp:15.22.144.248).
auth_info A pointer to the sec_rgy_bind_auth_info_t structure
that identifies the authentication protocol, protection
level, and authorization protocol to use in
establishing the binding. See
rpc_binding_set_auth_info. If the
sec_rgy_bind_auth_info_t structure specifies
authenticated RPC, the caller must have established a
valid network identity for this routine to succeed.
Output
context A pointer to a sec_rgy_handle_t type. Upon return, this
contains a registry server handle indicating (bound to)
the desired registry site.
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns one of the following errors:
sec_rgy_server_unavailable The DCE Registry Server
is unavailable.
sec_login_s_no_current_context The caller does not
have a valid network login
context.
Usage
The sec_rgy_site_bind routine binds to a registry site at the
security level specified by the auth_info parameter. The site_name
parameter identifies the registry to use. If site_name is NULL, or a
zero-length string, a registry site in the local cell is selected by
the client agent.
Notes
Similar to the sec_rgy_site_bind_query routine, this routine binds
arbitrarily to either an update or query site. Although update sites
can accept queries, query sites cannot accept updates. To
specifically select an update site, use sec_rgy_site_bind_update.
Related Information
Routines: rpc_binding_set_auth_info
sec_rgy_site_open
sec_rgy_cell_bind
sec_rgy_site_bind_update
ΓòÉΓòÉΓòÉ 8.9.59. sec_rgy_site_bind_query ΓòÉΓòÉΓòÉ
Purpose
Binds to a registry query site.
Library
\lib\dceos2.lib
Format
#include <dce/binding.h>
void sec_rgy_site_bind_query(
unsigned_char_t *site_name,
sec_rgy_bind_auth_info_t *auth_info,
sec_rgy_handle_t *context,
error_status_t *status);
Parameters
Input
site_name A character string (type unsigned_char_t) that contains
the name of the registry site to bind to. Supply this
name in any of the following forms:
o To randomly choose a site to bind to in the named
cell, specify a cell name (for example,
\...\r_d.com or \.: for the local cell)
o To bind to a specific site in a specific cell,
specify either the site's global name (for
example,
\...\r_d.com\subsys\dce\sec\rs_server_250_2) or
the site's network address (for example,
ncadg_ip_udp:15.22.144.248).
auth_info A pointer to the sec_rgy_bind_auth_info_t structure
that identifies the authentication protocol, protection
level, and authorization protocol to use in
establishing the binding. See
rpc_binding_set_auth_info. If the
sec_rgy_bind_auth_info_t structure specifies
authenticated RPC, the caller must have established a
valid network identity for this routine to succeed.
Output
context A pointer to a sec_rgy_handle_t. Upon return, this
contains a registry server handle indicating (bound to)
the desired registry site.
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns one of the following errors:
sec_login_s_no_current_context The caller does not
have a valid network login context.
sec_rgy_server_unavailable The DCE Registry Server
is unavailable.
Usage
The sec_rgy_site_bind_query routine binds to a registry query site at
an arbitrary level of security. A registry query site is a satellite
server that operates on a periodically updated copy of the main
registry database. To change the registry database, it is necessary
to change a registry update site, which then automatically updates
its associated query sites. No changes can be made directly to a
registry query database.
Related Information
Routines: rpc_binding_set_auth_info
sec_rgy_site_open
sec_rgy_site_bind
ΓòÉΓòÉΓòÉ 8.9.60. sec_rgy_site_bind_update ΓòÉΓòÉΓòÉ
Purpose
Binds to a registry update site.
Library
\lib\dceos2.lib
Format
#include <dce/binding.h>
void sec_rgy_site_bind_update(
unsigned_char_t *site_name,
sec_rgy_bind_auth_info_t *auth_info,
sec_rgy_handle_t *context,
error_status_t *status);
Parameters
Input
site_name A character string (type unsigned_char_t) that contains
the name of the registry site to bind to. Supply this
name in any of the following forms:
o To choose an update site to bind to in the named
cell, specify a cell name (for example,
\...\r_d.com or \.: for the local cell)
auth_info A pointer to the sec_rgy_bind_auth_info_t structure
that identifies the authentication protocol, protection
level, and authorization protocol to use in
establishing the binding. See
rpc_binding_set_auth_info. If the
sec_rgy_bind_auth_info_t structure specifies
authenticated RPC, the caller must have established a
valid network identity for this routine to succeed.
Output
context A pointer to a sec_rgy_handle_t. Upon return, this
contains a registry server handle indicating (bound to)
the desired registry site.
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns the following error:
sec_rgy_server_unavailable The DCE Registry Server
is unavailable.
sec_login_s_no_current_context The caller does not
have a valid network login
context.
Usage
The sec_rgy_site_bind_update routine binds to a registry update site.
A registry update site is a master server that can control several
satellite (query) servers. To change the registry database, it is
necessary to change a registry update site, which then automatically
updates its associated query sites. No changes can be made directly
to a registry query database.
The site_name parameter identifies the cell in which to find the
update site. If site_name is NULL or a zero-length string, an update
site in the local cell is selected by the client agent.
The handle for the associated registry server is returned in context.
The handle is to an update site. Use this registry context handle in
subsequent calls that update or query the registry database (for
example, the sec_rgy_pgo_add or sec_rgy_acct_lookup routine).
Related Information
Routines: rpc_binding_set_auth_info
sec_rgy_site_bind
sec_rgy_site_open
ΓòÉΓòÉΓòÉ 8.9.61. sec_rgy_site_binding_get_info ΓòÉΓòÉΓòÉ
Purpose
Returns information from the registry binding handle.
Library
\lib\dceos2.lib
Format
#include <dce/binding.h>
void sec_rgy_site_binding_get_info(
sec_rgy_handle_t context,
unsigned_char_t **cell_name,
unsigned_char_t **server_name,
unsigned_char_t **string_binding,
sec_rgy_bind_auth_info_t *auth_info,
error_status_t *status);
Parameters
Input
context A sec_rgy_handle_t parameter that contains a registry
server handle indicating (bound to) the desired
registry site. To obtain information on the default
binding handle, initialize context to
sec_rgy_default_handle. A valid login context must be
set for the process if context is set to
sec_rgy_default_handle; otherwise, the error
sec_under_login_s_no_current_context is returned.
Output
cell_name The name of the home cell for this registry.
server_name The name of the node the server resides on. This name
is either a global name or a network address, depending
on the form used to input the name to the routine that
bound to the site.
string_binding A string containing binding information from the
sec_rgy_handle_t.
auth_info A pointer to the sec_rgy_bind_auth_info_t structure
that identifies the authentication protocol, protection
level, and authorization protocol to use in
establishing the binding. See
rpc_binding_set_auth_info.
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns one of the following errors:
sec_login_s_no_current_context The caller does not
have a valid network login context.
sec_rgy_server_unavailable The DCE registry server
is unavailable.
Usage
The sec_rgy_site_binding_get_info routine returns the site name and
authentication information associated with the context parameter. If
the context is the default context, the information for the default
binding is returned. Passing in a NULL value for any of the output
values (except for status) prevents that value from being returned.
Memory is allocated for the string returned in the cell_name,
server_name, and string_binding parameters. The application calls the
rpc_string_free routine to deallocate that memory.
Related Information
Routines: sec_rgy_site_bind
sec_rgy_site_open
rpc_string_free
ΓòÉΓòÉΓòÉ 8.9.62. sec_rgy_site_close ΓòÉΓòÉΓòÉ
Purpose
Frees the binding handle for a registry server.
Library
\lib\dceos2.lib
Format
#include <dce/binding.h>
void sec_rgy_site_close(
sec_rgy_handle_t ext_context,
error_status_t *status);
Parameters
Input
ext_context An opaque handle indicating (bound to) a registry
server. Use sec_rgy_site_open to acquire a bound
handle.
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns an error.
Usage
The sec_rgy_site_close routine frees the memory occupied by the
specified handle and destroys its binding with the registry server.
Notes
A handle cannot be used after it is freed.
Related Information
Routines: sec_rgy_site_get
sec_rgy_site_open
sec_rgy_site_open_query
sec_rgy_site_open_update
ΓòÉΓòÉΓòÉ 8.9.63. sec_rgy_site_get ΓòÉΓòÉΓòÉ
Purpose
Returns the string representation for a bound registry site.
Library
\lib\dceos2.lib
Format
#include <dce/binding.h>
void sec_rgy_site_get(
sec_rgy_handle_t context,
unsigned_char_t **site_name,
error_status_t *status);
Parameters
Input
context An opaque handle bound to a registry server. Use
sec_rgy_site_open to acquire a bound handle. To obtain
information on the default binding handle, initialize
context to sec_rgy_default_handle. A valid login
context must be set for the process if context is set
to sec_rgy_default_handle; otherwise, the error
sec_under_login_s_no_current_context is returned.
Output
site_name A pointer to a character string (type unsigned_char_t)
that contains the returned name of the registry site
associated with context, the given registry server
handle. The name is either a global name or a network
address, depending on the form used to input the name
to the call that bound to the site.
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns the following error:
sec_rgy_server_unavailable The requested registry
server is not available.
sec_under_login_s_no_current_context The caller
does not have a valid network
login context.
Usage
The sec_rgy_site_get routine returns the name of the registry site
associated with the specified handle. If the handle is the default
context, the routine returns the name of the default context's site.
Memory is allocated for the string returned in the site_name
parameter. The application calls the rpc_string_free routine to
deallocate that memory.
Related Information
Routines:
sec_rgy_site_open
ΓòÉΓòÉΓòÉ 8.9.64. sec_rgy_site_is_readonly ΓòÉΓòÉΓòÉ
Purpose
Checks whether a registry site is read-only.
Library
\lib\dceos2.lib
Format
#include <dce/binding.h>
boolean32 sec_rgy_site_is_readonly(
sec_rgy_handle_t context);
Parameters
Input
context An opaque handle indicating (bound to) a registry
server. Use sec_rgy_site_open to acquire a bound
handle.
Usage
The sec_rgy_site_is_readonly routine checks whether the registry site
associated with the specified handle is a query site or an update
site. A query site is a read-only replica of a master registry
database (the update site). The update site accepts changes to the
registry database and duplicates the changes in its associated query
sites.
Return Codes
The routine returns:
o TRUE if the registry site is read-only or if there was an error
using the specified handle.
o FALSE if the registry site is an update site.
Related Information
Routines: sec_rgy_site_open
sec_rgy_site_open_query
ΓòÉΓòÉΓòÉ 8.9.65. sec_rgy_site_open ΓòÉΓòÉΓòÉ
Purpose
Binds to a registry site.
Library
\lib\dceos2.lib
Format
#include <dce/binding.h>
void sec_rgy_site_open(
unsigned_char_t *site_name,
sec_rgy_handle_t *context,
error_status_t *status);
Parameters
Input/Output
site_name A pointer to a character string (type unsigned_char_t)
containing the name of the registry site to bind to.
Supply this name in any of the following forms:
o To randomly choose a site to bind to in the named
cell, specify a cell name (for example,
\...\r_d.com or \.: for the local cell)
o To bind to a specific site in a specific cell,
specify either the site's global name (for
example,
\...\r_d.com\subsys\dce\sec\rs_server_250_2) or
the site's network address (for example,
ncadg_ip_udp:15.22.144.248). Note that if you
specify the name of a specific secd to bind to and
the name is not valid, the routine binds to a
random site in the cell if the specified cell name
is valid.
Output
context A pointer to a sec_rgy_handle_t parameter. Upon return,
this contains a registry server handle indicating
(bound to) the desired registry site.
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns the following error:
sec_rgy_server_unavailable The requested registry
server is not available.
sec_login_s_no_current_context The caller does not
have a valid network login
context.
Usage
The sec_rgy_site_open routine binds to a registry site at the level
of security specified in the rpc_binding_set_auth_info routine. The
site_name parameter identifies the registry to use. If site_name is
NULL, or a zero-length string, a registry site in the local cell is
selected by the client agent. The caller must have established a
valid network identity for this routine to succeed.
Related Information
Routines: sec_rgy_rep_admin_become_master
sec_rgy_site_close
sec_rgy_site_is_readonly
sec_rgy_site_open_query
sec_rgy_site_open_update
sec_rgy_plcy_get_override_info
ΓòÉΓòÉΓòÉ 8.9.66. sec_rgy_site_open_query ΓòÉΓòÉΓòÉ
Purpose
Binds to a registry query site.
Library
\lib\dceos2.lib
Format
#include <dce/binding.h>
void sec_rgy_site_open_query(
unsigned_char_t *site_name,
sec_rgy_handle_t *context,
error_status_t *status);
Parameters
Input
site_name A character string (type unsigned_char_t) containing
the name of the registry query site to bind to. Supply
this name in any of the following forms:
o To randomly choose a site to bind to in the named
cell, specify a cell name (for example,
\...\r_d.com or \.: for the local cell)
o To bind to a specific site in a specific cell,
specify either the site's global name (for
example,
\...\r_d.com\subsys\dce\sec\rs_server_250_2) or
the site's network address (for example,
ncadg_ip_udp:15.22.144.248).
Output
context A pointer to a sec_rgy_handle_t. Upon return, this
contains a registry server handle indicating (bound to)
the desired registry site.
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns the following error:
sec_rgy_server_unavailable The DCE registry server
is unavailable.
sec_login_s_no_current_context The caller does not
have a valid network login context.
Usage
The sec_rgy_site_open_query routine binds to a registry query site. A
registry query site is a satellite server that operates on a
periodically updated copy of the main registry database. To change
the registry database, it is necessary to change a registry update
site, which then automatically updates its associated query sites. No
changes can be made directly to a registry query database.
The site_name parameter identifies the query site to use. If
site_name is NULL, or a zero-length string, a query site in the local
cell is selected by the client agent.
The handle for the associated registry server is returned in context.
The caller must have established a valid network identity for this
routine to succeed.
Notes
The use of the sec_rgy_site_bind_query routine to bind to a registry
query site is recommended in place of this routine.
Related Information
Routines: sec_rgy_site_close
sec_rgy_site_get
sec_rgy_site_is_readonly
sec_rgy_site_open
sec_rgy_site_open_update
ΓòÉΓòÉΓòÉ 8.9.67. sec_rgy_site_open_update ΓòÉΓòÉΓòÉ
Purpose
Binds to a registry update site.
Library
\lib\dceos2.lib
Format
#include <dce/binding.h>
void sec_rgy_site_open_update(
unsigned_char_t *site_name,
sec_rgy_handle_t *context,
error_status_t *status);
Parameters
Input
site_name A character string (type unsigned_char_t) containing
the name of an update registry site to which to bind.
Supply this name in any of the following forms:
o To choose the update site to bind to in the named
cell, specify a cell name (for example,
\...\r_d.com or \.: for the local cell)
o To start the search for the update site at a
specific replica in the replica's cell, specify
either the site's global name (for example,
\...\r_d.com\subsys\dce\sec\rs_server_250_2 or the
site's network address (for example,
ncadg_ip_udp:15.22.144.248
Output
context A pointer to a sec_rgy_handle_t variable. Upon return,
this contains a registry server handle indicating
(bound to) the desired registry site.
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns the following error:
sec_rgy_server_unavailable The requested registry
server is unavailable.
sec_login_s_no_current_context The caller does not
have a valid network login context.
Usage
The sec_rgy_site_open_update routine binds to a registry update site.
A registry update site is a master server that can control several
satellite (query) servers. To change the registry database, it is
necessary to change a registry update site, which then automatically
updates its associated query sites. No changes can be made directly
to a registry query database.
The site_name parameter identifies either the cell that contains the
update site or the replica at which to start the search for the
update site. If site_name is NULL or a zero-length string, an update
site in the local cell is selected by the client agent.
The handle for the associated registry server is returned in context.
The handle is to an update site. Use this registry context handle in
subsequent calls that update or query the registry database (for
example, sec_rgy_pgo_add or sec_rgy_acct_lookup). The caller must
have established a valid network identity for this routine to
succeed.
Notes
The use of the sec_rgy_site_bind_update routine to bind to a registry
update site is recommended in place of this routine.
Related Information
Routines: sec_rgy_site_close
sec_rgy_site_get
sec_rgy_site_is_readonly
sec_rgy_site_open
sec_rgy_site_open_query
ΓòÉΓòÉΓòÉ 8.9.68. sec_rgy_unix_getgrent ΓòÉΓòÉΓòÉ
Purpose
Returns a UNIX-style group entry.
Library
\lib\dceos2.lib
Format
#include <dce/rgybase.h>
#include <dce/unix.h>
void sec_rgy_unix_getgrent (
sec_rgy_handle_t context,
signed32 max_num_members,
sec_rgy_cursor_t *marker,
sec_rgy_unix_group_t *group_entry,
signed32 *num_members[],
sec_rgy_member_t member_list,
error_status_t *status);
Parameters
Input
context An opaque handle bound to a registry server. Use
sec_rgy_site_open to acquire a bound handle.
max_num_members The maximum number of members to be returned by the
routine. This must be no larger than the allocated size
of the member_list array, and must not be negative. If
you specify a negative value for this parameter the
routine uses 0 (zero).
Input/Output
marker An opaque pointer indicating a specific PGO item entry
in the registry database. The sec_rgy_unix_getgrent
routine returns information about the group item to
which marker is pointing, and advances the cursor to
point to the next item in the database. When the end of
the list of entries is reached, the routine returns
sec_rgy_no_more_entries. Use sec_rgy_cursor_reset to
refresh the cursor.
Output
group_entry A UNIX-style group structure containing information
obtained from the PGO item pointed to by marker at the
beginning of the call.
num_members A signed 32-bit integer containing the total number of
member names returned in the member_list array.
member_list An array of character strings to receive the returned
member names. The size allocated for the array is
given by max_num_members. If this value is less than
the total number of members in the membership list,
multiple calls must be made to return all of the
members.
status On successful completion, the routine returns
error_status_ok. Otherwise, it returns one of the
following errors:
sec_rgy_no_more_entries The end of the list of
entries has been reached.
sec_rgy_server_unavailable The registry server
cannot be reached.
Usage
The sec_rgy_unix_getgrent routine returns a UNIX group structure
containing information obtained from the PGO item pointed to by the
cursor into the registry database. The group structure is in the
form:
typedef struct sec_rgy_unix_group_t {
sec_rgy_name_t name;
signed32 gid;
sec_rgy_member_buf_t members;
} sec_rgy_unix_group_t;
The structure includes:
o The name of the group.
o The UNIX ID of the group.
o A string containing the names of the group members. This string
is limited in size by the size of the sec_rgy_member_buf_t type
defined in rgybase.idl.
The routine also returns an array of member names, limited in size by
the max_num_members parameter.
This routine does not recognize implicit members of a group. It does
recognize those members of a group who have been added explicitly
(using the dcecp command). When an account is first defined, the
principal is assigned an organization and a group as part of its
account name. The principal therefore becomes a member of that group
without being explicitly defined as such. This routine does not list
any members that have been implicitly defined. To get all members of
a group, including the implicit members, you can use the
sec_rgy_pgo_get_members routine.
Related Information
Routines: sec_rgy_unix_getgrgid
sec_rgy_unix_getgrnam
sec_rgy_cursor_reset
sec_rgy_site_open
ΓòÉΓòÉΓòÉ 8.9.69. sec_rgy_unix_getgrgid ΓòÉΓòÉΓòÉ
Purpose
Returns a UNIX-style group entry for the account matching the
specified group ID.
Library
\lib\dceos2.lib
Format
#include <dce/rgybase.h>
#include <dce/unix.h>
void sec_rgy_unix_getgrgid(
sec_rgy_handle_t context,
signed32 gid,
signed32 max_num_members,
sec_rgy_cursor_t *marker,
sec_rgy_unix_group_t *group_entry,
signed32 *num_members,
sec_rgy_member_t members[],
error_status_t *status);
Parameters
Input
context An opaque handle bound to a registry server. Use
sec_rgy_site_open to acquire a bound handle.
gid A 32-bit integer specifying the group ID to match.
max_num_members The maximum number of members to be returned by the
routine. This must be no larger than the allocated size
of the members array, and must not be negative. If you
specify a negative value for this parameter the routine
uses 0 (zero).
Input/Output
marker An opaque pointer that indicates a specific PGO item
entry in the registry database. The
sec_rgy_unix_getgrgid routine returns the PGO item
indicated by marker, and advances the cursor to point
to the next item in the database. When the end of the
list of entries is reached, the routine returns
sec_rgy_no_more_entries. Use sec_rgy_cursor_reset to
refresh the cursor.
Output
group_entry A UNIX-style group entry structure returned with
information about the group matching gid.
num_members An signed 32-bit integer containing the total number of
member names returned in the members array.
members An array of character strings to receive the returned
member names. The size allocated for the array is given
by max_num_members. If this value is less than the
total number of members in the membership list,
multiple calls must be made to return all of the
members.
status On successful completion, the routine returns
error_status_ok. Otherwise, it returns one of the
following errors:
sec_rgy_no_more_entries The end of the list of
entries has been reached.
sec_rgy_server_unavailable The requested registry
server is unavailable.
Usage
The sec_rgy_unix_getgrgid routine returns the next UNIX group
structure that matches the input UNIX group ID. The structure is in
the following form:
typedef struct {
sec_rgy_name_t name;
signed32 gid;
sec_rgy_member_buf_t members;
} sec_rgy_unix_group_t;
The structure includes:
o The name of the group.
o The UNIX ID of the group.
o A string containing the names of the group members. This string
is limited in size by the size of the sec_rgy_member_buf_t type
defined in rgybase.idl.
The routine also returns an array of member names, limited in size by
the num_members parameter.
This routine does not recognize implicit members of a group. It does
recognize those members of a group who have been added explicitly
(using the dcecp command). When an account is first defined, the
principal is assigned an organization and a group as part of its
account name. The principal therefore becomes a member of that group
without being explicitly defined as such. This routine does not list
any members that have been implicitly defined. To get all members of
a group, including the implicit members, you can use the
sec_rgy_pgo_get_members routine.
This routine is supplied in source code form.
Related Information
Routines: sec_rgy_unix_getgrent
sec_rgy_unix_getgrnam
sec_rgy_cursor_reset
sec_rgy_site_open
ΓòÉΓòÉΓòÉ 8.9.70. sec_rgy_unix_getgrnam ΓòÉΓòÉΓòÉ
Purpose
Returns a UNIX-style group entry for the account matching the
specified group name.
Library
\lib\dceos2.lib
Format
#include <dce/rgybase.h>
#include <dce/unix.h>
void sec_rgy_unix_getgrnam(
sec_rgy_handle_t context,
sec_rgy_name_t name,
signed32 name_length,
signed32 max_num_members,
sec_rgy_cursor_t marker,
sec_rgy_unix_group_t group_entry,
signed32 num_members,
sec_rgy_member_t members[],
error_status_t *status);
Parameters
Input
context An opaque handle bound to a registry server. Use
sec_rgy_site_open to acquire a bound handle.
name A character string (of type sec_rgy_name_t) specifying
the group name to be matched.
name_length A signed 32-bit integer specifying the length of name
in characters.
max_num_members The maximum number of members to be returned by the
routine. This must be no larger than the allocated size
of the members array, and must not be negative. If you
specify a negative value for this parameter the routine
uses 0 (zero).
Input/Output
marker An opaque pointer that indicates a specific PGO item
entry in the registry database. The
sec_rgy_unix_getgrnam routine returns the PGO item
indicated by marker, and advances the cursor to point
to the next item in the database. When the end of the
list of entries is reached, the routine returns
sec_rgy_no_more_entries. Use sec_rgy_cursor_reset to
refresh the cursor.
Output
group_entry A UNIX-style group entry structure returned with
information about the group matching name.
num_members A signed 32-bit integer containing the total number of
member names returned in the members array.
members An array of character strings to receive the returned
member names. The size allocated for the array is given
by max_number. If this value is less than the total
number of members in the membership list, multiple
calls must be made to return all of the members.
status On successful completion, the routine returns
error_status_ok. Otherwise, it returns one of the
following errors:
sec_rgy_no_more_entries The end of the list of
entries has been reached.
sec_rgy_bad_data The name supplied as input
was too long.
sec_rgy_server_unavailable The requested registry
server is unavailable.
Usage
The sec_rgy_unix_getgrnam routine looks up the next group entry in
the registry that matches the input group name and returns the
corresponding UNIX-style group structure. The structure is in the
following form:
typedef struct {
sec_rgy_name_t name;
signed32 gid;
sec_rgy_member_buf_t members;
} sec_rgy_unix_group_t;
The structure includes:
o The name of the group.
o The UNIX ID of the group.
o A string containing the names of the group members. This string
is limited in size by the size of the sec_rgy_member_buf_t type
defined in rgybase.idl.
The routine also returns an array of member names, limited in size by
the num_members parameter.
This routine does not recognize implicit members of a group. It does
recognize those members of a group who have been added explicitly
(using the dcecp command). When an account is first defined, the
principal is assigned an organization and a group as part of its
account name. The principal therefore becomes a member of that group
without being explicitly defined as such. This routine does not list
any members that have been implicitly defined. To get all members of
a group, including the implicit members, you can use the
sec_rgy_pgo_get_members routine.
This routine is provided in source code form.
Related Information
Routines: sec_rgy_unix_getgrent
sec_rgy_unix_getgrgid
sec_rgy_cursor_reset
sec_rgy_site_open
ΓòÉΓòÉΓòÉ 8.9.71. sec_rgy_unix_getpwent ΓòÉΓòÉΓòÉ
Purpose
Returns a UNIX-style password entry.
Library
\lib\dceos2.lib
Format
#include <dce/rgybase.h>
#include <dce/unix.h>
void sec_rgy_unix_getpwent (
sec_rgy_handle_t context,
sec_rgy_cursor_t *marker,
sec_rgy_unix_passwd_t *passwd_entry,
error_status_t *status);
Parameters
Input
context An opaque handle bound to a registry server. Use
sec_rgy_site_open to acquire a bound handle.
Input/Output
marker An opaque pointer that indicates a specific PGO item
entry in the registry database. The
sec_rgy_unix_getpwent routine returns information about
the item to which marker is pointing, and advances the
cursor to point to the next item in the database. When
the end of the list of entries is reached, the routine
returns sec_rgy_no_more_entries. Use
sec_rgy_cursor_reset to refresh the cursor.
Output
passwd_entry A UNIX-style password structure containing information
obtained from the PGO item pointed to by marker at the
beginning of the routine.
status On successful completion, the routine returns
error_status_ok. Otherwise, it returns one of the
following errors:
sec_rgy_no_more_entries The end of the list of
entries has been reached.
sec_rgy_server_unavailable The registry server
cannot be reached.
Usage
The sec_rgy_unix_getpwent routine returns a UNIX password structure
containing information obtained from the PGO item pointed to by the
cursor into the registry database. The password structure is in the
form:
typedef struct sec_rgy_unix_passwd_t {
sec_rgy_unix_login_name_t name;
sec_rgy_unix_passwd_buf_t passwd;
signed32 uid;
signed32 gid;
signed32 oid;
sec_rgy_unix_gecos_t gecos;
sec_rgy_pname_t homedir;
sec_rgy_pname_t shell;
} sec_rgy_unix_passwd_t;
The structure includes:
o The account's login name.
o The account's password.
o The account's UNIX ID.
o The UNIX ID of the group and organization associated with the
account.
o The account's GECOS information.
o The account's home directory.
o The account's login shell.
Related Information
Routines: sec_rgy_unix_getpwuid
sec_rgy_unix_getpwnam
sec_rgy_cursor_reset
sec_rgy_site_open
Files:
\include\dce\rgybase.idl - The idl file from which dce\rgybase.h was
derived.
\usr\include\dce\unix.idl - The idl file from which dce\unix.h was
derived.
ΓòÉΓòÉΓòÉ 8.9.72. sec_rgy_unix_getpwnam ΓòÉΓòÉΓòÉ
Purpose
Returns a UNIX-style passwd entry for the account matching the
specified name.
Library
\lib\dceos2.lib
Format
#include <dce/rgybase.h>
#include <dce/unix.h>
void sec_rgy_unix_getpwnam(
sec_rgy_handle_t context,
sec_rgy_name_t name,
unsigned32 name_len,
sec_rgy_cursor_t *marker,
sec_rgy_unix_passwd_t *passwd_entry,
error_status_t *status);
Parameters
Input
context An opaque handle bound to a registry server. Use the
sec_rgy_site_open routine to acquire a bound handle.
name A character string of type sec_rgy_name_t containing
the name of the person whose name entry is desired.
name_len A 32-bit integer representing the length of the name in
characters.
Input/Output
marker An opaque pointer that indicates a specific PGO item
entry in the registry database. The
sec_rgy_unix_getpwnam routine returns the PGO item
indicated by marker, and advances the cursor to point
to the next item in the database. When the end of the
list of entries is reached, the routine returns
sec_rgy_no_more_entries. Use the sec_rgy_cursor_reset
routine to refresh the cursor.
Output
passwd_entry A UNIX-style passwd structure returned with information
about the account matching name.
status On successful completion, the routine returns
error_status_ok. Otherwise, it returns one of the
following errors:
sec_rgy_bad_data The name supplied as input
was too long.
sec_rgy_no_more_entries The end of the list of
entries has been reached.
Usage
The sec_rgy_unix_getpwnam routine returns the next UNIX passwd
structure that matches the input name. The structure is in the form:
typedef struct {
sec_rgy_unix_login_name_t name;
sec_rgy_unix_passwd_buf_t passwd;
signed32 uid;
signed32 gid;
signed32 oid;
sec_rgy_unix_gecos_t gecos;
sec_rgy_pname_t homedir;
sec_rgy_pname_t shell;
} sec_rgy_unix_passwd_t;
The structure includes:
o The account's login name.
o The account's password.
o The account's UNIX ID.
o The UNIX ID of the group and organization associated with the
account.
o The account's GECOS information.
o The account's home directory.
o The account's login shell.
This routine is provided in source code form.
Related Information
Routines:
sec_rgy_unix_getpwent
sec_rgy_unix_getpwuid
sec_rgy_cursor_reset
sec_rgy_site_open
Files:
\include\dce\rgybase.idl - The idl file from which dce\rgybase.h was
derived.
\usr\include\dce\unix.idl - The idl file from which dce\unix.h was
derived.
ΓòÉΓòÉΓòÉ 8.9.73. sec_rgy_unix_getpwuid ΓòÉΓòÉΓòÉ
Purpose
Returns a UNIX-style passwd entry for the account matching the
specified UID.
Library
\lib\dceos2.lib
Format
#include <dce/rgybase.h>
#include <dce/unix.h>
void sec_rgy_unix_getpwuid(
sec_rgy_handle_t context,
signed32 uid,
sec_rgy_cursor_t *marker,
sec_rgy_unix_passwd_t *passwd_entry,
error_status_t *status);
Parameters
Input
context An opaque handle bound to a registry server. Use the
sec_rgy_site_open routine to acquire a bound handle.
uid A 32-bit integer UNIX ID.
Input/Output
marker An opaque pointer that indicates a specific PGO item
entry in the registry database. The
sec_rgy_unix_getpwuid routine returns the PGO item
indicated by marker, and advances the cursor to point
to the next item in the database. When the end of the
list of entries is reached, the routine returns
sec_rgy_no_more_entries. Use sec_rgy_cursor_reset to
refresh the cursor.
Output
passwd_entry A UNIX-style password structure returned with
information about the account matching uid.
status On successful completion, the routine returns
error_status_ok. Otherwise, it returns one of the
following errors:
sec_rgy_no_more_entries The end of the list of
entries has been reached.
sec_rgy_server_unavailable The requested registry
server is unavailable.
Usage
The sec_rgy_unix_getpwuid routine looks up the next passwd entry in
the registry that matches the input UNIX ID and returns the
corresponding sec_rgy_unix_passwd_t structure. The structure is in
the following form:
typedef struct {
sec_rgy_unix_login_name_t name;
sec_rgy_unix_passwd_buf_t passwd;
signed32 uid;
signed32 gid;
signed32 oid;
sec_rgy_unix_gecos_t gecos;
sec_rgy_pname_t homedir;
sec_rgy_pname_t shell;
} sec_rgy_unix_passwd_t;
The structure includes:
o The account's login name.
o The account's password.
o The account's UNIX ID.
o The UNIX ID of the group and organization associated with the
account.
o The account's GECOS information.
o The account's home directory.
o The account's login shell.
This routine is provided in source code form.
Related Information
Routines: sec_rgy_unix_getpwent
sec_rgy_unix_getpwnam
sec_rgy_cursor_reset
Files:
\include\dce\rgybase.idl - The idl file from which dce\rgybase.h was
derived.
\usr\include\dce\unix.idl - The idl file from which dce\unix.h was
derived.
ΓòÉΓòÉΓòÉ 8.9.74. sec_rgy_wait_until_consistent ΓòÉΓòÉΓòÉ
Purpose
Blocks the caller while prior updates are propagated to the registry
replicas.
Format
#include <dce/misc.h>
boolean32 sec_rgy_wait_until_consistent(
sec_rgy_handle_t context,
error_status_t *status);
Parameters
Input
context The registry server handle associated with the master
registry.
Output
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns one of the following errors:
sec_rgy_server_unavailable The server for the
master registry is not
available.
sec_rgy_read_only Either the master site is
in maintenance mode or
the site associated with
the handle is a read-only
(query) site.
Usage
The sec_rgy_wait_until_consistent routine blocks callers until all
prior updates to the master registry have been propagated to all
active registry replicas.
Return Codes
The routine returns TRUE when all replicas have received the prior
updates. It returns FALSE if at least one replica did not receive the
updates.
ΓòÉΓòÉΓòÉ 9. DCE Event Management Service API ΓòÉΓòÉΓòÉ
The DCE Event Management Service (EMS) manages event services in a DCE cell.
EMS consists of three parts: break=fit.
The event supplier interface Provides support for suppliers. A supplier can
be any DCE core service or DCE-based
application that emits event data.
The EMS daemon (emsd) Responsible for the following tasks:
o Authenticating and authorizing event
suppliers and consumers
o Keeping databases of event types, event
filters, and consumers
o Associating an event filter group with
each event consumer
o Ensuring reliable delivery of events to
interested consumers
The event consumer interface Provides support for the steps required to
implement an event consumer. An event consumer
performs the following tasks:
o Query EMS for supported event types
o Get a list of existing filter names
o Construct event filters for each event
type
o Add event filters to its event filter
group
Note: The event consumer must be registered
with EMS and must set up event filter
groups before it can receive events.
The EMS API provides the following structures and interfaces:
EMS Data Structures
EMS Registration Routines
EMS Event Type Routines
EMS Supplier Routine
EMS Event Filter Routines
EMS Consumer Routines
EMS Management Routines
ΓòÉΓòÉΓòÉ 9.1. EMS Data Structures ΓòÉΓòÉΓòÉ
The data structures for EMS are grouped by function. The groups include the
following:
o EMS Event Attributes
o EMS Event Structure
o Event Types
o EMS Event Filters
o EMS Consumer Data Structures
o EMS Server Data Structure
ΓòÉΓòÉΓòÉ 9.1.1. EMS Event Attributes ΓòÉΓòÉΓòÉ
ems_attr_type_t An unsigned16 integer that is used to specify the data type of
an event attribute. The attribute type specifies the format of the
data in the event attribute value union (ems_attr_value_t). An event
attribute type can be one of those in the following table:
ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
Γöé Table 18. Event Attribute Type Specifiers Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé ATTRIBUTE TYPE Γöé DATA TYPE Γöé TAGGED UNION FIELD NAME Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
Γöé ems_c_attr_small_int Γöé idl_small_int Γöé small_int Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé ems_c_attr_short_int Γöé idl_short_int Γöé short_int Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé ems_c_attr_long_int Γöé idl_long_int Γöé long_int Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé ems_c_attr_hyper_int Γöé idl_hyper_int Γöé hyper_int Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé ems_c_attr_usmall_int Γöé idl_usmall_int Γöé usmall_int Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé ems_c_attr_ushort_int Γöé idl_ushort_int Γöé ushort_int Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé ems_c_attr_ulong_int Γöé idl_ulong_int Γöé ulong_int Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé ems_c_attr_uhyper_int Γöé idl_uhyper_int Γöé uhyper_int Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé ems_c_attr_short_float Γöé idl_short_float Γöé short_float Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé ems_c_attr_long_float Γöé idl_long_float Γöé long_float Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé ems_c_attr_boolean Γöé idl_boolean Γöé bool Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé ems_c_attr_uuid Γöé uuid_t Γöé uuid Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé ems_c_attr_utc Γöé utc_t * Γöé utc Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé ems_c_attr_severity Γöé ems_severity_t Γöé severity Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé ems_c_attr_acl Γöé sec_acl_t* Γöé acl Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé ems_c_attr_byte_string Γöé idl_byte * Γöé byte_string Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé ems_c_attr_char_string Γöé idl_char * Γöé char_string Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé ems_c_attr_bytes Γöé ems_bytes_t Γöé bytes Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
Byte strings and character strings are terminated with a 0 (zero)
byte. The pickling service of the IDL compiler can be used to encode
complex data types into byte strings that are to be included in an
EMS event.
ems_bytes_t A data type to define data stored as bytes. This type contains two
fields:
size An integer of type unsigned32 that indicates the size
of the byte data.
data The byte data.
ems_attr_value_t A self-defining data structure that has an attribute type
specifier (format) that tells what type of data is in the union, and
then appropriate union members to hold the value of the data
specified. The format field is of type ems_attr_type_t, and can
contain only one of the tagged union fields described in Event
Attribute Type Specifiers
ems_attribute_t A structure that contains an event attribute name/type pair
that defines an event attribute. The ems_event_tdata type contains
an array of ems_attribute_t structures. Event attributes can be used
in defining the event types in event type schemas, and in defining
event filters in event filter expressions. The ems_attribute_t data
type contains two fields:
attr_name A name of type ems_string that specifies the
attribute name
attr_type A value of type ems_attr_value_t that specifies
the format of the attribute value
ΓòÉΓòÉΓòÉ 9.1.2. EMS Event Structure ΓòÉΓòÉΓòÉ
The following data types define an event:
ems_event_type_t A variable that defines the type of event. Events can have
one of two default types:
ems_c_generic_type Generic
ems_c_svc_type SVC
Events of type generic do not have event type schemas associated
with them, and can only be filtered by expressions with header
attributes in them. This is a uuid_t data type. To examine the value
in this variable, use the uuid_compare routine.
ems_eventid_t A structure that contains the unique identifier for an event.
The event identifier contains the following fields:
type An event type of ems_event_type_t
id An identifier of type uuid_tthat is unique to a
specific event.
ems_netname_t A structure containing the network name of a given host machine.
ems_nameservice_t An enumerated data type that specifies the name service that
recognizes the given network name. The possible values are:
ems_ns_other The name service is other than listed.
ems_ns_dns DNS name service.
ems_ns_dce DCE CDS name Service, the only value supported
in this release.
ems_ns_x500 X500.
ems_ns_nis NIS.
ems_ns_sna SNA network.
ems_netaddr_t A structure that contains the network name. The name is
interpreted according to the name service specified in
ems_nameservice_t. The ems_netaddr_t structure contains the
following fields:
len An unsigned short integer containing the length of
the address
name The name, in an appropriate format. The name is of
type ems_octet_t, and is of length len. The
ems_octet_t data type is char.
For a DCE hostname, the following example sets the ems_netname_t
structure called netname:
static char * dce_hostname = "/.:/hosts/eagle.austin.ibm.com";
ems_netname_t netname;
netname.service = ems_ns_dce;
netname.netaddr->len = strlen( dce_hostname )+1;
netname.netaddr->name = (char *)malloc( netname.netaddr->len );
strcpy( netname.netaddr->name, dce_hostname );
ems_origin_t A structure that indicates where the event originated; that is,
the name of the host where the supplier is running, the name of the
supplier, and the supplier process identification. These values
might not be valid for all hosts. This structure contains the
following fields:
netname The network name of the originator host, of type
ems_netname_t.
descname The descriptive name of the supplier, of type char
*.
pid The process ID of the originator, of type
unsigned32. This ID is operating system-dependent.
uid The user ID of the originator, of type unsigned32.
This ID is operating system-dependent.
gid The group ID of the originator, of type unsigned32.
This ID is operating system-dependent.
ems_severity_t An enumerated variable that specifies the severity of the
event. The names have a one-to-one correspondence to DCE SVC
severity attribute values. (See the DCE for OS/2 Warp: Application
Development Guide - Core Components.) The event severity can have
one of the following values:
ems_sev_info Information event.
ems_sev_fatal Fatal event.
ems_sev_error Alert event.
ems_sev_warning Warning event.
ems_sev_notice Notice event.
ems_sev_notice_verbose Notice Verbose event.
ems_sev_debug Debug event.
ems_hdr_t A structure containing the header of the ems_event_t data structure.
The header contains the following fields:
eventid The event identifier, of type ems_eventid_t.
origin The event origin, of type ems_origin_t.
severity The event severity, of type ems_severity_t.
received A timestamp indicating the time the event was
received. This timestamp is of type utc_t and is set
by the EMS daemon.
delivered A timestamp indicating the time the event was
delivered to the consumer. This timestamp is of type
utc_t and is set by the consumer.
A set of filter attributes are provided for event header filtering.
The following names can be used for the filter attribute in an event
filter expression.
Attribute Name Attribute Type
eventid.id ems_c_attr_uuid
eventid.type ems_c_attr_uuid
origin.netname.service ems_c_attr_ulong
origin.netname.netaddr ems_c_attr_bytes
origin.descname ems_c_attr_char_string
origin.pid ems_c_attr_ulong
origin.uid ems_c_attr_ulong
origin.gid ems_c_attr_ulong
severity ems_c_attr_ulong
received ems_c_attr_utc
ems_event_t A structure containing a fixed header and a variable array. The
fields are as follows:
header The event header, a structure of type ems_hdr_t.
count An integer of type unsigned32, which contains the
number of data items in the item array.
item[] An array of size count, containing ems_attribute_t
attributes. Each data item is a self-defining value
that contains an attribute type and attribute data.
ΓòÉΓòÉΓòÉ 9.1.3. Event Types ΓòÉΓòÉΓòÉ
The EMS event type structures are used to define the EMS event types.
ems_event_type_schema_t A structure that is used to define an event type. The
event type schema specifies only the fixed part of an event.
Although the fixed part of an event must match the event type
schema, the event can have additional attributes that are unnamed in
the schema. The ems_event_type_schema_t structure contains the
following list of attributes:
type A structure of type ems_event_type_t containing an
event type ID.
name A pointer to a character string that specifies the
name of the event type.
size A long integer that contains the number of attributes
in the attribute array.
attribute[] An array of event type attributes of type
ems_attribute_t describing the format of this event
type. This array has size elements.
ems_event_type_list_t A structure that contains a list of event type schemas.
The structure contains the following fields:
size A long integer containing the number of event type
schemas.
schema[] An array of size size of type ems_schema_ptr_t, which
is defined as:
typedef [ptr] ems_event_schema_t *ems_schema_ptr_t;
ΓòÉΓòÉΓòÉ 9.1.4. EMS Event Filters ΓòÉΓòÉΓòÉ
The event filter data structures allow the definition of both event filters,
and event filter lists.
ems_attr_op_t The attribute operator part of an event filter expression.
Attribute operators define the boolean operation to perform on the
attribute name and attribute value in an event filter expression.
The possible attribute operators are:
Attribute Operator Description
ems_c_attr_op_eq The attr_name is equal (==) to
attr_value.
ems_c_attr_op_gt The attr_name is greater than (>)
attr_value.
ems_c_attr_op_lt The attr_name is less than (<)
attr_value.
ems_c_attr_op_ge The attr_name is greater than or equal
(>=) to attr_value.
ems_c_attr_op_le The attr_name is less than or equal
(<=) to attr_value.
ems_c_attr_op_ne The attr_name is not equal (<>) to
attr_value.
ems_c_attr_op_substr The attr_name contains the string
value specified by attr_value.
ems_c_attr_op_bitand The attr_name that is bitwise ANDed
with attr_value is greater than 0.
ems_filter_exp_t A structure containing an event filter expression. This
structure contains the elements that are used to build an event
filter. Event filter expressions contain an attribute name, an
operator, and a value that define a boolean filter expression. The
fields are:
attr_name A pointer to a character string that contains
the attribute name.
attr_operator An attribute operator of type ems_attr_op_t.
attr_value An attribute value of type ems_attr_value_t.
Filter Expression Operator Table describes what filter operators are
valid with each attribute type.
ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
Γöé Table 19. Filter Expression Operator Table Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé DATA TYPE Γöé EQ Γöé GT Γöé LT Γöé GE Γöé LE Γöé NE Γöé BITANDΓöé SUBSTRΓöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé small int Γöé YES Γöé YES Γöé YES Γöé YES Γöé YES Γöé YES Γöé Γöé Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé short int Γöé YES Γöé YES Γöé YES Γöé YES Γöé YES Γöé YES Γöé Γöé Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé long int Γöé YES Γöé YES Γöé YES Γöé YES Γöé YES Γöé YES Γöé Γöé Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé hyper int Γöé YES Γöé YES Γöé YES Γöé YES Γöé YES Γöé YES Γöé Γöé Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé usmall int Γöé YES Γöé YES Γöé YES Γöé YES Γöé YES Γöé YES Γöé Γöé Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé ushort int Γöé YES Γöé YES Γöé YES Γöé YES Γöé YES Γöé YES Γöé Γöé Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé ulong int Γöé YES Γöé YES Γöé YES Γöé YES Γöé YES Γöé YES Γöé Γöé Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé uhyper int Γöé YES Γöé YES Γöé YES Γöé YES Γöé YES Γöé YES Γöé Γöé Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé short float Γöé YES Γöé YES Γöé YES Γöé YES Γöé YES Γöé YES Γöé Γöé Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé long float Γöé YES Γöé YES Γöé YES Γöé YES Γöé YES Γöé YES Γöé Γöé Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé boolean Γöé YES Γöé Γöé Γöé Γöé Γöé YES Γöé Γöé Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé uuid Γöé YES Γöé YES Γöé YES Γöé YES Γöé YES Γöé YES Γöé Γöé Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé utc Γöé YES Γöé YES Γöé YES Γöé YES Γöé YES Γöé YES Γöé Γöé Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé severity Γöé YES Γöé Γöé Γöé Γöé Γöé YES Γöé Γöé Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé acl Γöé YES Γöé Γöé Γöé Γöé Γöé YES Γöé Γöé Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé byte string Γöé YES Γöé Γöé Γöé Γöé Γöé YES Γöé YES Γöé Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé char string Γöé YES Γöé YES Γöé YES Γöé YES Γöé YES Γöé YES Γöé Γöé YES Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé bytes Γöé YES Γöé Γöé Γöé Γöé Γöé YES Γöé YES Γöé Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
ems_filter_exp_list_t A structure containing a list of event filter
expressions. This structure groups filter expressions together in a
list to form an ANDed filter expression used to define an event
filter. The structure contains the following fields:
size A long integer indicating the number of filter
expressions in the filter_exps array.
filter_exps[] An array of filter expressions of type
ems_filter_exp_t.
ems_filter_t An event filter specifies a series of event filter expressions
that will be ANDed together to perform a filter operation. The event
filter structure contains the following fields:
filter_name The event filter name, which will be entered in
the CDS name space. This name is of type
ems_string_t.
type A structure of type ems_event_type_t that
contains the type of event filter.
filter_exp_list A list of filter expressions of type
ems_filter_exp_list_t.
Filters with an event type of generic can only have filter
expressions with header attribute names in them. (See the event
header attributes listed in ems_hdr_t.)
The following example illustrates how to create a filter:
/*------------------------------------------------*
* Create a filter that specifies all the events *
* received between 1 and 2 AM GMT. *
*------------------------------------------------*/
ems_filter_exp_list_t * el = (ems_filter_exp_list_t *)
malloc(sizeof(ems_filter_exp_list_t)+(1*sizeof(ems_filter_exp_t));
el->size = 0;
el->filllter_exps[el->size].attr_name = (unsigned char *)"received.tod";
el->filter_exps[el->size].attr_operator = ems_c_attr_op_le;
el->filter_exps[el->size].attr_value.format = ems_c_attr_char_string;
el->filter_exps[el->size].attr_value.tagged_union.char_string = "0200";
el->size++;
el->filter_exps[el->size].attr_name = (unsigned char *)"received.tod";
el->filter_exps[el->size].attr_operator = ems_c_attr_op_gt;
el->filter_exps[el->size].attr_value.format = ems_c_attr_char_string;
el->filter_exps[el->size].attr_value.tagged_union.char_string = "0100";
el->size++;
ems_string_t A pointer to a character string used to describe filter names.
ems_filtername_list_t A structure containing a list of event filter names.
This event filter list contains the following fields:
size A long integer that contains the number of names
in the filter_names array.
filter_names[] An array containing event filter names of type
ems_string_t.
ems_filter_list_t A structure that contains an event filter list. The
structure contains the following fields:
size A long integer that contains the number of event
filters in the filters array.
filters[] An array of pointers to ems_filter_t structures that
describe filters.
ΓòÉΓòÉΓòÉ 9.1.5. EMS Consumer Data Structures ΓòÉΓòÉΓòÉ
These data structures make up the Consumer database in EMS.
ems_consumer_t A structure that defines an EMS consumer. Each consumer has the
following fields:
name A character string containing the DCE name of the
consumer, which is entered in CDS.
hostname The DCE host name where the consumer is running, of
type ems_netname_t.
uuid A uuid_t identifier unique to that consumer.
ems_consumer_list_t A structure that contains a list of consumer entries. The
structure has the following fields:
size A long integer containing the number of entries
in the consumer array.
consumer[] An array of ems_consumer_t structures that
contain consumer information.
ΓòÉΓòÉΓòÉ 9.1.6. EMS Server Data Structure ΓòÉΓòÉΓòÉ
ems_attrlist_t The attribute list data structure defines a list of server
attributes. Each attribute is a value maintained by an emsd server.
The attribute list can be used to query those values. The attribute
list contains the following fields:
size A long integer describing the number of attributes in
the attr array.
attr[] An array of event type attributes of type
ems_attribute_t.
ΓòÉΓòÉΓòÉ 9.2. EMS Registration Routines ΓòÉΓòÉΓòÉ
The EMS API allows event suppliers and consumers to register with the EMS
daemon. The EMS registration step provides a handle that is used for all future
EMS operations. The registration step is required for all event suppliers and
management applications. The following routines allow suppliers and management
applications to register with the EMS daemon:
ems_register Obtains an EMS handle for future calls to EMS
routines.
ems_unregister Frees the resources obtained by a call to
ems_register.
ΓòÉΓòÉΓòÉ 9.3. EMS Event Type Routines ΓòÉΓòÉΓòÉ
The EMS API allows event suppliers and consumers to get a list of event types
from the EMS daemon. All events processed by the event service have an event
type. Event types can be either generic or defined by an event type schema. The
formats of EMS event types are defined by event type schemas, and are kept in
the EMS Event Type database.
A consumer can request a list of supported event types, and select the event
types it wants to receive by using the event type schemas to construct event
filters, and to map event data according to attribute names. For example, an
event consumer can reconstruct an SVC message by using the attribute names to
find the correct data items.
Suppliers use event type schemas to define new event types that they intend to
produce. EMS uses the event type schemas to apply event filters to events.
The event service keeps a database of event types that consists of event type
schemas. The following routines allow you to manipulate the event types in the
event type database:
ems_event_type_free_list Frees the list of event type schemas.
ems_event_type_get_list Gets a list of event type schemas from the
Event Type Database.
ΓòÉΓòÉΓòÉ 9.4. EMS Supplier Routine ΓòÉΓòÉΓòÉ
The following routine allows event suppliers to send events to the EMS daemon:
ems_supplier_send Sends an event to EMS.
ΓòÉΓòÉΓòÉ 9.5. EMS Event Filter Routines ΓòÉΓòÉΓòÉ
Filters are the mechanism used by suppliers and consumers to control which
events are sent through the event channel. Filtering is applied by the EMS
daemon before forwarding events to consumers. The EMS API supports filtering by
allowing event suppliers, consumers, and system administrators to manipulate
the EMS Event Filter database. The event filter routines are as follows:
ems_filter_add Adds a filter to the Event Filter Database.
ems_filter_append Appends filter expressions to the Event Filter
Database.
ems_filter_get Gets the contents of an event filter.
ems_filter_delete Deletes a filter from the Event Filter
Database.
ems_filter_get_namelist Gets a list of the names of all filters in the
Event Filter Database.
ems_filter_free Frees an event filter.
ems_filter_free_namelist Frees a list of event filter names.
ems_filter_get_list Gets a list of all the filters in the Event
Filter Database.
ems_filter_free_list Frees the list of filters.
ΓòÉΓòÉΓòÉ 9.6. EMS Consumer Routines ΓòÉΓòÉΓòÉ
All event consumers must call the EMS event consumer setup routines before
receiving EMS events. In DCE terms, EMS event consumers are both clients and
servers. The following steps are required to implement an event consumer:
1. Set up as a DCE server.
2. Register an event handler with the EMS daemon to receive events.
3. Register with the EMS daemon.
4. Create filters to control the events forwarded from the daemon.
5. Start listening for events.
The EMS daemon maintains a consumer database to keep track of all registered
consumers. Registering and unregistering with the EMS daemon adds and deletes
consumers to and from the database.
The following routines set up the consumers using DCE RPC, and set up the
event handler routines.
ems_add_filter_to_group Adds a filter name to a consumers event filter
group.
ems_consumer_handler_register Registers a consumers event handler.
ems_consumer_register Registers a consumer with EMS.
ems_consumer_start Starts an event consumer.
ems_consumer_stop Stops an event consumer.
ems_consumer_unregister Unregisters a consumer with EMS.
ems_delete_filter_from_group Deletes a filter name from a consumers event
filter group.
ems_get_filter_group Gets the list of filter names that comprise a
consumers event filter group.
ΓòÉΓòÉΓòÉ 9.7. EMS Management Routines ΓòÉΓòÉΓòÉ
The EMS Management interface provides a means to manage various aspects of EMS.
Using this interface, applications can manage event consumers, event filters,
and the EMS event log. System administrators can also use dcecp to manage the
same set of resources.
EMS also offers an interface to the EMS event log. This interface allows
management applications to manipulate event logs. The log interface is a local
interface only, and can only be run on the machine that runs the emsd server.
The EMS event log is used to store events in case of EMS failures. EMS writes
all events to the event log, and deletes the event record once the event has
been transmitted to all consumers that are supposed to get the event. The event
log is kept in a file on the machine where emsd is running. Routines are
provided to examine local event logs.
ems_mgmt_free_attributes Frees a list of emsd server attributes.
ems_mgmt_free_consumers Frees a list of consumers obtained from
ems_mgmt_list_consumers.
ems_mgmt_free_ems Frees a list of EMS host names obtained
from ems_mgmt_list_ems.
ems_mgmt_list_ems Lists all hosts running emsds.
ems_mgmt_list_attributes Lists attributes for a specific emsd.
ems_mgmt_list_consumers Lists consumers registered with EMS.
ems_mgmt_delete_consumer Deletes a consumer from the Consumer
Database.
ems_mgmt_delete_filter_from_group Deletes a filter name from a consumers
filter group.
ems_mgmt_add_filter_to_group Adds a filter name to a consumers filter
group.
ems_mgmt_get_filter_group Gets the list of names in a consumers
filter group.
ems_log_open Opens an EMS event log.
ems_log_read Reads events from an EMS event log.
ems_log_close Closes an EMS event log.
ems_log_rewind Rewinds an EMS event log.
ΓòÉΓòÉΓòÉ 9.7.1. ems_add_filter_to_group ΓòÉΓòÉΓòÉ
Purpose
Adds an event filter to a group.
Format
#include <dce/ems.h>
void ems_add_filter_to_group(
ems_handle_t handle,
ems_filtername_list_t *event_filters,
error_status_t *status);
Parameters
Input
handle Must contain a valid consumer handle obtained from
ems_consumer_register.
event_filters A pointer to a list of one or more event filter names
to add to this consumer's event filter group. Consumers
can use the names of new event filters after building
them with the ems_filter_add routine, or existing
filters that can be obtained by using the
ems_filter_get_namelist routine.
Output
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, the routine returns one of the following
error codes:
ems_s_insufficient_permission The routine does not
have permission to
perform the
operation.
ems_s_filter_list_empty event_filters
contains no event
filter names.
ems_s_filtername_exists An event filter in
event_filters
already exists in
the consumer's event
filter group.
ems_s_no_memory Error allocating
memory
ems_s_invalid_handle The handle is not
valid.
ems_s_invalid_name A filter, consumer,
or filter attribute
name that contains
characters that are
not valid was
specified.
Usage
The ems_add_filter_to_group routine is used by EMS event consumers to
add event filter names to a consumer's event filter group. This
routine can be called multiple times for each consumer.
Permissions Required
(w) on /.:/hosts/dce_hostname/ems-server/consumers
ΓòÉΓòÉΓòÉ 9.7.2. ems_consumer_handler_register ΓòÉΓòÉΓòÉ
Purpose
Registers a consumer event handler.
Format
#include <dce/ems.h>
void ems_consumer_handler_register(
ems_handler_t hfunc,
error_status_t *status);
Parameters
Input
hfunc Specifies the name of the event handler function. The
handler's signature should be:
typedef void (*ems_handler_t) (
ems_event_t *event,
error_status_t *status);
Output
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, the routine returns one of the following
error codes:
ems_s_no_memory Error allocating
memory.
ems_s_mutex_init Error initializing
event queue.
ems_s_cond_variable_init Error initializing
event queue.
ems_s_pthread_create Error initializing
event queue.
ems_s_consumer_not_started Event consumer has
not been started.
Usage
The ems_consumer_handler_register routine declares the event
consumer's event handler. The event consumer developer is responsible
for providing the handler to process events.
This routine does not make any RPC calls to EMS.
ΓòÉΓòÉΓòÉ 9.7.3. ems_consumer_register ΓòÉΓòÉΓòÉ
Purpose
Registers a consumer.
Format
#include <dce/ems.h>
void ems_consumer_register(
ems_netname_t *dce_hostname,
ems_filtername_list_t *filter_group,
ems_handle_t *handle,
error_status_t *status); /* register status */
Parameters
Input
dce_hostname A pointer to the name of the DCE host machine where
emsd is running. If the DCE host name is NULL, then the
local host is assumed.
Note: dce_hostname is case sensitive.
filter_group A pointer to a list of event filter names that define
this consumer's initial event filter group. If
filter_group is empty, no filter group is specified,
and EMS will not forward any events to this consumer
until the consumer makes a call to
ems_add_event_to_group.
Output
handle Returns an EMS handle that can be used on subsequent
calls to EMS routines.
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns one of the following status
codes:
ems_s_no_memory Error allocating
memory.
ems_s_already_registered Consumer with this
name already
registered.
ems_s_mutex_init Error initializing
event queue.
ems_s_cond_variable_init Error initializing
event queue.
ems_s_pthread_create Error initializing
event queue.
ems_s_insufficient_permission No permission to
perform the
requested
operation.
ems_s_consumer_not_started Event consumer has
not been started.
ems_s_unsupported_nameservice Nameservice is not
supported.
Usage
The ems_consumer_register routine is used by EMS event consumers to
register with EMS. This routine should be called once for each DCE
host from which this consumer wants to receive events. This routine
must be called after a call to ems_consumer_start.
Permissions Required
(i) on /.:/hosts/dce_hostname/ems-server/consumers
ΓòÉΓòÉΓòÉ 9.7.4. ems_consumer_start ΓòÉΓòÉΓòÉ
Purpose
Starts a consumer.
Format
#include <dce/ems.h>
void ems_consumer_start(
char *consumer,
unsigned32 flags,
error_status_t *status);
Parameters
Input
consumer A pointer to the consumer name. This name must be
unique, and is registered in the CDS namespace under
/.:/hosts/dce_hostname/ems/consumers. The name is used
by the administrative interface to refer to this
consumer.
flags Reserved for future use.
Output
status A pointer to the completion status. Upon successful
completion, the routine returns error_status_ok.
Otherwise, it returns one of the following error codes:
ems_s_no_memory Error allocating
memory.
ems_s_consumer_already_started consumer already
started.
ems_s_invalid_name A filter,
consumer, or
filter attribute
name that contains
characters that
are not valid was
specified.
Usage
The ems_consumer_start routine should be called at the beginning of
each event consumer before making any register calls. It creates an
object UUID to uniquely identify this event consumer and register its
endpoint so that EMS can send this consumer event data.
This routine does not make any RPCs to EMS.
ΓòÉΓòÉΓòÉ 9.7.5. ems_consumer_stop ΓòÉΓòÉΓòÉ
Purpose
Stops a consumer.
Format
#include <dce/ems.h>
void ems_consumer_stop(
error_status_t *status);
Parameters
Output
status A pointer to the completion status. On successful
completion the routine returns error_status_ok.
Otherwise, it returns ems_s_consumer_not_started, which
indicates that the specified event consumer has not
been started.
Usage
The ems_consumer_stop routine should be called at the end of each
event consumer after a call to ems_s_consumer_start. It unregisters
the endpoint of this event consumer and kills the thread that was
created by the consumer's event handler interface to receive all
events from EMS.
This routine does not make any RPCs to EMS.
ΓòÉΓòÉΓòÉ 9.7.6. ems_consumer_unregister ΓòÉΓòÉΓòÉ
Purpose
Unregisters a consumer.
Format
#include <dce/ems.h>
void ems_consumer_unregister(
ems_handle_t *handle,
error_status_t *status);
Parameters
Input
handle A handle returned from a call to ems_consumer_register.
This routine frees memory used by handle, and sets
handle to NULL.
Output
status A pointer to the completion status. Upon successful
completion, this routine returns error_status_ok.
Otherwise, it returns one of the following error codes:
ems_s_unknown_consumer Tried to unregister
a consumer that was
not registered.
ems_s_consumer_not_started Consumer has not
been started.
ems_s_insufficient_permission No permission to
perform the
requested operation.
ems_s_invalid_handle The handle is not
valid.
Usage
The ems_consumer_unregister routine is used by EMS event consumers to
unregister with EMS. This routine should be called once for each call
to ems_consumer_register. The event consumer should call this routine
before calling the ems_consumer_stop routine.
Permissions Required
(d) on /.:/hosts/dce_hostname/ems-server/consumers
ΓòÉΓòÉΓòÉ 9.7.7. ems_delete_filter_from_group ΓòÉΓòÉΓòÉ
Purpose
Deletes an event filter from a group.
Format
#include <dce/ems.h>
void ems_delete_filter_from_group(
ems_handle_t handle,
ems_filtername_list_t *filter_name,
error_status_t *status);
Parameters
Input
handle Must contain a valid consumer handle obtained from
ems_consumer_register.
filter_name A pointer to the event filter names to delete from the
consumer's event filter group.
Output
status A pointer to the completion status. Upon successful
completion, this routine returns error_status_ok.
Otherwise, it returns one of the following error codes:
ems_s_filter_list_empty No filter names were
specified for
deletion.
ems_s_filtername_not_there Specified filter
name to delete not
in group.
ems_s_no_memory Error allocating
memory.
ems_s_insufficient_permission No permission to
perform the
requested operation.
ems_s_invalid_handle The handle is not
valid.
ems_s_invalid_name A filter, consumer,
or filter attribute
name that contains
characters that are
not valid was
specified.
Usage
The ems_delete_filter_from_group routine is used by EMS event
consumers to delete event filter names from consumer event filter
groups.
Permissions Required
(w) on /.:/hosts/dce_hostname/ems-server/consumers
ΓòÉΓòÉΓòÉ 9.7.8. ems_event_type_free_list ΓòÉΓòÉΓòÉ
Purpose
Frees an event type list.
Format
#include <dce/ems.h>
void ems_event_type_free_list(
ems_event_type_list_t **type_list,
error_status_t *status);
Parameters
Input
type_list A pointer to an event type list as returned by
ems_event_type_get_list. This routine sets type_list to
NULL.
Output
status A pointer to the completion status. Upon successful
completion, this routine returns error_status_ok.
Usage
The ems_event_type_free_list routine is used by callers of
ems_get_event_types to free the storage used by an event type list.
ΓòÉΓòÉΓòÉ 9.7.9. ems_event_type_get_list ΓòÉΓòÉΓòÉ
Purpose
Gets an event types list.
Format
#include <dce/ems.h>
void ems_event_type_get_list(
ems_handle_t handle,
ems_event_type_list_t **type_list,
error_status_t *status);
Parameters
Input
handle The handle returned from a call to
ems_consumer_register.
Output
type_list Returns the list of available event types.
status A pointer to the completion status. Upon successful
completion, this routine returns error_status_ok.
Otherwise, it returns one of the following error codes:
ems_s_no_type_list There is no event
type list available.
ems_s_no_memory Error allocating
memory.
ems_s_insufficient_permission No permission to
perform the
requested operation.
ems_s_invalid_handle The handle is not
valid.
Usage
The ems_event_type_get_list routine is used by EMS event consumers to
find out what event types are available to register for. The consumer
can then set up filters for attributes in one of the available event
types.
Permissions Required
(r) on /.:/hosts/dce_hostname/ems-server/event-types
ΓòÉΓòÉΓòÉ 9.7.10. ems_filter_add ΓòÉΓòÉΓòÉ
Purpose
Adds an event filter.
Format
#include <dce/ems.h>
void ems_filter_add(
ems_handle_t handle,
ems_string_t filter_name,
ems_event_type_t type,
ems_filter_exp_list_t *exp_list
error_status_t *status);
Parameters
Input
handle A handle returned from a call to ems_consumer_register.
filter_name Specifies the event filter name for this event filter.
This name can be used to add the event filter to a
consumer's event filter group.
type Specifies the event type that this filter is applied
against.
exp_list Pointer to a list of filter expressions that are part
of the event filter filter_name.
Output
status A pointer to the completion status. Upon successful
completion, this routine returns error_status_ok.
Otherwise it returns one of the following error codes:
ems_s_filter_exists The given filter
name already exists.
ems_s_invalid_filter The input parameter
specifies an invalid
filter.
ems_s_insufficient_permission No permission to
perform the
requested operation.
ems_s_invalid_handle The handle is not
valid.
ems_s_invalid_name A filter, consumer,
or filter attribute
name that contains
characters that are
not valid was
specified.
Usage
The ems_filter_add routine is used to add a new event filter to the
EMS Event Filter Database.
Permissions Required
(i) on /.:/hosts/dce_hostname/ems-server/filters
ΓòÉΓòÉΓòÉ 9.7.11. ems_filter_append ΓòÉΓòÉΓòÉ
Purpose
Appends to an event filter.
Format
#include <dce/ems.h>
void ems_filter_append(
ems_handle_t handle,
ems_string_t filter_name,
ems_filter_exp_list_t *exp_list,
error_status_t *status);
Parameters
Input
handle The handle returned from a call to
ems_consumer_register.
filter_name Specifies the name of the event filter to add the
filter expressions to.
exp_list A list of filter expressions that will be added to the
end of event filter filter_name.
Output
status A pointer to the completion status. Upon successful
completion, this routine returns error_status_ok.
Otherwise, it returns one of the following error codes:
ems_s_invalid_filter The input parameter
specifies an invalid
filter.
ems_s_filter_not_found The specified filter
was not found.
ems_s_insufficient_permission No permission for
the requested
operation.
ems_s_invalid_handle The handle is not
valid.
ems_s_invalid_name A filter, consumer,
or filter attribute
name that contains
characters that are
not valid was
specified.
Usage
The ems_filter_append routine is used to add filter expressions to an
event filter. The filter expressions are added to the end of the
current list of filter expressions in the event filter.
Permissions Required
(w) on /.:/hosts/dce_hostname/ems-server/filters/filter_name
ΓòÉΓòÉΓòÉ 9.7.12. ems_filter_delete ΓòÉΓòÉΓòÉ
Purpose
Deletes an event filter.
Format
#include <dce/ems.h>
void ems_filter_delete(
ems_handle_t handle,
ems_string_t filter_name,
error_status_t *status);
Parameters
Input
handle The handle returned from a call to
ems_consumer_register.
filter_name Specifies the name of the event filter to delete.
Output
status A pointer to the completion status. Upon successful
completion, this routine returns error_status_ok.
Otherwise, it returns one of the following error codes:
ems_s_filter_not_found The specified filter
name was not found in
the filter database.
ems_s_filter_in_use The specified filter
name appears in a
consumer's event
filter group.
ems_s_insufficient_permission No permission for
the requested
operation.
ems_s_invalid_handle The handle is not
valid.
ems_s_invalid_name A filter, consumer,
or filter attribute
name that contains
characters that are
not valid was
specified.
Usage
The ems_filter_delete routine is used to delete an event filter from
the Event Filter Database. The name filter_name cannot appear in any
consumer's event filter group when this routine is called.
Permissions Required
(d) on /.:/hosts/dce_hostname/ems-server/filters/filter_name, or
(d) on /.:/hosts/dce_hostname/ems-server/filters
ΓòÉΓòÉΓòÉ 9.7.13. ems_filter_free ΓòÉΓòÉΓòÉ
Purpose
Frees an event filter.
Format
#include <dce/ems.h>
void ems_filter_free(
ems_filter_exp_list_t **exp_list,
error_status_t *status);
Parameters
Input
exp_list A pointer to a list of filter expressions to free.
Output
status A pointer to the completion status. Upon successful
completion, this routine returns error_status_ok.
Otherwise, it returns an error.
Usage
The ems_filter_free routine is used to free a list of event filter
expressions obtained by a call to the ems_filter_get routine.
ΓòÉΓòÉΓòÉ 9.7.14. ems_filter_free_list ΓòÉΓòÉΓòÉ
Purpose
Frees an event filter list.
Format
#include <dce/ems.h>
void ems_filter_free_list(
ems_filter_list_t **filter_list,
error_status_t *status);
Parameters
Input/Output
filter_list A pointer to a list of event filters that make up the
Event Filter Database as returned by the routine
ems_filter_get_list. On output, filter_list is set to
NULL.
Output
status A pointer to the completion status. Upon successful
completion, this routine returns error_status_ok.
Usage
The ems_filter_free_list routine is used by callers of
ems_get_event_filter_database to free the storage used by an Event
Filter Database (ems_filter_db_t) structure.
ΓòÉΓòÉΓòÉ 9.7.15. ems_filter_free_namelist ΓòÉΓòÉΓòÉ
Purpose
Frees a list of event filter names.
Format
#include <dce/ems.h>
void ems_filter_free_namelist(
ems_filtername_list_t **name_list,
error_status_t *status);
Parameters
Input
name_list A pointer to a list of filter names to free.
Output
status A pointer to the completion status. Upon successful
completion, this routine returns error_status_ok.
Otherwise, it returns an error.
Usage
The ems_filter_free_namelist routine is used to free a list of filter
names returned by various routines. The routines that return a list
of filter names are:
ems_filter_get_namelist
ems_get_filter_group
ems_mgmt_get_filter_group
ΓòÉΓòÉΓòÉ 9.7.16. ems_filter_get ΓòÉΓòÉΓòÉ
Purpose
Gets an event filter.
Format
#include <dce/ems.h>
void ems_filter_get(
ems_handle_t handle,
ems_string_t filter_name,
ems_event_type_t *filter_type,
ems_filter_exp_list_t **exp_list,
error_status_t *status);
Parameters
Input
handle The handle returned from a call to
ems_consumer_register.
filter_name Specifies the name of the event filter to get.
Output
filter_type Specifies the event type of the filter.
exp_list A pointer to the list of filter expressions that are
part of event filter filter_name.
status A pointer to the completion status. Upon successful
completion, this routine returns error_status_ok.
Otherwise, it returns one of the following error codes:
ems_s_filter_not_found The specified filter
name was not found
in the filter
database.
ems_s_insufficient_permission No permission for
the requested
operation.
ems_s_invalid_handle The handle is not
valid.
ems_s_invalid_name A filter, consumer,
or filter attribute
name that contains
characters that are
not valid was
specified.
Usage
The ems_filter_get routine is used to get the filter expressions in
an event filter.
Permissions Required
(r) on /.:/hosts/dce_hostname/ems-server/filters
ΓòÉΓòÉΓòÉ 9.7.17. ems_filter_get_list ΓòÉΓòÉΓòÉ
Purpose
Gets event filter list.
Format
#include <dce/ems.h>
void ems_filter_get_list(
ems_handle_t handle,
ems_filter_list_t **filter_list,
error_status_t *status);
Parameters
Input
handle A handle returned from a call to ems_consumer_register.
Output
filter_list A pointer to a list of all the event filters in the
Event Filter Database.
status A pointer to the completion code. Upon successful
completion, this routine returns error_status_ok.
Otherwise, it returns one of the following error codes:
ems_s_empty_filter_db No filters in
database.
ems_s_insufficient_permission No permission for
the requested
operation.
ems_s_invalid_handle The handle is not
valid.
ems_s_invalid_name A filter, consumer,
or filter attribute
name that contains
characters that are
not valid was
specified.
Usage
The ems_filter_get_list routine is used to get a list of the event
filters in the Event Filter Database. This list should be freed using
ems_filter_free_list.
Permissions Required
(r) on /.:/hosts/dce_hostname/ems-server/filters/filter_name
ΓòÉΓòÉΓòÉ 9.7.18. ems_filter_get_namelist ΓòÉΓòÉΓòÉ
Purpose
Lists event filter names.
Format
#include <dce/ems.h>
void ems_filter_get_namelist(
ems_handle_t handle,
ems_filtername_list_t **name_list,
error_status_t *status);
Parameters
Input
handle The handle returned from a call to
ems_consumer_register.
Output
name_list A pointer to a list of all the event filter names in
the Event Filter Database. The routine
ems_event_filter_get can be used to find out the
contents of each event filter.
status A pointer to the completion status. Upon successful
completion, this routine returns error_status_ok.
Otherwise, it returns one of the following error codes:
ems_s_empty_filter_db No filters in
database.
ems_s_insufficient_permission No permission for
the requested
operation.
ems_s_invalid_handle The handle is not
valid.
Usage
The ems_filter_get_namelist routine is used to get a list of the
names of the event filters in the Event Filter Database.
Permissions Required
(r) on /.:/hosts/dce_hostname/ems-server/filters
ΓòÉΓòÉΓòÉ 9.7.19. ems_get_filter_group ΓòÉΓòÉΓòÉ
Purpose
Gets a filter group.
Format
#include <dce/ems.h>
void ems_get_filter_group(
ems_handle_t handle,
ems_filtername_list_t **filter_group,
error_status_t *status);
Parameters
Input
handle Must contain a valid consumer handle obtained from
ems_consumer_register.
Output
filter_group A pointer to the list of event filter names that are in
the consumer's event filter group.
status A pointer to the completion status. Upon successful
completion, this routine returns error_status_ok.
Otherwise, it returns one of the following error codes:
ems_s_invalid_handle Invalid handle.
ems_s_insufficient_permission No permission to
perform the
requested operation.
ems_s_consumer_not_found The specified
consumer is not
registered.
Usage
The ems_get_filter_group routine returns a list of event filter names
that comprise the consumer's event filter group. It is up to the
requesting consumer to free the storage allocated for filter_group.
Permissions Required
(r) on /.:/hosts/dce_hostname/ems-server/consumers
ΓòÉΓòÉΓòÉ 9.7.20. ems_log_close ΓòÉΓòÉΓòÉ
Purpose
Closes event log.
Format
#include <dce/ems.h>
void ems_log_close(
ems_log_file_t *handle,
error_status_t *status);
Parameters
Input/Output
handle Specifies the event log file to close. On output handle
is set to NULL.
Output
status A pointer to the completion status. Upon successful
completion, this routine returns error_status_ok.
Otherwise, it returns ems_s_invalid_log_handle, which
indicates that an invalid log file handle was passed
in.
Usage
The ems_log_close routine closes an event log file.
ΓòÉΓòÉΓòÉ 9.7.21. ems_log_open ΓòÉΓòÉΓòÉ
Purpose
Opens event log.
Format
#include <dce/ems.h>
void ems_log_open(
ems_log_file_t *log_file,
char *log_dir,
error_status_t *status);
Parameters
Input
log_dir Directory where log directory is located. If NULL, the
environment variable EMS_EVENTLOG_DIR is checked. If
EMS_EVENTLOG_DIR is not set, the default directory is
used.
Output
log_file Log handle to use in other ems_log_* routines.
status A pointer to the completion code. If the routine
completes successfully it returns error_status_ok.
Otherwise it returns one the following error codes:
ems_s_no_event_log Event log not found.
ems_s_no_log_entries No event log entries.
ems_s_no_memory Error allocating memory.
Usage
The ems_log_open routine opens an EMS event log and locks the event
log database until the ems_log_close routine is called.
ΓòÉΓòÉΓòÉ 9.7.22. ems_log_read ΓòÉΓòÉΓòÉ
Purpose
Read event log.
Format
#include <dce/ems.h>
void ems_log_read(
ems_log_file_t handle,
ems_event_t **event,
error_status_t *status);
Parameters
Input
handle Specifies the open event log to read from.
Output
event A pointer to the next event in the event log.
status A pointer to the completion status. Upon successful
completion, this routine returns error_status_ok.
Otherwise, it returns one of the following error codes:
ems_s_invalid_log_handle Invalid log file
handle passed in.
ems_s_no_more_events No more events to read
in log file.
Usage
The ems_log_read routine reads an event from the EMS event log.
ΓòÉΓòÉΓòÉ 9.7.23. ems_log_rewind ΓòÉΓòÉΓòÉ
Purpose
Rewinds event log.
Format
#include <dce/ems.h>
void ems_log_rewind(
ems_log_file_t handle,
error_status_t *status);
Parameters
Input
handle Specifies the event log file to rewind.
Output
status A pointer to the completion status. Upon successful
completion, this routine returns error_status_ok.
Otherwise, it returns one of the following error codes:
ems_s_invalid_log_handle An invalid log file
handle was passed in.
ems_s_no_log_entries No event log entries.
Usage
The ems_log_rewind routine rewinds an event log. This allows the
event log to be rewound to the beginning. This function is equivalent
to calling ems_log_close, then ems_log_open again.
ΓòÉΓòÉΓòÉ 9.7.24. ems_mgmt_add_filter_to_group ΓòÉΓòÉΓòÉ
Purpose
Adds a list of event filter names to an event filter group.
Format
#include <dce/ems.h>
void ems_mgmt_add_filter_to_group(
ems_handle_t handle,
char *consumer,
uuid_t *uuid,
ems_filtername_list_t *filter_name,
error_status_t *status);
Parameters
Input
handle Must contain a valid consumer handle obtained from the
ems_register routine.
consumer Specifies the consumer whose event filter group is
being updated.
uuid Specifies the consumer UUID that uniquely identifies
the consumer to clear. If this parameter is NULL, then
only one consumer can exist with the name consumer.
filter_name Specifies the list of event filter names to add.
Output
status A pointer to the completion status. Upon successful
completion, this routine returns error_status_ok.
Otherwise, it returns one of the following error codes:
ems_s_insufficient_permission No permission to
perform the
requested operation.
ems_s_invalid_handle An invalid handle
was passed.
ems_s_consumer_not_found The specified
consumer is not
registered.
ems_s_invalid_name A filter, consumer,
or filter attribute
name that contains
characters that are
not valid was
specified.
Usage
The ems_mgmt_add_filter_to_group routine adds event filter names to a
consumer's event filter group.
Permissions Required
(i) on /.:/hosts/dce_hostname/ems-server/consumers
ΓòÉΓòÉΓòÉ 9.7.25. ems_mgmt_delete_consumer ΓòÉΓòÉΓòÉ
Purpose
Deletes consumers.
Format
#include <dce/ems.h>
void ems_mgmt_delete_consumer(
ems_handle_t handle,
char *consumer,
uuid_t *uuid,
error_status_t *status);
Parameters
Input
handle Must contain a valid consumer handle obtained from the
ems_register routine.
consumer A pointer to the consumer name to clear. This name is
the name returned in the ems_consumer_list_t data
structure after calling ems_mgmt_list_consumers or the
name used on the ems_consumer_start routine.
uuid Specifies the consumer UUID that uniquely identifies
the consumer to clear. If this parameter is NULL, only
one consumer can exist with the name consumer.
Output
status A pointer to the completion status. Upon successful
completion, this routine returns error_status_ok.
Otherwise, it returns one of the following error codes:
ems_s_invalid_handle An invalid handle
was passed.
ems_s_consumer_not_found The specified
consumer is not
registered.
ems_s_insufficient_permission No permission for
the requested
operation.
ems_s_invalid_name A filter, consumer,
or filter attribute
name that contains
characters that are
not valid was
specified.
Usage
The ems_mgmt_delete_consumer routine clears all information stored in
EMS about the specified consumer. This means clearing the consumer's
filters, then unregistering the consumer. The consumer receives
notification that it is being deleted.
Permissions Required
(d) on /.:/hosts/dce_hostname/ems-server/consumers
ΓòÉΓòÉΓòÉ 9.7.26. ems_mgmt_delete_filter_from_group ΓòÉΓòÉΓòÉ
Purpose
Deletes event filter name from event filter group.
Format
#include <dce/ems.h>
void ems_mgmt_delete_filter_from_group(
ems_handle_t handle,
char *consumer,
uuid_t *uuid,
ems_filtername_list_t *filter_name,
error_status_t *status);
Parameters
Output
handle Must contain a valid consumer handle obtained from the
ems_register routine.
consumer A pointer to the consumer whose event filter group is
being updated.
uuid A pointer to the consumer UUID that uniquely identifies
the consumer to clear. If this parameter is NULL, then
only one consumer can exist with the name consumer.
filter_name A pointer to the names of the filters to delete from
the consumer's filter group.
Output
status A pointer to the completion status. Upon successful
completion, this routine returns error_status_ok.
Otherwise, it returns one of the following error codes:
ems_s_invalid_handle An invalid handle
was passed.
ems_s_consumer_not_found The specified
consumer is not
registered.
ems_s_insufficient_permission No permission for
the requested
operation.
ems_s_invalid_name A filter, consumer,
or filter attribute
name that contains
characters that are
not valid was
specified.
Usage
The ems_mgmt_delete_filter_from_group routine deletes the specified
event filter names from a consumer's event filter group.
Permissions Required
(w) on /.:/hosts/dce_hostname/ems-server/consumers
ΓòÉΓòÉΓòÉ 9.7.27. ems_mgmt_free_attributes ΓòÉΓòÉΓòÉ
Purpose
Frees a list of emsd server attributes.
Format
#include <dce/ems.h>
void ems_mgmt_free_attributes(
ems_attrlist_t **list,
error_status_t *status);
Parameters
Input
list A pointer to the list of attributes to free.
Output
status A pointer to the completion status. Upon successful
completion, this routine returns error_status_ok.
Otherwise, it returns an error.
Usage
The ems_mgmt_free_attributes routine frees a list of emsd server
attributes obtained by the ems_mgmt_list_attributes routine.
ΓòÉΓòÉΓòÉ 9.7.28. ems_mgmt_free_consumers ΓòÉΓòÉΓòÉ
Purpose
Frees a list of consumers obtained from ems_mgmt_list_consumers.
Format
#include <dce/ems.h>
void ems_mgmt_free_consumers(
ems_consumer_list_t **list,
error_status_t *status);
Parameters
Input
list A pointer to a list of consumers to free.
Output
status A pointer to the completion status. Upon successful
completion, this routine returns error_status_ok.
Otherwise, it returns an error.
Usage
The ems_mgmt_free_consumers routine frees a list of consumers
obtained from ems_mgmt_list_consumers.
ΓòÉΓòÉΓòÉ 9.7.29. ems_mgmt_free_ems ΓòÉΓòÉΓòÉ
Purpose
Frees a list of hosts obtained from ems_mgmt_list_ems.
Format
#include <dce/ems.h>
void ems_mgmt_free_ems(
char ***host_list,
error_status_t *status);
Parameters
Input
host_list A pointer to a list of hosts to free.
Output
status A pointer to the completion status. Upon successful
completion, this routine returns error_status_ok.
Otherwise, it returns an error.
Usage
The ems_mgmt_free_ems routine frees a list of consumers obtained from
ems_mgmt_list_ems.
ΓòÉΓòÉΓòÉ 9.7.30. ems_mgmt_get_filter_group ΓòÉΓòÉΓòÉ
Purpose
Gets a list of event filter names in an event filter group.
Format
#include <dce/ems.h>
void ems_mgmt_get_filter_group(
ems_handle_t handle,
char *consumer,
uuid_t *uuid,
ems_filtername_list_t **filter_group,
error_status_t *status);
Parameters
Input
handle Must contain a valid consumer handle obtained from the
ems_register routine.
consumer A pointer to the consumer's event filter group to
return. The consumer name is the name given to the
ems_start_consumer routine, or the name returned in the
ems_consumer_list_t data structure from the routine
ems_mgmt_list_consumers.
uuid A pointer to the consumer UUID that uniquely identifies
the consumer to clear. If this parameter is NULL, only
one consumer can exist with the name consumer.
Output
filter_group A pointer to the list of event filter names in the
specified consumer's event filter group.
status A pointer to the completion code. Upon successful
completion this routine returns error_status_ok.
Otherwise, it returns one of the following error codes:
ems_s_invalid_handle An invalid handle
was passed.
ems_s_consumer_not_found The specified
consumer is not
registered.
ems_s_insufficient_permission No permission for
the requested
operation.
ems_s_invalid_name A filter, consumer,
or filter attribute
name that contains
characters that are
not valid was
specified.
Usage
The ems_mgmt_get_filter_group routine returns a list of event filter
names in a consumer's event filter group.
Permissions Required
(i) on /.:/hosts/dce_hostname/ems-server/consumers
ΓòÉΓòÉΓòÉ 9.7.31. ems_mgmt_list_attributes ΓòÉΓòÉΓòÉ
Purpose
Lists emsd attributes.
Format
#include <dce/ems.h>
void ems_mgmt_list_attributes(
ems_handle_t handle,
ems_attrlist_t **list,
error_status_t *status);
Parameters
Input
handle Must contain a valid consumer handle obtained from the
ems_register routine.
Output
list A pointer to the list of emsd attributes.
status A pointer to the completion status. Upon successful
completion, this routine returns error_status_ok.
Otherwise, it returns one of the following error codes:
ems_s_insufficient_permission No permission to
perform the
requested operation.
ems_s_invalid_handle An invalid handle
was passed.
ems_s_no_memory Error allocating
memory.
Usage
The ems_mgmt_list_attributes routine lists emsd server attributes.
Free this list using the ems_mgmt_free_attributes routine.
Permissions Required
(r) on /.:/hosts/dce&ushostname/ems-server
ΓòÉΓòÉΓòÉ 9.7.32. ems_mgmt_list_consumers ΓòÉΓòÉΓòÉ
Purpose
Lists consumers.
Format
#include <dce/ems.h>
void ems_mgmt_list_consumers(
ems_handle_t handle,
ems_consumer_list_t **list,
error_status_t *status);
Parameters
Input
handle Must contain a valid consumer handle obtained from the
ems_register routine.
Output
list A pointer to the list of consumers.
status A pointer to the completion status. Upon successful
completion, this routine returns error_status_ok.
Otherwise it returns one of the following error codes:
ems_s_no_memory Error allocating
memory.
ems_s_no_consumers No consumers
registered.
ems_s_insufficient_permission No permission to
perform the
requested operation.
ems_s_invalid_handle An invalid handle
was passed.
Usage
The ems_mgmt_list_consumers routine lists consumers registered with
EMS.
Permissions Required
(r) on /.:/hosts/dce_hostname/ems-server/consumers
ΓòÉΓòÉΓòÉ 9.7.33. ems_mgmt_list_ems ΓòÉΓòÉΓòÉ
Purpose
Lists EMS hosts.
Format
#include <dce/ems.h>
void ems_mgmt_list_ems(
char ***host_list,
error_status_t *status);
Parameters
Output
host_list A pointer to the list of hosts running emsd.
status A pointer to the completion status. Upon successful
completion, this routine returns error_status_ok.
Otherwise, it returns ems_no_memory, which indicates
that there was an error allocating memory.
Usage
The ems_mgmt_list_ems routine lists hosts running emsd. Use free to
free memory used by host_list.
ΓòÉΓòÉΓòÉ 9.7.34. ems_register ΓòÉΓòÉΓòÉ
Purpose
Registers with EMS.
Format
#include <dce/ems.h>
void ems_register(
ems_netname_t *dce_hostname,
ems_handle_t *handle,
error_status_t *status);
Parameters
Input
dce_hostname A pointer to the name of the DCE host machine where
emsd is running. If the DCE host name is NULL, then the
local host is assumed.
Note: dce_hostname is case sensitive.
Output
handle Returns an EMS handle to use for future calls to EMS
routines.
status A pointer to the completion status. Upon successful
completion, this routine returns error_status_ok.
Otherwise, it returns one of the following error codes:
ems_s_no_memory An EMS handle
cannot be
allocated.
ems_s_unsupported_nameservice The dce_hostname
contains an
unsupported name
service.
Usage
The ems_register routine registers with EMS, and obtains an EMS
binding handle. This routine can be used by a management application
that will be using the EMS Management API or by event suppliers that
want to add new event types.
ΓòÉΓòÉΓòÉ 9.7.35. ems_supplier_send ΓòÉΓòÉΓòÉ
Purpose
Sends supplier events to EMS.
Format
#include <dce/ems.h>
void ems_supplier_send(
ems_handle_t handle,
ems_event_t *event,
error_status_t *status);
Parameters
Input
handle Should be the handle returned from a call to
ems_register.
event A pointer to the event data. For the content of the
event messages, see EMS Data Structures.
Output
status Pointer to the completion status. Upon successful
completion, this routine returns error_status_ok.
Otherwise, it returns one of the following error codes:
ems_s_invalid_handle A handle that has
not been initialized
or that is invalid
was used.
ems_s_no_memory The EMS server
received an error
allocating memory.
ems_s_insufficient_permission This supplier does
not have permission
to supply events.
Usage
The ems_supplier_send routine is called by event suppliers to send
events to EMS.
Permissions Required
(w) on /.:/hosts/dce_hostname/ems-server/event-types/type_name
ΓòÉΓòÉΓòÉ 9.7.36. ems_unregister ΓòÉΓòÉΓòÉ
Purpose
Unregisters with EMS.
Format
#include <dce/ems.h>
void ems_unregister(
ems_handle_t *handle,
error_status_t *status);
Parameters
Input/Output
handle An EMS handle obtained from the ems_register routine.
On output the value of handle is set to NULL.
Output
status A pointer to the completion status. Upon successful
completion, this routine returns error_status_ok.
Otherwise, it returns ems_s_invalid_handle, which
indicates that an invalid handle was passed.
Usage
The ems_unregister routine unregisters and frees up the resources
used by an EMS handle. This routine should be called with a handle
obtained by the ems_register routine.
ΓòÉΓòÉΓòÉ 10. DCE SNMP Management Information Base ΓòÉΓòÉΓòÉ
Simple Network Management Protocol (SNMP) is a TCP/IP network management
protocol and is based on a manager-agent interaction. The SNMP manager (such as
NetView for OS/2) communicates with its agents. Agents gather management data
(such as physical and logical characteristics of network objects) and store it,
while managers solicit this data and process it. This collection of management
information is called a Management Information Base (MIB). The DCE SNMP
subagent implements the DCE MIB for the agent and accesses the DCE data upon
request. The individual pieces of information that comprise a MIB are called
MIB objects and they reside on the agent system. The subagent can generate
traps from DCE Serviceability (SVC) messages and communicates the traps to the
agent asynchronously. With the exception of traps, MIB objects can be accessed
by the agent at the manager's request.
Note: Even though DCE provides location transparency, which means the views
can be cell-wide as opposed to node-wide, the DCE SNMP MIB is defined on
a per-node basis due to the nature of the SNMP model.
The DCE SNMP MIB consists of the following groups:
Component ID Group Provides the very basic information about the IBM DCE OS/2
product that is installed.
Software Component Information Group Extends the Component ID group with
attributes that further define the software component.
DCE Subagent Group Contains information about the DCE subagent.
DCE Host Information Group Contains the DCE host name and cell name.
DCE Server Table Group A table of DCE server entries. Each entry contains
information about a different server configured on the host.
DCE Host Server Group Contains information about the Host server on the host.
DCE Event Management Service Server Group Contains information about the Event
Management Service (EMS) server on the host.
DCE Security Server Group Contains information about the Security server on
the host.
DCE Cell Directory Service Server Group Contains information about the DCE
Cell Directory Service (CDS) server on the host.
DCE Cell Directory Service Advertiser Group Contains information about the DCE
CDS advertiser on the host.
DCE Cell Directory Service Clerks Group Contains information about the DCE CDS
clerks on the host.
DCE Cell Directory Service Clerk Table Group Contains a table of entries about
the DCE CDS clerks on the host.
DCE Cell Directory Service Clearinghouse Table Group Contains a table of
entries about the DCE CDS clearinghouses on the host.
DCE Cell Directory Service Cached Clearinghouse Table Group Contains a table
of entries about the cached clearinghouses on the host.
DCE Global Directory Agent Server Group Contains information about the Global
Directory Agent (GDA) server on the host.
DCE Distributed Time Service Entity Group Contains information about the
Distributed Time Service (DTS) entity.
DCE Distributed Time Service Server Group Contains information about the local
or global DCE DTS server on this host.
DCE Distributed Time Service Known Server Table Group A table of DCE DTS
servers (local and global) that are known by the DTS entity on the host.
DCE Traps Group Network events sent from the DCE SNMP subagent to an SNMP
agent asynchronously. The information generated and sent out from the DCE
Traps group cannot be queried. The information generated by all of the
other groups can be queried.
ΓòÉΓòÉΓòÉ 10.1. DCE MIB Definitions ΓòÉΓòÉΓòÉ
IMPORTS
Counter, enterprises
FROM RFC1155-SMI
OBJECT-TYPE
FROM RFC-1212
DisplayString
FROM RFC1213-MIB
TRAP-TYPE
FROM RFC-1215;
Date ::= OCTET STRING (SIZE (50))
-- identified-org OBJECT IDENTIFIER ::= { iso 3 }
-- osf OBJECT IDENTIFIER ::= { identified-org 22 }
osf OBJECT IDENTIFIER ::= { org 22 }
dce OBJECT IDENTIFIER ::= { osf 1 }
SNMP OBJECT IDENTIFIER ::= { dce 7 }
MIB OBJECT IDENTIFIER ::= { SNMP 1 }
subagent OBJECT IDENTIFIER ::= { SNMP 2 }
ΓòÉΓòÉΓòÉ 10.1.1. Component ID Group ΓòÉΓòÉΓòÉ
componentIDGroup OBJECT IDENTIFIER ::= {MIB 1}
aManufacturer OBJECT-TYPE
SYNTAX DisplayString (SIZE (0..32))
ACCESS read-only
STATUS mandatory
DESCRIPTION "The company that produced this component."
-- The string is: IBM Corporation.
::= {componentIDGroup 1}
aProduct OBJECT-TYPE
SYNTAX DisplayString (SIZE (0..32))
ACCESS read-only
STATUS mandatory
DESCRIPTION "The name of this component or product."
-- The string is: IBM DCE for OS/2.
::= {componentIDGroup 2}
aVersion OBJECT-TYPE
SYNTAX DisplayString (SIZE (0..16))
ACCESS read-only
STATUS mandatory
DESCRIPTION "The version string for this component."
-- The string is obtained from the syslevel.dce file.
::= {componentIDGroup 3}
aSerialNumber OBJECT-TYPE
SYNTAX DisplayString (SIZE (0..16))
ACCESS read-only
STATUS mandatory
DESCRIPTION "The serial number for this component."
-- The string is obtained from the syslevel.dce file.
::= {componentIDGroup 4}
aInstallation OBJECT-TYPE
SYNTAX DisplayString (SIZE (0..28))
ACCESS read-only
STATUS mandatory
DESCRIPTION "The date and time of the last IBM DCE for OS/2 install on this system."
-- The string is obtained from the syslevel.dce file.
::= {componentIDGroup 5}
aVerify OBJECT-TYPE break=fit compact.
SYNTAX INTEGER
-- {
-- vAnErrorOccurred;CheckStatusCode (0),
-- vThisComponentDoesNotExist (1),
-- vTheVerifyIsNotSupported (2),
-- vReserved (3),
-- vComponent'sFunctionalityUntested (4),
-- vComponent'sFunctionalityUnknown (5),
-- vComponentIsNotFunctioningCorrectly (6),
-- vComponentFunctionsCorrectly (7)
-- }
ACCESS read-only
STATUS mandatory
DESCRIPTION "A code that provides a level of verification that the component
is still installed and working. This value is 2 for this release."
::= {componentIDGroup 6}
aVerifyString OBJECT-TYPE
SYNTAX DisplayString (SIZE (0..32))
ACCESS read-only
STATUS mandatory
DESCRIPTION "A string that corresponds to the aVerify value. The string for this
release is: Verify is not supported.
::= {componentIDGroup 7}
ΓòÉΓòÉΓòÉ 10.1.2. Software Component Information Group ΓòÉΓòÉΓòÉ
softwareCompInfoGroup OBJECT IDENTIFIER ::= {MIB 2}
aMajorVersion OBJECT-TYPE
SYNTAX DisplayString (SIZE (0..12))
ACCESS read-only
STATUS mandatory
DESCRIPTION "Major version of this software component."
-- The string is obtained from the syslevel.dce file.
::= {softwareCompInfoGroup 1}
aMinorVersion OBJECT-TYPE
SYNTAX DisplayString (SIZE (0..12))
ACCESS read-only
STATUS mandatory
DESCRIPTION "Minor version of this software component."
-- The string is obtained from the syslevel.dce file.
::= {softwareCompInfoGroup 2}
aRevision OBJECT-TYPE
SYNTAX DisplayString (SIZE (0..12))
ACCESS read-only
STATUS mandatory
DESCRIPTION "Revision of this software component."
-- The string is obtained from the syslevel.dce file.
::= {softwareCompInfoGroup 3}
aBuild OBJECT-TYPE
SYNTAX DisplayString (SIZE (0..12))
ACCESS read-only
STATUS mandatory
DESCRIPTION "Manufacturer's internal identifier for this compilation."
-- The string is obtained from the syslevel.dce file.
::= {softwareCompInfoGroup 4}
aTargetOperatingSystem OBJECT-TYPE
SYNTAX INTEGER
ACCESS read-only
STATUS mandatory
DESCRIPTION "The operating system for which this software component is intended.
This value is 3 (IBM OS/2) for this release."
::= {softwareCompInfoGroup 5}
aLanguageEdition OBJECT-TYPE
SYNTAX DisplayString (SIZE (0..16))
ACCESS read-only
STATUS mandatory
DESCRIPTION "The language edition of this software component.
This string is: English."
::= {softwareCompInfoGroup 6}
aIdentificationCode OBJECT-TYPE
SYNTAX DisplayString (SIZE (0..16))
ACCESS read-only
STATUS mandatory
DESCRIPTION "Stock Keeping Unit (SKU) for this software component."
-- The string is obtained from the syslevel.dce file.
::= {softwareCompInfoGroup 7}
aTargetOSString OBJECT-TYPE
SYNTAX DisplayString (SIZE (0..32))
ACCESS read-only
STATUS mandatory
DESCRIPTION "The operating system for which this software component is intended.
This is IBM OS/2 for this release."
::= {softwareCompInfoGroup 8}
ΓòÉΓòÉΓòÉ 10.1.3. DCE Subagent Group ΓòÉΓòÉΓòÉ
dceSubagentGroup OBJECT IDENTIFIER ::= {MIB 3}
aSubagtName OBJECT-TYPE
SYNTAX DisplayString (SIZE (0..32))
ACCESS read-only
STATUS mandatory
DESCRIPTION "The name of this subagent is IBM DCE Subagent.
The string is: IBM DCE Subagent.
::= {dceSubagentGroup 1}
aSubagtUpTime OBJECT-TYPE
SYNTAX Date
ACCESS read-only
STATUS mandatory
DESCRIPTION "The date and time the DCE subagent was last started."
::= {dceSubagentGroup 2}
ΓòÉΓòÉΓòÉ 10.1.4. DCE Host Information Group ΓòÉΓòÉΓòÉ
dceHostInfoGroup OBJECT IDENTIFIER ::= {MIB 4}
aDCEHostName OBJECT-TYPE
SYNTAX DisplayString (SIZE (0..64))
ACCESS read-only
STATUS mandatory
DESCRIPTION "The name of the DCE host."
::= {dceHostInfoGroup 1}
aDCEHostCellName OBJECT-TYPE
SYNTAX DisplayString (SIZE (0..64))
ACCESS read-only
STATUS mandatory
DESCRIPTION "The name for the cell to which this DCE host belongs."
::= {dceHostInfoGroup 2}
ΓòÉΓòÉΓòÉ 10.1.5. DCE Server Table Group ΓòÉΓòÉΓòÉ
dceSvrTable OBJECT-TYPE
SYNTAX SEQUENCE OF DCEHostSvrEntry
ACCESS not-accessible
STATUS mandatory
DESCRIPTION "A list of server entries configured on this DCE host."
::= {MIB 5}
dceHostSvrEntry OBJECT-TYPE
SYNTAX DCEHostSvrEntry
ACCESS not-accessible
STATUS mandatory
DESCRIPTION ""
INDEX {aDCESvrName}
::= {dceSvrTable 1}
DCEHostSvrEntry ::= SEQUENCE
break=fit compact.
{
aDCESvrName DisplayString,
aDCESvrState DisplayString,
aDCESvrStateValue INTEGER
}
aDCESvrName OBJECT-TYPE
SYNTAX DisplayString (SIZE (0..48))
ACCESS read-only
STATUS mandatory
DESCRIPTION "The name of the DCE server."
-- The string can be on of the following:
-- Unknown
-- DCE Host Server
-- Master Security Server
-- Replica Security Server
-- CDS Server
-- CDS Advertiser
-- DTS Global Server
-- DTS Local Server
-- DTS Clerk
-- Time Provider
-- GDA Server
-- EMS Server
-- Audit Server
-- DFS Server
-- Password Strength Server
-- Password Synchronization Server
-- Generic Server
::= {dceHostSvrEntry 1}
aDCESvrState OBJECT-TYPE
SYNTAX DisplayString (SIZE (0..16))
ACCESS read-only
STATUS mandatory
DESCRIPTION "The state of this DCE server."
-- One of the following strings will be set based on the state value:
-- String Description
--
-- Unknown
-- Not running The server does not appear to be running.
-- Available The server is running and responding to requests.
-- Not available The server is running but is not responding to requests.
::= {dceHostSvrEntry 2}
aDCESvrStateValue OBJECT-TYPE
break=fit compact.
SYNTAX INTEGER
{
vUnknown (0),
vNotRunning (1),
vAvailable (2),
vNotAvailable (3)
}
ACCESS read-only
STATUS mandatory
DESCRIPTION "The state value of this DCE server."
::= {dceHostSvrEntry 3}
ΓòÉΓòÉΓòÉ 10.1.6. DCE Host Server Group ΓòÉΓòÉΓòÉ
dceHostSvrGroup OBJECT IDENTIFIER ::= {MIB 6}
aHostSvrPid OBJECT-TYPE
SYNTAX INTEGER
ACCESS read-only
STATUS mandatory
DESCRIPTION "The process ID of the DCE host server."
::= {dceHostSvrGroup 1}
aHostSvrUid OBJECT-TYPE
SYNTAX INTEGER
ACCESS read-only
STATUS mandatory
DESCRIPTION "The user ID of the DCE host server."
::= {dceHostSvrGroup 2}
aHostSvrGid OBJECT-TYPE
SYNTAX INTEGER
ACCESS read-only
STATUS mandatory
DESCRIPTION "The group ID of the DCE host server."
::= {dceHostSvrGroup 3}
aHostSvrInRpcCalls OBJECT-TYPE
SYNTAX Counter
ACCESS read-only
STATUS mandatory
DESCRIPTION "The number of RPC calls received by the DCE host server."
::= {dceHostSvrGroup 4}
aHostSvrOutRpcCalls OBJECT-TYPE
SYNTAX Counter
ACCESS read-only
STATUS mandatory
DESCRIPTION "The number of RPC calls initiated by the DCE host server."
::= {dceHostSvrGroup 5}
aHostSvrInRpcPkts OBJECT-TYPE
SYNTAX Counter
ACCESS read-only
STATUS mandatory
DESCRIPTION "The number of RPC packets received by the DCE host server."
::= {dceHostSvrGroup 6}
aHostSvrOutRpcPkts OBJECT-TYPE
SYNTAX Counter
ACCESS read-only
STATUS mandatory
DESCRIPTION "The number of RPC packets initiated by the DCE host server."
::= {dceHostSvrGroup 7}
aHostSvrState OBJECT-TYPE
SYNTAX DisplayString (SIZE (0..16))
ACCESS read-only
STATUS mandatory
DESCRIPTION "The state of this DCE host server."
-- One of the following strings will be set based on the state value:
-- String Description
--
-- Unknown
-- Not running The server does not appear to be running.
-- Available The server is running and responding to requests.
-- Not available The server is running but is not responding to requests.
::= {dceHostSvrGroup 8}
aHostSvrStateValue OBJECT-TYPE
break=fit compact.
SYNTAX INTEGER
{
vUnknown (0),
vNotRunning (1),
vAvailable (2),
vNotAvailable (3)
}
ACCESS read-only
STATUS mandatory
DESCRIPTION "The state value of this DCE host server."
::= {dceHostSvrGroup 9}
ΓòÉΓòÉΓòÉ 10.1.7. DCE Event Management Service Server Group ΓòÉΓòÉΓòÉ
dceEmsSvrGroup OBJECT IDENTIFIER ::= {MIB 7}
aEmsSvrPid OBJECT-TYPE
SYNTAX INTEGER
ACCESS read-only
STATUS mandatory
DESCRIPTION "The process ID of the DCE EMS server."
::= {dceEmsSvrGroup 1}
aEmsSvrUid OBJECT-TYPE
SYNTAX INTEGER
ACCESS read-only
STATUS mandatory
DESCRIPTION "The user ID of the DCE EMS server."
::= {dceEmsSvrGroup 2}
aEmsSvrGid OBJECT-TYPE
SYNTAX INTEGER
ACCESS read-only
STATUS mandatory
DESCRIPTION "The group ID of the DCE EMS server."
::= {dceEmsSvrGroup 3}
aEmsSvrInRpcCalls OBJECT-TYPE
SYNTAX Counter
ACCESS read-only
STATUS mandatory
DESCRIPTION "The number of RPC calls received by the DCE EMS server."
::= {dceEmsSvrGroup 4}
aEmsSvrOutRpcCalls OBJECT-TYPE
SYNTAX Counter
ACCESS read-only
STATUS mandatory
DESCRIPTION "The number of RPC calls initiated by the DCE EMS server."
::= {dceEmsSvrGroup 5}
aEmsSvrInRpcPkts OBJECT-TYPE
SYNTAX Counter
ACCESS read-only
STATUS mandatory
DESCRIPTION "The number of RPC packets received by the DCE EMS server."
::= {dceEmsSvrGroup 6}
aEmsSvrOutRpcPkts OBJECT-TYPE
SYNTAX Counter
ACCESS read-only
STATUS mandatory
DESCRIPTION "The number of RPC packets initiated by the DCE EMS server."
::= {dceEmsSvrGroup 7}
aEmsSvrState OBJECT-TYPE
SYNTAX DisplayString (SIZE (0..16))
ACCESS read-only
STATUS mandatory
DESCRIPTION "The state of this DCE EMS server."
-- One of the following strings will be set based on the state value:
-- String Description
--
-- Unknown
-- Not running The server does not appear to be running.
-- Available The server is running and responding to requests.
-- Not available The server is running but is not responding to requests.
::= {dceEmsSvrGroup 8}
aEmsSvrStateValue OBJECT-TYPE
break=fit compact.
SYNTAX INTEGER
{
vUnknown (0),
vNotRunning (1),
vAvailable (2),
vNotAvailable (3)
}
ACCESS read-only
STATUS mandatory
DESCRIPTION "The state value of this DCE EMS server."
::= {dceEmsSvrGroup 9}
ΓòÉΓòÉΓòÉ 10.1.8. DCE Security Server Group ΓòÉΓòÉΓòÉ
dceSecSvrGroup OBJECT IDENTIFIER ::= {MIB 8}
aSecSvrRole OBJECT-TYPE
break=fit compact.
SYNTAX INTEGER
{
vUnknown (0),
vMaster (1),
vReplica (2)
}
ACCESS read-only
STATUS mandatory
DESCRIPTION "The role of the Security server.
::= {dceSecSvrGroup 1}
aSecSvrMode OBJECT-TYPE
break=fit compact.
SYNTAX INTEGER
{
vUnknown (0),
vService (1),
vMaintenance (2)
}
ACCESS read-only
STATUS mandatory
DESCRIPTION "The mode of the Master Security server.
::= {dceSecSvrGroup 2}
aSecRgyUpdTime OBJECT-TYPE
SYNTAX Date
ACCESS read-only
STATUS mandatory
DESCRIPTION "The localized date and time that the replica was last updated."
-- The string will be Unavailable when an error is encountered
-- trying to retrieve the string. The string will be Not applicable
-- when the object does not apply.
::= {dceSecSvrGroup 3}
aSecRgyUpdSeq OBJECT-TYPE
SYNTAX INTEGER
ACCESS read-only
STATUS mandatory
DESCRIPTION "The sequence number of the last update that the replica received."
::= {dceSecSvrGroup 4}
aSecSvrPid OBJECT-TYPE
SYNTAX INTEGER
ACCESS read-only
STATUS mandatory
DESCRIPTION "The process ID of the DCE Security server."
::= {dceSecSvrGroup 5}
aSecSvrUid OBJECT-TYPE
SYNTAX INTEGER
ACCESS read-only
STATUS mandatory
DESCRIPTION "The user ID of the DCE Security server."
::= {dceSecSvrGroup 6}
aSecSvrGid OBJECT-TYPE
SYNTAX INTEGER
ACCESS read-only
STATUS mandatory
DESCRIPTION "The group ID of the DCE Security server."
::= {dceSecSvrGroup 7}
aSecSvrInRpcCalls OBJECT-TYPE
SYNTAX Counter
ACCESS read-only
STATUS mandatory
DESCRIPTION "The number of RPC calls received by the DCE Security server."
::= {dceSecSvrGroup 8}
aSecSvrOutRpcCalls OBJECT-TYPE
SYNTAX Counter
ACCESS read-only
STATUS mandatory
DESCRIPTION "The number of RPC calls initiated by the DCE Security server."
::= {dceSecSvrGroup 9}
aSecSvrInRpcPkts OBJECT-TYPE
SYNTAX Counter
ACCESS read-only
STATUS mandatory
DESCRIPTION "The number of RPC packets received by the DCE Security server."
::= {dceSecSvrGroup 10}
aSecSvrOutRpcPkts OBJECT-TYPE
SYNTAX Counter
ACCESS read-only
STATUS mandatory
DESCRIPTION "The number of RPC packets initiated by the DCE Security server."
::= {dceSecSvrGroup 11}
aSecSvrState OBJECT-TYPE
SYNTAX DisplayString (SIZE (0..16))
ACCESS read-only
STATUS mandatory
DESCRIPTION "The state of this DCE Security server."
-- One of the following strings will be set based on the state value:
-- String Description
--
-- Unknown
-- Not running The server does not appear to be running.
-- Available The server is running and responding to requests.
-- Not available The server is running but is not responding to requests.
::= {dceSecSvrGroup 12}
aSecSvrStateValue OBJECT-TYPE
break=fit compact.
SYNTAX INTEGER
{
vUnknown (0),
vNotRunning (1),
vAvailable (2),
vNotAvailable (3)
}
ACCESS read-only
STATUS mandatory
DESCRIPTION "The state value of this DCE Security server."
::= {dceSecSvrGroup 13}
aSecSvrRoleString OBJECT-TYPE
SYNTAX DisplayString (SIZE (0..16))
ACCESS read-only
STATUS mandatory
DESCRIPTION "The role of this DCE Security server."
-- One of the following strings will be set based on the state value:
-- String Description
--
-- Unknown
-- Master
-- Replica
-- Unavailable An error was encountered trying to retrieve the string.
-- Not applicable The object does not apply.
::= {dceSecSvrGroup 14}
aSecSvrModeString OBJECT-TYPE
SYNTAX DisplayString (SIZE (0..16))
ACCESS read-only
STATUS mandatory
DESCRIPTION "The mode of this DCE Security server."
-- One of the following strings will be set based on the state value:
-- String Description
--
-- Unknown
-- Service
-- Maintenance
-- Unavailable An error was encountered trying to retrieve the string.
-- Not applicable The object does not apply.
::= {dceSecSvrGroup 15}
ΓòÉΓòÉΓòÉ 10.1.9. DCE Cell Directory Service Server Group ΓòÉΓòÉΓòÉ
dceCdsSvrGroup OBJECT IDENTIFIER ::= {MIB 9}
aCdsSvrUpTime OBJECT-TYPE
SYNTAX Date
ACCESS read-only
STATUS mandatory
DESCRIPTION "The time this server was created."
-- The string will be Unavailable when an error is encountered trying to
-- retrieve the string. The string will be Not applicable when the object does not apply.
::= {dceCdsSvrGroup 1}
aCdsSvrChildUpdFails OBJECT-TYPE
SYNTAX Counter
ACCESS read-only
STATUS mandatory
DESCRIPTION "The number of times the server was unable to contact all the clearinghouses
that store a replica of a particular child directory's parent directory and
apply the child updates that have occurred since the last skulk."
::= {dceCdsSvrGroup 2}
aCdsSvrCrucialReps OBJECT-TYPE
SYNTAX Counter
ACCESS read-only
STATUS mandatory
DESCRIPTION "The number of times a user attempted to remove a crucial replica
from this server."
::= {dceCdsSvrGroup 3}
aCdsSvrMaxSkewTime OBJECT-TYPE
SYNTAX INTEGER
ACCESS read-only
STATUS mandatory
DESCRIPTION "The maximum amount of time that a timestamp on a new or modified
entry can vary from local system time."
::= {dceCdsSvrGroup 4}
aCdsSvrLookupPathBrokens OBJECT-TYPE
SYNTAX Counter
ACCESS read-only
STATUS mandatory
DESCRIPTION "The number of broken connections between clearinghouses on
this server and clearinghouses closer to the root."
::= {dceCdsSvrGroup 5}
aCdsSvrSecFails OBJECT-TYPE
SYNTAX Counter
ACCESS read-only
STATUS mandatory
DESCRIPTION "The number of times a server principal for this server was found to have
inadequate permissions to perform a request operation."
::= {dceCdsSvrGroup 6}
aCdsSvrSkulkInitd OBJECT-TYPE
SYNTAX Counter
ACCESS read-only
STATUS mandatory
DESCRIPTION "The number of skulks initiated by this DCE CDS server."
::= {dceCdsSvrGroup 7}
aCdsSvrSkulkCmpltd OBJECT-TYPE
SYNTAX Counter
ACCESS read-only
STATUS mandatory
DESCRIPTION "The number of skulks successfully completed by this DCE CDS server."
::= {dceCdsSvrGroup 8}
aCdsSvrReadOps OBJECT-TYPE
SYNTAX Counter
ACCESS read-only
STATUS mandatory
DESCRIPTION "The number of read operations directed to this DCE CDS server."
::= {dceCdsSvrGroup 9}
aCdsSvrWriteOps OBJECT-TYPE
SYNTAX Counter
ACCESS read-only
STATUS mandatory
DESCRIPTION "The number of write operations to this DCE CDS server."
::= {dceCdsSvrGroup 10}
aCdsSvrPid OBJECT-TYPE
SYNTAX INTEGER
ACCESS read-only
STATUS mandatory
DESCRIPTION "The process ID of this DCE CDS server."
::= {dceCdsSvrGroup 11}
aCdsSvrUid OBJECT-TYPE
SYNTAX INTEGER
ACCESS read-only
STATUS mandatory
DESCRIPTION "The user ID this DCE CDS server."
::= {dceCdsSvrGroup 12}
aCdsSvrGid OBJECT-TYPE
SYNTAX INTEGER
ACCESS read-only
STATUS mandatory
DESCRIPTION "The group ID of this DCE CDS server."
::= {dceCdsSvrGroup 13}
aCdsSvrInRpcCalls OBJECT-TYPE
SYNTAX Counter
ACCESS read-only
STATUS mandatory
DESCRIPTION "The number of RPC calls received by the DCE CDS server."
::= {dceCdsSvrGroup 14}
aCdsSvrOutRpcCalls OBJECT-TYPE
SYNTAX Counter
ACCESS read-only
STATUS mandatory
DESCRIPTION "The number of RPC calls initiated by the DCE CDS server."
::= {dceCdsSvrGroup 15}
aCdsSvrInRpcPkts OBJECT-TYPE
SYNTAX Counter
ACCESS read-only
STATUS mandatory
DESCRIPTION "The number of RPC packets received by the DCE CDS server."
::= {dceCdsSvrGroup 16}
aCdsSvrOutRpcPkts OBJECT-TYPE
SYNTAX Counter
ACCESS read-only
STATUS mandatory
DESCRIPTION "The number of RPC packets initiated by the DCE CDS server."
::= {dceCdsSvrGroup 17}
aCdsSvrState OBJECT-TYPE
SYNTAX DisplayString (SIZE (0..16))
ACCESS read-only
STATUS mandatory
DESCRIPTION "The state of this DCE CDS Server."
-- One of the following strings will be set based on the state value:
-- String Description
--
-- Unknown
-- Not running The server does not appear to be running.
-- Available The server is running and responding to requests.
-- Not available The server is running but is not responding to requests.
::= {dceCdsSvrGroup 18}
aCdsSvrStateValue OBJECT-TYPE
break=fit compact.
SYNTAX INTEGER
{
vUnknown (0),
vNotRunning (1),
vAvailable (2),
vNotAvailable (3)
}
ACCESS read-only
STATUS mandatory
DESCRIPTION "The state value of this DCE CDS server."
::= {dceCdsSvrGroup 19}
ΓòÉΓòÉΓòÉ 10.1.10. DCE Cell Directory Service Advertiser Group ΓòÉΓòÉΓòÉ
dceCdsAdvGroup OBJECT IDENTIFIER ::= {MIB 10}
aCdsAdvUpTime OBJECT-TYPE
SYNTAX Date
ACCESS read-only
STATUS mandatory
DESCRIPTION "The start time of the DCE CDS advertiser."
-- The string will be Unavailable when an error is encountered
-- trying to retrieve the string. The string will be Not applicable when
-- the object does not apply.
::= {dceCdsAdvGroup 1}
aCdsAdvPid OBJECT-TYPE
SYNTAX INTEGER
ACCESS read-only
STATUS mandatory
DESCRIPTION "The process ID of the DCE CDS advertiser."
::= {dceCdsAdvGroup 2}
aCdsAdvUid OBJECT-TYPE
SYNTAX INTEGER
ACCESS read-only
STATUS mandatory
DESCRIPTION "The user ID of this DCE CDS advertiser."
::= {dceCdsAdvGroup 3}
aCdsAdvGid OBJECT-TYPE
SYNTAX INTEGER
ACCESS read-only
STATUS mandatory
DESCRIPTION "The group ID of this DCE CDS advertiser."
::= {dceCdsAdvGroup 4}
aCdsAdvInRpcCalls OBJECT-TYPE
SYNTAX Counter
ACCESS read-only
STATUS mandatory
DESCRIPTION "The number of RPC calls received by the DCE CDS advertiser."
::= {dceCdsAdvGroup 5}
aCdsAdvOutRpcCalls OBJECT-TYPE
SYNTAX Counter
ACCESS read-only
STATUS mandatory
DESCRIPTION "The number of RPC calls initiated by the DCE CDS advertiser."
::= {dceCdsAdvGroup 6}
aCdsAdvInRpcPkts OBJECT-TYPE
SYNTAX Counter
ACCESS read-only
STATUS mandatory
DESCRIPTION "The number of RPC packets received by the DCE CDS advertiser."
::= {dceCdsAdvGroup 7}
aCdsAdvOutRpcPkts OBJECT-TYPE
SYNTAX Counter
ACCESS read-only
STATUS mandatory
DESCRIPTION "The number of RPC packets initiated by the DCE CDS advertiser."
::= {dceCdsAdvGroup 8}
aCdsAdvState OBJECT-TYPE
SYNTAX DisplayString (SIZE (0..16))
ACCESS read-only
STATUS mandatory
DESCRIPTION "The state of this DCE CDS advertiser."
-- One of the following strings will be set based on the state value:
-- String Description
--
-- Unknown
-- Not running The server does not appear to be running.
-- Available The server is running and responding to requests.
-- Not available The server is running but is not responding to requests.
::= {dceCdsAdvGroup 9}
aCdsAdvStateValue OBJECT-TYPE
break=fit compact.
SYNTAX INTEGER
{
vUnknown (0),
vNotRunning (1),
vAvailable (2),
vNotAvailable (3)
}
ACCESS read-only
STATUS mandatory
DESCRIPTION "The state value of this DCE CDS advertiser."
::= {dceCdsAdvGroup 10}
ΓòÉΓòÉΓòÉ 10.1.11. DCE Cell Directory Service Clerks Group ΓòÉΓòÉΓòÉ
dceCdsClerksGroup OBJECT IDENTIFIER ::= {MIB 11}
aCdsClerksAuthFails OBJECT-TYPE
SYNTAX Counter
ACCESS read-only
STATUS mandatory
DESCRIPTION "The number of times requesting principals failed authentication procedures."
::= {dceCdsClerksGroup 1}
aCdsClerksCacheBypasses OBJECT-TYPE
SYNTAX Counter
ACCESS read-only
STATUS mandatory
DESCRIPTION "The number of requests to read attributes for which the clerks were specifically
directed by the requesting application to bypass its own cache."
::= {dceCdsClerksGroup 2}
aCdsClerksCacheHits OBJECT-TYPE
SYNTAX Counter
ACCESS read-only
STATUS mandatory
DESCRIPTION "The total number of read requests directed to the clerks that were satisfied
entirely by its cache."
::= {dceCdsClerksGroup 3}
aCdsClerksMiscOps OBJECT-TYPE
SYNTAX Counter
ACCESS read-only
STATUS mandatory
DESCRIPTION "The number of operations other than read and write performed by the clerks."
::= {dceCdsClerksGroup 4}
aCdsClerksReadOps OBJECT-TYPE
SYNTAX Counter
ACCESS read-only
STATUS mandatory
DESCRIPTION "The number of lookup operations performed by the clerks."
::= {dceCdsClerksGroup 5}
aCdsClerksWriteOps OBJECT-TYPE
SYNTAX Counter
ACCESS read-only
STATUS mandatory
DESCRIPTION "The number of requests to modify data processed by the clerks."
::= {dceCdsClerksGroup 6}
ΓòÉΓòÉΓòÉ 10.1.12. DCE Cell Directory Service Clerk Table Group ΓòÉΓòÉΓòÉ
cdsClerkTable OBJECT-TYPE
SYNTAX SEQUENCE OF CdsClerkEntry
ACCESS not-accessible
STATUS mandatory
DESCRIPTION "A list of DCE CDS clerks on the host."
::= {MIB 12}
cdsClerkEntry OBJECT-TYPE
SYNTAX CdsClerkEntry
ACCESS not-accessible
STATUS mandatory
DESCRIPTION ""
INDEX {aClerkPid}
::= {cdsClerkTable 1}
CdsClerkEntry ::= SEQUENCE
break=fit compact.
{
aClerkUser DisplayString,
aClerkUid INTEGER,
aClerkPid INTEGER,
aClerkUpTime Date
}
aClerkUser OBJECT-TYPE
SYNTAX DisplayString (SIZE (0..64))
ACCESS read-only
STATUS mandatory
DESCRIPTION "The user name of a clerk on the host. This contains the string Not
applicable because there is no user concept prevalent on OS/2."
::= {cdsClerkEntry 1}
aClerkUid OBJECT-TYPE
SYNTAX INTEGER
ACCESS read-only
STATUS mandatory
DESCRIPTION "The user ID of a clerk on the host. This field is returned as
0 (zero) because there is no user concept prevalent on OS/2."
::= {cdsClerkEntry 2}
aClerkPid OBJECT-TYPE
SYNTAX INTEGER
ACCESS read-only
STATUS mandatory
DESCRIPTION "The process ID of a clerk on the host."
::= {cdsClerkEntry 3}
aClerkUpTime OBJECT-TYPE
SYNTAX Date
ACCESS read-only
STATUS mandatory
DESCRIPTION "The start time of a clerk on the host."
-- The string will be Unavailable when an error is encountered
-- trying to retrieve the string. The string will be Not applicable when
-- the object does not apply.
::= {cdsClerkEntry 4}
ΓòÉΓòÉΓòÉ 10.1.13. DCE Cell Directory Service Clearinghouse Table Group ΓòÉΓòÉΓòÉ
cdsCHTable OBJECT-TYPE
SYNTAX SEQUENCE OF CdsCHEntry
ACCESS not-accessible
STATUS mandatory
DESCRIPTION "A list of clearinghouses on the host."
::= {MIB 13}
cdsCHEntry OBJECT-TYPE
SYNTAX CdsCHEntry
ACCESS not-accessible
STATUS mandatory
DESCRIPTION ""
INDEX {aChName}
::= {cdsCHTable 1}
CdsCHEntry ::= SEQUENCE
break=fit compact.
{
aChName DisplayString,
aChDataCorrupts Counter,
aChEnableCounts Counter,
aChDisableCounts Counter,
aChRefReturns Counter,
aChSkulkFails Counter,
aChEntryMisses Counter,
aChRootLosts Counter,
aChUpgFails Counter,
aChReadOps Counter,
aChWriteOps Counter
}
aChName OBJECT-TYPE
SYNTAX DisplayString (SIZE (0..64))
ACCESS read-only
STATUS mandatory
DESCRIPTION "The full name of the clearinghouse."
-- The string will be Unavailable when an error is encountered
-- trying to retrieve the string. The string will be Not applicable when
-- the object does not apply.
::= {cdsCHEntry 1}
aChDataCorrupts OBJECT-TYPE
SYNTAX Counter
ACCESS read-only
STATUS mandatory
DESCRIPTION "The number of times that the data corruption event was generated "
::= {cdsCHEntry 2}
aChEnableCounts OBJECT-TYPE
SYNTAX Counter
ACCESS read-only
STATUS mandatory
DESCRIPTION "The number of times that the clearinghouse was enabled
since it was last started."
::= {cdsCHEntry 3}
aChDisableCounts OBJECT-TYPE
SYNTAX Counter
ACCESS read-only
STATUS mandatory
DESCRIPTION "The number of times that the clearinghouse was disabled
since it was last started."
::= {cdsCHEntry 4}
aChRefReturns OBJECT-TYPE
SYNTAX Counter
ACCESS read-only
STATUS mandatory
DESCRIPTION "The number of requests directed to this clearinghouse that resulted in the
return of a partial answer instead of satisfying the client's request."
::= {cdsCHEntry 5}
aChSkulkFails OBJECT-TYPE
SYNTAX Counter
ACCESS read-only
STATUS mandatory
DESCRIPTION "The number of times that a skulk of a directory,
initiated from this clearinghouse, failed to complete."
::= {cdsCHEntry 6}
aChEntryMisses OBJECT-TYPE
SYNTAX Counter
ACCESS read-only
STATUS mandatory
DESCRIPTION "The number of times the clearinghouse entry missing
event was generated."
::= {cdsCHEntry 7}
aChRootLosts OBJECT-TYPE
SYNTAX Counter
ACCESS read-only
STATUS mandatory
DESCRIPTION "The number of times the root lost event was generated."
::= {cdsCHEntry 8}
aChUpgFails OBJECT-TYPE
SYNTAX Counter
ACCESS read-only
STATUS mandatory
DESCRIPTION "The number of times that upgrades failed."
::= {cdsCHEntry 9}
aChReadOps OBJECT-TYPE
SYNTAX Counter
ACCESS read-only
STATUS mandatory
DESCRIPTION "The number of read operations directed to this clearinghouse."
::= {cdsCHEntry 10}
aChWriteOps OBJECT-TYPE
SYNTAX Counter
ACCESS read-only
STATUS mandatory
DESCRIPTION "The number of write operations directed to this clearinghouse."
::= {cdsCHEntry 11}
ΓòÉΓòÉΓòÉ 10.1.14. DCE Cell Directory Service Cached Clearinghouse Table Group ΓòÉΓòÉΓòÉ
cdsCachedCHTable OBJECT-TYPE
SYNTAX SEQUENCE OF CdsCachedCHEntry
ACCESS not-accessible
STATUS mandatory
DESCRIPTION "A list of cached clearinghouses on the host."
::= {MIB 14}
cdsCachedCHEntry OBJECT-TYPE
SYNTAX CdsCachedCHEntry
ACCESS not-accessible
STATUS mandatory
DESCRIPTION ""
INDEX {aCachedCHName}
::= {cdsCachedCHTable 1}
CdsCachedCHEntry ::= SEQUENCE
break=fit compact.
{
aCachedCHName DisplayString,
aCachedCHUpTime Date,
aCachedCHMiscOps Counter,
aCachedCHReadOps Counter,
aCachedCHWriteOps Counter
}
aCachedCHName OBJECT-TYPE
SYNTAX DisplayString (SIZE (0..64))
ACCESS read-only
STATUS mandatory
DESCRIPTION "The name of the cached clearinghouse."
-- The string will be Unavailable when an error is encountered
-- trying to retrieve the string. The string will be Not applicable when
-- the object does not apply.
::= {cdsCachedCHEntry 1}
aCachedCHUpTime OBJECT-TYPE
SYNTAX Date
ACCESS read-only
STATUS mandatory
DESCRIPTION "The date and time at which the clearinghouse was added to the cache."
-- The string will be Unavailable when an error is encountered
-- trying to retrieve the string. The string will be Not applicable when
-- the object does not apply.
::= {cdsCachedCHEntry 2}
aCachedCHMiscOps OBJECT-TYPE
SYNTAX Counter
ACCESS read-only
STATUS mandatory
DESCRIPTION "The number of operations other than read and write the clerk has
performed on the clearinghouse represented by the cache entry."
::= {cdsCachedCHEntry 3}
aCachedCHReadOps OBJECT-TYPE
SYNTAX Counter
ACCESS read-only
STATUS mandatory
DESCRIPTION "The number of lookup operations the clerk has performed
on the clearinghouse represented by the cache entry."
::= {cdsCachedCHEntry 4}
aCachedCHWriteOps OBJECT-TYPE
SYNTAX Counter
ACCESS read-only
STATUS mandatory
DESCRIPTION "The number of write operations the clerk has sent to
the clearinghouse represented by the cache entry."
::= {cdsCachedCHEntry 5}
ΓòÉΓòÉΓòÉ 10.1.15. DCE Global Directory Agent Server Group ΓòÉΓòÉΓòÉ
dceGdaSvrGroup OBJECT IDENTIFIER ::= {MIB 15}
aGdaSvrPid OBJECT-TYPE
SYNTAX INTEGER
ACCESS read-only
STATUS mandatory
DESCRIPTION "The process ID of this DCE GDA server."
::= {dceGdaSvrGroup 1}
aGdaSvrUid OBJECT-TYPE
SYNTAX INTEGER
ACCESS read-only
STATUS mandatory
DESCRIPTION "The user ID of this DCE GDA server."
::= {dceGdaSvrGroup 2}
aGdaSvrGid OBJECT-TYPE
SYNTAX INTEGER
ACCESS read-only
STATUS mandatory
DESCRIPTION "The group ID of this DCE GDA server."
::= {dceGdaSvrGroup 3}
aGdaSvrInRpcCalls OBJECT-TYPE
SYNTAX Counter
ACCESS read-only
STATUS mandatory
DESCRIPTION "The number of RPC calls received by the GDA server."
::= {dceGdaSvrGroup 4}
aGdaSvrOutRpcCalls OBJECT-TYPE
SYNTAX Counter
ACCESS read-only
STATUS mandatory
DESCRIPTION "The number of RPC calls initiated by the GDA server."
::= {dceGdaSvrGroup 5}
aGdaSvrInRpcPkts OBJECT-TYPE
SYNTAX Counter
ACCESS read-only
STATUS mandatory
DESCRIPTION "The number of RPC packets received by the GDA server."
::= {dceGdaSvrGroup 6}
aGdaSvrOutRpcPkts OBJECT-TYPE
SYNTAX Counter
ACCESS read-only
STATUS mandatory
DESCRIPTION "The number of RPC packets initiated the GDA server."
::= {dceGdaSvrGroup 7}
aGdaSvrState OBJECT-TYPE
SYNTAX DisplayString (SIZE (0..16))
ACCESS read-only
STATUS mandatory
DESCRIPTION "The state of this DCE GDA server."
-- One of the following strings will be set based on the state value:
-- String Description
--
-- Unknown
-- Not running The server does not appear to be running.
-- Available The server is running and responding to requests.
-- Not available The server is running but is not responding to requests.
::= {dceGdaSvrGroup 8}
aGdaSvrStateValue OBJECT-TYPE
break=fit compact.
SYNTAX INTEGER
{
vUnknown (0),
vNotRunning (1),
vAvailable (2),
vNotAvailable (3)
}
ACCESS read-only
STATUS mandatory
DESCRIPTION "The state value of this DCE GDA server."
::= {dceGdaSvrGroup 9}
ΓòÉΓòÉΓòÉ 10.1.16. DCE Distributed Time Service Entity Group ΓòÉΓòÉΓòÉ
dceDtsEntityGroup OBJECT IDENTIFIER ::= {MIB 16}
aDtsdCurrTime OBJECT-TYPE
SYNTAX Date
ACCESS read-only
STATUS mandatory
DESCRIPTION "Current time on the node."
-- The string will be Unavailable when an error is encountered
-- trying to retrieve the string. The string will be Not applicable when
-- the object does not apply.
::= {dceDtsEntityGroup 1}
aDtsdBadProtocols OBJECT-TYPE
SYNTAX Counter
ACCESS read-only
STATUS mandatory
DESCRIPTION "The number of times the local node failed to process a received message
containing an incompatible protocol version."
::= {dceDtsEntityGroup 2}
aDtsdBadTimeReps OBJECT-TYPE
SYNTAX Counter
ACCESS read-only
STATUS mandatory
DESCRIPTION "The number of times the local node failed to process a received message
containing an incompatible timestamp format."
::= {dceDtsEntityGroup 3}
aDtsdInsufRes OBJECT-TYPE
SYNTAX Counter
ACCESS read-only
STATUS mandatory
DESCRIPTION "The number of times the node has been unable to
allocate virtual memory."
::= {dceDtsEntityGroup 4}
aDtsdLocalNotIntersects OBJECT-TYPE
SYNTAX Counter
ACCESS read-only
STATUS mandatory
DESCRIPTION "The number of times the node's time interval failed to
intersect with the computed interval of the servers."
::= {dceDtsEntityGroup 5}
aDtsdSyncCmpltd OBJECT-TYPE
SYNTAX Counter
ACCESS read-only
STATUS mandatory
DESCRIPTION "The number of times the node successfully synchronized time."
::= {dceDtsEntityGroup 6}
aDtsdSysErrors OBJECT-TYPE
SYNTAX Counter
ACCESS read-only
STATUS mandatory
DESCRIPTION "The number of times the DTS entity detected a system error."
::= {dceDtsEntityGroup 7}
aDtsdTooFewSvrs OBJECT-TYPE
SYNTAX Counter
ACCESS read-only
STATUS mandatory
DESCRIPTION "The number of times a node failed to synchronize because it could not
contact the required minimum number of servers."
::= {dceDtsEntityGroup 8}
aDtsdGlobalTo OBJECT-TYPE
SYNTAX DisplayString (SIZE (0..32))
ACCESS read-only
STATUS mandatory
DESCRIPTION "The amount of time the node waits for a response to a WAN
synchronization request before sending another
request or declaring a global server to be unavailable."
-- The string will be Unavailable when an error is encountered
-- trying to retrieve the string. The string will be Not applicable when
-- the object does not apply.
::= {dceDtsEntityGroup 9}
aDtsdLocalTo OBJECT-TYPE
SYNTAX DisplayString (SIZE (0..32))
ACCESS read-only
STATUS mandatory
DESCRIPTION "The amount of time the node waits for a response to a synchronization
request before sending another request or declaring a
server to be unavailable."
-- The string will be Unavailable when an error is encountered
-- trying to retrieve the string. The string will be Not applicable when
-- the object does not apply.
::= {dceDtsEntityGroup 10}
aDtsdPid OBJECT-TYPE
SYNTAX INTEGER
ACCESS read-only
STATUS mandatory
DESCRIPTION "The process ID of this DCE DTS entity."
::= {dceDtsEntityGroup 11}
aDtsdUid OBJECT-TYPE
SYNTAX INTEGER
ACCESS read-only
STATUS mandatory
DESCRIPTION "The user ID of the DCE DTS entity."
::= {dceDtsEntityGroup 12}
aDtsdGid OBJECT-TYPE
SYNTAX INTEGER
ACCESS read-only
STATUS mandatory
DESCRIPTION "The group ID of the DCE DTS entity."
::= {dceDtsEntityGroup 13}
aDtsdInRpcCalls OBJECT-TYPE
SYNTAX Counter
ACCESS read-only
STATUS mandatory
DESCRIPTION "The number of RPC calls received by the DCE DTS entity."
::= {dceDtsEntityGroup 14}
aDtsdOutRpcCalls OBJECT-TYPE
SYNTAX Counter
ACCESS read-only
STATUS mandatory
DESCRIPTION "The number of RPC calls initiated by the DCE DTS entity."
::= {dceDtsEntityGroup 15}
aDtsdInRpcPkts OBJECT-TYPE
SYNTAX Counter
ACCESS read-only
STATUS mandatory
DESCRIPTION "The number of RPC packets received by the DCE DTS entity."
::= {dceDtsEntityGroup 16}
aDtsdOutRpcPkts OBJECT-TYPE
SYNTAX Counter
ACCESS read-only
STATUS mandatory
DESCRIPTION "The number of RPC packets initiated by the DCE DTS entity."
::= {dceDtsEntityGroup 17}
aDtsdState OBJECT-TYPE
SYNTAX DisplayString (SIZE (0..16))
ACCESS read-only
STATUS mandatory
DESCRIPTION "The state of this DCE DTS entity."
-- One of the following strings will be set based on the state value:
-- String Description
--
-- Unknown
-- Not running The server does not appear to be running.
-- Available The server is running and responding to requests.
-- Not available The server is running but is not responding to requests.
::= {dceDtsEntityGroup 18}
aDtsdStateValue OBJECT-TYPE
break=fit compact.
SYNTAX INTEGER
{
vUnknown (0),
vNotRunning (1),
vAvailable (2),
vNotAvailable (3)
}
ACCESS read-only
STATUS mandatory
DESCRIPTION "The state value of this DCE DTS entity.
::= {dceDtsEntityGroup 19}
ΓòÉΓòÉΓòÉ 10.1.17. DCE Distributed Time Service Server Group ΓòÉΓòÉΓòÉ
dceDtsSvrGroup OBJECT IDENTIFIER ::= {MIB 17}
aDtsSvrRole OBJECT-TYPE
break=fit compact.
SYNTAX Counter
{
vUnknown (0),
vLocal (1),
vGlobal (2)
}
ACCESS read-only
STATUS mandatory
DESCRIPTION "The role of the DTS server."
::= {dceDtsSvrGroup 1}
aDtsSvrCourierRole OBJECT-TYPE
break=fit compact.
SYNTAX INTEGER
{
vUnknown (0),
vCourier (1),
vBackup (2),
vNoncourier (3)
}
ACCESS read-only
STATUS mandatory
DESCRIPTION "A server's interaction with the set of global servers.
::= {dceDtsSvrGroup 2}
aDtsSvrDiffEpochs OBJECT-TYPE
SYNTAX Counter
ACCESS read-only
STATUS mandatory
DESCRIPTION "The number of times the node received time response messages that
had a different epoch number.
::= {dceDtsSvrGroup 3}
aDtsSvrNoGlobals OBJECT-TYPE
SYNTAX Counter
ACCESS read-only
STATUS mandatory
DESCRIPTION "The number of times the clock could not contact any global clocks."
::= {dceDtsSvrGroup 4}
aDtsSvrNotResponds OBJECT-TYPE
SYNTAX Counter
ACCESS read-only
STATUS mandatory
DESCRIPTION "The number of times the clock could not contact a
specific global clock."
::= {dceDtsSvrGroup 5}
aDtsSvrProviderErrors OBJECT-TYPE
SYNTAX Counter
ACCESS read-only
STATUS mandatory
DESCRIPTION "The number of times the external time provider signaled a failure or the
node was unable to access the time provider."
::= {dceDtsSvrGroup 6}
aDtsSvrRoleString OBJECT-TYPE
SYNTAX DisplayString (SIZE (0..16))
ACCESS read-only
STATUS mandatory
DESCRIPTION "The role of the DCE DTS server."
-- One of the following strings will be set based on the aDtsSvrRole value:
-- String Description
--
-- Unknown
-- Local
-- Global
-- Unavailable An error was encountered trying to retrieve the string.
-- Not applicable The object does not apply.
-- Clerk If there are no errors and the role is not Local or Global,
-- Clerk is used instead of Unknown.
::= {dceDtsSvrGroup 7}
aDtsSvrCourierRoleString OBJECT-TYPE
SYNTAX DisplayString (SIZE (0..16))
ACCESS read-only
STATUS mandatory
DESCRIPTION "A server's interaction with the set of global servers."
-- One of the following strings will be set based on the aDtsSvrCourierRole value:
-- String Description
--
-- Unknown
-- Courier
-- Backup
-- Noncourier
-- Unavailable An error was encountered trying to retrieve the string.
-- Not applicable The object does not apply.
::= {dceDtsSvrGroup 8}
ΓòÉΓòÉΓòÉ 10.1.18. DCE Distributed Time Service Known Server Table Group ΓòÉΓòÉΓòÉ
dtsKnownSvrTable OBJECT-TYPE
SYNTAX SEQUENCE OF DtsKnownSvrEntry
ACCESS not-accessible
STATUS mandatory
DESCRIPTION "A list of DCE DTS local or global servers known by this DCE DTS entity."
::= {MIB 18}
dtsKnownSvrEntry OBJECT-TYPE
SYNTAX DtsKnownSvrEntry
ACCESS not-accessible
STATUS mandatory
DESCRIPTION ""
INDEX {aDtsKnownSvrName}
::= {dtsKnownSvrTable 1}
DtsKnownSvrEntry ::= SEQUENCE
break=fit compact.
{
aDtsKnownSvrName DisplayString,
aLastPolled Date,
aLastObsSkew DisplayString,
aUsedInLastSync DisplayString,
aLastObsTime Date,
aDtsSvrProto INTEGER,
aDtsSvrProtoString DisplayString
}
aDtsKnownSvrName OBJECT-TYPE
SYNTAX DisplayString (SIZE (0..64))
ACCESS read-only
STATUS mandatory
DESCRIPTION "The name of the known DCE DTS server known by this host."
-- The string will be Unavailable when an error is encountered
-- trying to retrieve the string. The string will be Not applicable when
-- the object does not apply.
::= {dtsKnownSvrEntry 1}
aLastPolled OBJECT-TYPE
SYNTAX Date
ACCESS read-only
STATUS mandatory
DESCRIPTION "The time that the known DCE DTS server was last polled."
-- The string will be Unavailable when an error is encountered
-- trying to retrieve the string. The string will be Not applicable when
-- the object does not apply.
::= {dtsKnownSvrEntry 2}
aLastObsSkew OBJECT-TYPE
SYNTAX DisplayString (SIZE (0..32))
ACCESS read-only
STATUS mandatory
DESCRIPTION "The last observed time difference of the known DCE DTS server."
-- The string will be Unavailable when an error is encountered
-- trying to retrieve the string. The string will be Not applicable when
-- the object does not apply.
::= {dtsKnownSvrEntry 3}
aUsedInLastSync OBJECT-TYPE
SYNTAX DisplayString (SIZE (0..32))
ACCESS read-only
STATUS mandatory
DESCRIPTION "The time that the known DTS server was last synchronized."
-- The string will be Unavailable when an error is encountered
-- trying to retrieve the string. The string will be Not applicable when
-- the object does not apply.
::= {dtsKnownSvrEntry 4}
aLastObsTime OBJECT-TYPE
SYNTAX Date
ACCESS read-only
STATUS mandatory
DESCRIPTION "The time that the known DTS server was last observed."
-- The string will be Unavailable when an error is encountered
-- trying to retrieve the string. The string will be Not applicable when
-- the object does not apply.
::= {dtsKnownSvrEntry 5}
aDtsSvrProto OBJECT-TYPE
break=fit compact.
SYNTAX INTEGER
{
vUnknown (0),
vIEEE802_3 (1),
vDCEnet (2),
vUDPIP (3),
vTCPIP (4),
vRPC (5)
}
ACCESS read-only
STATUS mandatory
DESCRIPTION "The transport protocol of the known DTS server."
::= {dtsKnownSvrEntry 6}
aDtsSvrProtoString OBJECT-TYPE
SYNTAX DisplayString (SIZE (0..16))
ACCESS read-only
STATUS mandatory
DESCRIPTION "The transport protocol of the known DTS server."
-- One of the following strings will be set based on the aDtsSvrProto value:
-- String Description
--
-- Unknown
-- IEEE 802.3
-- DECnet
-- UDP/IP
-- TCP/IP
-- RPC
-- Unavailable An error was encountered trying to retrieve the string.
-- Not applicable The object does not apply.
::= {dtsKnownSvrEntry 7}
ΓòÉΓòÉΓòÉ 10.1.19. DCE Traps Group ΓòÉΓòÉΓòÉ
trapsGroup OBJECT IDENTIFIER ::= {MIB 19}
aEventType OBJECT-TYPE
SYNTAX DisplayString (SIZE (0..12))
ACCESS not-accessible
STATUS mandatory
DESCRIPTION "The type of the event."
-- The event type will be one of the following strings:
-- DCE Generic
-- DCE Service
::= {trapsGroup 1}
aEventText OBJECT-TYPE
SYNTAX DisplayString (SIZE (0..256))
ACCESS not-accessible
STATUS mandatory
DESCRIPTION "The description of the event."
::= {trapsGroup 2}
aEventSeverity OBJECT-TYPE
SYNTAX DisplayString (SIZE (0..16))
ACCESS not-accessible
STATUS mandatory
DESCRIPTION "The severity level of the event."
-- The event severity will be one of the following strings:
-- UNKNOWN
-- FATAL
-- ERROR
-- WARNING
-- NOTICE
-- NOTICE_VERBOSE
::= {trapsGroup 3}
aCellName OBJECT-TYPE
SYNTAX DisplayString (SIZE (0..64))
ACCESS not-accessible
STATUS mandatory
DESCRIPTION "The name of the cell where the event occurred."
::= {trapsGroup 4}
aHostName OBJECT-TYPE
SYNTAX DisplayString (SIZE (0..128))
ACCESS not-accessible
STATUS mandatory
DESCRIPTION "The name of the host where the event occurred."
::= {trapsGroup 5}
aTime OBJECT-TYPE
SYNTAX Date
ACCESS not-accessible
STATUS mandatory
DESCRIPTION "The time when the event occurred."
::= {trapsGroup 6}
aProgram OBJECT-TYPE
SYNTAX DisplayString (SIZE (0..32))
ACCESS not-accessible
STATUS mandatory
DESCRIPTION "The name of the program that generated the event."
::= {trapsGroup 7}
aComponent OBJECT-TYPE
SYNTAX DisplayString (SIZE (0..32))
ACCESS not-accessible
STATUS mandatory
DESCRIPTION "The name of the component that generated the event."
::= {trapsGroup 8}
aSubComponent OBJECT-TYPE
SYNTAX DisplayString (SIZE (0..32))
ACCESS not-accessible
STATUS mandatory
DESCRIPTION "The name of the subcomponent that generated the event."
::= {trapsGroup 9}
aThreadId OBJECT-TYPE
SYNTAX INTEGER
ACCESS not-accessible
STATUS mandatory
DESCRIPTION "The ID of the thread where the event occurred."
::= {trapsGroup 10}
aFile OBJECT-TYPE
SYNTAX DisplayString (SIZE (0..32))
ACCESS not-accessible
STATUS mandatory
DESCRIPTION "The name of the source file that generated the event."
::= {trapsGroup 11}
aLine OBJECT-TYPE
SYNTAX INTEGER
ACCESS not-accessible
STATUS mandatory
DESCRIPTION "The number of the source line that generated the event."
::= {trapsGroup 12}
(.txt)
(.txt)