Document revision date: 5 July 2000

This chapter provides reference pages for the X/Open Object Management (XOM) API functions.

Compaq's XOM implementation supports two additional ways to create private objects. The functions are as follows:

• The om_encode function uses the encoding rules you specify to create a private object independent of the original private object.
• The om_decode function decodes the ASN.1 of the original object to create the new one. You must specify the class of the existing object and the rules used to encode it.

For a description of the standard DCE XOM functions, refer to Chapter 4 of the OSF DCE Application Development Reference Manual.

Introduces the OM API functions.

Synopsis

#include <XOM.H>

Description

This reference page defines the functions of the C interface in the Compaq X.500 product.

Function	Description
om_copy	Copies a private object.
om_copy_value	Copies a string between private objects.
om_create	Creates a private object.
om_decode	Creates a new private object that decodes an existing ASN.1 private object.
om_delete	Deletes a private or service-generated object.
om_encode	Creates a new private object that encodes an existing private object.
om_get	Gets copies of attribute values from a private object.
om_instance	Tests an object's class.
om_put	Puts attribute values into a private object.
om_read	Reads a segment of a string in a private object.
om_remove	Removes attribute values from a private object.
om_write	Writes a segment of a string into a private object.

As indicated in the table, the service interface comprises a number of functions whose purpose and range of capabilities are summarized as follows:

Function	Description
om_copy	This function creates an independent copy of an existing private object and all its subobjects. The copy is placed in the original's workspace, or in another specified by the XOM application.
om_copy_value	This function 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 function 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_decode	This function creates a new private object by decoding the ASN.1 of the original object.
om_delete	This function deletes a service-generated public object, or makes a private object inaccessible.
om_encode	This function creates a new private object, the encoding, which exactly and independently encodes an existing private object, the original.
om_get	This function 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 function determines whether an object is an instance of a particular class. The client can determine an object's class simply by inspection. This function is useful because it reveals that an object is an instance of a particular class, even if the class is an instance of a subclass of that class.
om_put	This function places or replaces in one private object copies of the attribute values of another public object 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 function 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 function 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 function removes and discards particular values of an attribute of a private object. The attribute itself is removed if no values remain.
om_write	This function 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 because any elements beyond it are discarded. The function enables the client to write an arbitrarily long value without having to place a copy of the entire value in memory.

In the C interface, the functions are realized by macros. The function prototype in the synopsis of a function's specification shows the client's view of the function.

The intent of the interface definition is that each function 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.

Creates a new private object that decodes an existing ASN.1 private object.

Synopsis

OM _return_code om_decode(encoding, original)

C Binding

OM_return_code om_decode(encoding, original)

OM_private_object encoding,
OM_private_object #original

Arguments

Encoding

The encoded object that you want to decode. It must be an instance of the Encoding class.

Original

An object that is the decoded version of the encoding. The service creates this object in the workspace in which the encoding is located. The service returns this argument if the Return Code of the function is OM_SUCCESS.

Description

This function creates a new private object by decoding the ASN.1 of the original object.

In the Encoding argument, you specify the class of the existing object and the rules used to encode it. In the current version of the OM API, you must specify ASN.1 BER.

Return Values

Possible return values are as follows:

Return	Description
OM_SUCCESS	The function has completed its task successfully.
OM_ENCODING_INVALID	The value of the Object Encoding is invalid.
OM_FUNCTION_INTERRUPTED	The function was aborted by external intervention.
OM_MEMORY_INSUFFICIENT	There is not enough memory to complete the function.
OM_NETWORK_ERROR	The service cannot use the underlying network.
OM_NO_SUCH_CLASS	There is an undefined class identifier.
OM_NO_SUCH_OBJECT	You have specified a nonexistent object, or an invalid Handle for an object.
OM_NO_SUCH_RULES	There is an undefined rules identifier.
OM_NOT_AN_ENCODING	There is an object that is not an instance of the Encoding class.
OM_NOT_PRIVATE	There is a public object where there should be a private object.
OM_PERMANENT_ERROR	The service encountered a permanent problem for which there is no defined error code.
OM_POINTER_INVALID	An invalid pointer was supplied as a function argument.
OM_SYSTEM_ERROR	The service cannot use the operating system.
OM_TEMPORARY_ERROR	The service encountered a temporary problem for which there is no defined error code.
OM_TOO_MANY_VALUES	An implementation limit prevents the addition to an object of another attribute value.
OM_WRONG_VALUE_LENGTH	There is an attribute with a value that violates the value length constraints in force.
OM_WRONG_VALUE_MAKEUP	There is an attribute with a value that violates a constraint of its syntax.
OM_WRONG_VALUE_NUMBER	There is an attribute with a value that violates the value number constraints in force.
OM_WRONG_VALUE_SYNTAX	There is an attribute value with an illegal syntax.
OM_WRONG_VALUE_TYPE	There is an attribute value with an illegal type.

Examples

The following example shows the decoding of the object encoded in the code example from OSI-Abstract-Data Manipulation. The encoded object is encoding , and the decoded object is decoded_object .

OM_return_code result; OM_private_object encoding, decoded_object; result = om_decode (encoding, /* object to be decoded */ &decoded_object); /* decoded object */

Creates a new private object that encodes an existing private object.

Synopsis

OM _return_code om_encode(original, rules, encoding)

C Binding

OM_return_code(om_encode)(original, rules, encoding)

OM_private_object original,
OM_object_identifier rules,
OM_private_object #encoding

Arguments

Original

The object you want to encode.

Rules

The set of rules that the service must follow to produce an encoding. In this version of the OM API, you can only specify ASN.1 BER.

