═══ 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 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 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 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 #include 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 #include 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 #include 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 #include 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 #include 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 #include 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 #include 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 #include 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 #include 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 #include 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 #include 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 #include 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 #include 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 #include 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 #include 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 #include 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 #include 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 #include 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 . 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 /* 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 #include 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 #include 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 attributevalue2,... 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 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 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= (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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 #include 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 #include 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 #include 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 #include 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 #include 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 #include 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 #include 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 #include 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 #include 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 #include 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 #include 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 #include 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 #include 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 #include 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 #include 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 #include 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 #include 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 #include 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 #include 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 #include 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 #include 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 #include 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 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 #include 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 #include 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 #include 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 #include 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 #include #include #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 . 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 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 #include 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 #include 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 #include #include #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 #include 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 #include 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 #include #include #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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 #include 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 #include 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 #include 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 #include #include #include 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 #include 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 #include #include 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 #include #include 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 #include #include 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 #include #include 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 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_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 #include 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 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 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 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 #include 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 #include 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 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 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_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_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_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_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_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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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_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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 #include 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 #include 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 #include 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 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 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 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 #include 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 #include 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 #include 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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_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 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 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 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 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 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 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 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 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 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 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 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 #include 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 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 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 #include 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 #include 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 #include 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 #include 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 #include 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 #include 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 #include 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 #include 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 #include 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 #include 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 #include 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 #include 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 #include #include 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 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 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 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 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 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 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 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 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 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 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 #include 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 #include 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 #include 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 #include 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 #include 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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(, , &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, , 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 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 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 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 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 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(, , &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, , 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 #include ═══ 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 ═══ 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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(, 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 #include 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 #include 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 #include 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 #include 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 #include 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 #include 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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}