Encoding

An object that is the encoded version of the original. The service creates this object in the workspace in which the original is located. The service returns this argument if the Return Code of the function is OM_SUCCESS. The returned object is an instance of the Encoding class.

Description

This function creates a new private object, the encoding, which exactly and independently encodes an existing private object, the original. When you apply this function to a private object, the function uses the encoding rules you specify to create a new private object. The new encoded private object is independent of the original private object.

Return Values

Possible return values are as follows:

Return	Description
OM_SUCCESS	The function has completed its task successfully.
OM_FUNCTION_DECLINED	The function does not apply to the object to which it is addressed.
OM_FUNCTION_INTERRUPTED	The function was aborted by external intervention.
OM_MEMORY_INSUFFICIENT	There is not enough memory to complete the function.
OM_NETWORK_ERROR	The service cannot use the underlying network.
OM_NO_SUCH_OBJECT	You have specified a nonexistent object, or an invalid Handle for an object.
OM_NO_SUCH_RULES	There is an undefined rules identifier.
OM_NOT_PRIVATE	There is a public object where there should be a private object.
OM_PERMANENT_ERROR	The service encountered a permanent problem for which there is no defined error code.
OM_POINTER_INVALID	An invalid pointer was supplied as a function argument.
OM_SYSTEM_ERROR	The service cannot use the operating system.
OM_TEMPORARY_ERROR	The service encountered a temporary problem for which there is no defined error code.

Examples

The following example shows the encoding of an object of the MH class Report encodable_object . The object is encoded according to the rules CWOM_BER , and the encoded object is encoding .

OM_return_code result; OM_private_object encodable_object, encoding; result = om_encode (encodable_object, /* object to be encoded */ OM_BER, /* encoding rules */ &encoding); /* encoded object */

The following APIs are included in DCE Version 3.0 to create client credentials and to support server impersonation of a client. This means that the server runs with the security credentials of the client, and all of the capabilities of the client belong to the server. For additional information on RPC APIs, see the DCE Application Reference Manual and the DCE Administration Guide.

This function is called by the client RPC application to allocate and populate a WINNT auth_identity structure to be used as a parameter to rpc_binding_set_auth_info(). The caller must use the rpc_winnt_free_auth_identity() function to free the WINNT auth_identity. The strings that are passed in may be ASCII or Unicode (UCS-4) strings. The input flag will tell which type of strings they are.

Syntax

#include <RPC.H> PUBLIC void rpc_winnt_set_auth_identity ( rpc_winnt_auth_string_p_t Username; rpc_winnt_auth_string_p_t Password; rpc_winnt_auth_string_p_t Domain; unsigned __int64 CharacterSetFlag; rpc_auth_identity_handle_t *auth_identity; unsigned32 *stp)

Arguments

INPUT

username --- Pointer to null terminated string containing username password --- Pointer to null terminated string containing password domain --- Pointer to null terminated string containing domain

CharacterSetFlag

SEC_WINNT_AUTH_IDENTITY_UNICODE --- 4 byte Unicode (UCS-4)
SEC_WINNT_AUTH_IDENTITY_ANSI --- ASCII (ISO8859-1)

OUTPUT

auth_identity --- Pointer to a pointer to a WINNT auth_identity structure stp --- Pointer to returned status

Note Be sure to allocate space for three strings (username, password, domain). The string variables will probably be pointers of type unsigned_char_t if the strings are ASCII or pointers of type wchar_t if the strings are Unicode (UCS-4). If the domain string is a valid empty string, then the domain of the computer will be used.

This function is called by the client RPC application to free a WINNT auth_identity structure that was previously allocated by a call to rpc_winnt_set_auth_identity().

Syntax

#include <RPC.H> PUBLIC void rpc_winnt_free_auth_identity ( rpc_auth_identity_handle_t *auth_identity, unsigned32 *stp)

Arguments

INPUT

auth_identity --- Pointer to a pointer to a WINNT auth_identity structure. On output, auth_identity will be set to NULL.

OUTPUT

stp --- Pointer to returned status

Examples

The following code extract sets and frees the WINNT auth_identity.

#include <dce/rpc.h> int main () { /* */ /* Declare variables to be used */ /* */ rpc_auth_identity_handle_t auth_identity; unsigned_char_t username[255]; unsigned_char_t domain[255]; unsigned_char_t password[255]; error_status_t status; /* */ /* Initialize input arguments */ /* */ printf("Enter username: "); gets(username); printf("Enter password: "); gets(password); printf("Enter domain: "); gets(domain); /* */ /* Try to set the WINNT auth_identity */ /* for use in rpc_binding_set_auth_info() */ /* */ rpc_winnt_set_auth_identity(username, password, domain, SEC_WINNT_AUTH_IDENTITY_ANSI, (rpc_auth_identity_handle_t*)&auth_identity, &status); if (status != rpc_s_ok) { printf ("*** Can't set winnt auth identity\n"); } else { rpc_winnt_free_auth_identity((rpc_auth_identity_handle_t*)&auth_identity, &status); } return(1); }

This function is called by the server application to allow the current server thread to run with all of the client privileges.

Syntax

#include <RPC.H> void rpc_impersonate_client( rpc_binding_handle_t binding_handle, rpc_status_t *status)

Arguments

INPUT

binding_handle --- Specifies a server-side call handle for this RPC which represents the client to impersonate.

OUTPUT

status --- Specifies a pointer to an unsigned 32-bit integer that holds a status code.

	privacy and legal statement
6533_DCE_REF_PRO_008.HTML