/* XDSHLI.H V5.6-3 *%COPYRIGHT_START% * * Copyright Digital Equipment Corporation 1993, 1995. All rights reserved * * Restricted Rights: Use, duplication, or disclosure by the U.S Government is * subject to restrictions as set forth in subparagraph (C) (1) (ii) of DFARS * 252.227-7013, or in FAR 52.227-19, or in FAR 52.227-14 Alt, III, as * applicable. Unpublished rights reserved under applicable copyright laws. * * This software is proprietary to and embodies the confidential technology of * Digital Equipment Corporation. Possession, use, or copying of this software * and media is authorized only pursuant to a valid written license from * Digital or an authorized sublicensor. * *%COPYRIGHT_END% */ /* **++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ ** ** The following are trademarks of Digital Equipment Corporation: ** DEC, OpenVMS, ULTRIX. ** **------------------------------------------------------------------------ */ /* **++ ** FACILITY: XDSHLI - extension to X.500 XDS/OM interface ** ** The XDS High Level Interface (XDSHLI) provides a set of useful services ** to help build XDS/OM applications. XDSHLI complements the XDS/OM API ** by hiding some of its complexities, but allowing access to these ** features if they are required. ** ** The services provided are: ** - simplifying the importing/exporting of useful OIDs defined in XDS/OM ** - the following routines: ** dsX_dn_string_to_object() - creates DN OM object from string ** dsX_dn_object_to_string() - creates DN string from OM object ** dsX_make_session() - creates session with credentials ** dsX_make_selection() - creates Entry-Information-Selection obj ** dsX_make_filter() - creates Filter object ** dsX_add_filter() - adds Filter object to Filter object ** dsX_add_filter_item() - adds Filter Item to Filter object ** dsX_add_substring_filter_item()- adds substring Filter Item to filter ** dsX_count_result_entries() - counts no of entries in results ** dsX_get_result_entry() - extracts Entry-Info from Search-Result ** dsX_find_entry_name() - finds name of Entry ** dsX_find_attribute() - finds a specified attribute in Entry ** dsX_find_next_attribute() - finds an attribute by index ** dsX_process_error() - returns information about an error ** omX_compare_om_strings() - compares om strings for equivalence ** omX_find_om_type() - finds an OM_descriptor in a public obj ** omX_count_om_types() - counts no of given OM types in object ** ** XDSHLI comprises of the following modules: ** XDSHLI.H - public include file and interface specification ** XDSHLI_IMPORT.H - imports declarations of useful OIDs ** XDSHLI_EXPORT.C - exports declarations of useful OIDs ** XDSHLI_NAME.C - provides name conversion service ** XDSHLI_FILTER.C - builds filter expressions ** XDSHLI_BUILD.C - builds other useful objects ** XDSHLI_PROCESS.C - finds and extracts information from objects ** XDSHLI_UTILS.C - various utility routines ** XDSHLI_PRIVATE.H - private XDSHLI include file ** ** An example of an application using XDSHLI is the XDS_SEARCH_EXAMPLE_1.C ** program in the [DXD] subdirectory of SYS$EXAMPLES directory (OpenVMS), ** or the /usr/examples/dxd directory (ULTRIX and Digital UNIX formerly ** DEC OSF/1). ** ** MODULE DESCRIPTION: ** ** This module is the main include file for this interface. ** It includes the required XDS/OM include files, defines ** the prototypes of functions available, imports the required ** symbols, and defines literals and macros. ** ** ENVIRONMENT: ** ** This module must be compiled with an ANSI C standard compiler. ** This module is fully rentrant as long as XDS, malloc(), free(), ** and printf() services support this, or are removed or replaced ** with services that are reentrant. ** ** The routines documented below perform minimal error checks. ** Features to be aware of are: ** - minimal validatation of input parameters: this makes the ** logic simpler and easier to understand. Any errors ** should be detected by XDS/OM or by the Directory. ** - where errors are detected in underlying services, they are ** detected and reported, and the appropriate return value ** is return across the XDSHLI interface. ** ** ** AUTHORS: ** ** IRD ** ** CREATION DATE: 26-Jul-1993 ** ** MODIFICATION HISTORY: ** ** 000 26-Jul-1993 IRD Creation ** 001 24-Aug-1993 IRD Minor changes to comments and interface. ** 002 27-Aug-1993 IRD Minor changes ** 003 1-Sep-1993 IRD Add dsX_count_result_entries() & minor changes ** 004 4-Sep-1993 IRD Change i/f to dsX_find_next_attribute, enhance ** functionality of dsX_add_substring_filter_item, ** and other minor changes. ** 005 24-Sep-1993 IRD Change to dsX_add_filter_item() ** 006 13-Oct-1993 CMB Minor changes to comments. ** 007 12-Nov-1993 IRD Change include statements ** 008 22-Nov-1993 IRD Describe name argument in dsX_process_error(). ** 009 02-Feb-1993 IRD Extend description of dsX_process_error(). **-- */ #ifndef XDSHLI_INCLUDED #define XDSHLI_INCLUDED /* ** ** INCLUDE FILES ** */ #include #include #include #include #include #include #include "xdshli_import.h" /* ** ** DEFINITIONS ** */ #define TRUE 1 #define FALSE 0 /* * Definition of an Enumerated type to identify classes of Error OM objects * returned by the XDS interface */ enum dsX_Error_Class { DSX_ABANDON_FAILED_ERROR, DSX_ATTRIBUTE_ERROR, DSX_COMMUNICATIONS_ERROR, DSX_LIBRARY_ERROR, DSX_NAME_ERROR, DSX_REFERRAL, DSX_SECURITY_ERROR, DSX_SERVICE_ERROR, DSX_SYSTEM_ERROR, DSX_UPDATE_ERROR } ; /* **++ ** This grammar defines the string format of Distinguished Names supported ** by dsX_dn_object_to_string() and dsX_dn_string_to_object(). ** The grammar is a subset of the RFC1485 String Representation ** of Distinguished Names. ** ** ::= ( ) ** | ** ** ::= ** ** ** ** ::= "," | ";" ** ** ::= ( ) *( " " ) ** ** ::= ** | "+" ** ** ** ::= ** | "=" ** ** ** ::= 1*( ) ** ** ::= letters, numbers, and space ** ** ::= *( | ) ** ** ::= "," | "=" | '"' | | "+" | "<" | ">" | "#" | ";" ** ** ::= any char except ** ** A NULL string indicates the root value ** ** Parts of RFC1485 not supported are: ** o Quoting of distinguished values. Therefore values cannot contain ** any of the characters, or leading and trailing spaces. ** o Attribute types which are expressed as Object Identifiers ** (eg 2.3.4). ** o Attribute values which are expressed in hexadecimal format (eg #4564). ** o Attribute values which are other than string syntax. **-- */ /* dsX_dn_string_to_object() **++ ** FUNCTIONAL DESCRIPTION: ** ** This function is used to convert a Distinguished Name in string format ** to an OM private object. The Distinguished Name must conform to the ** grammar defined above. The function returns a DS-DN OM private ** object. The encoding of the characters in the input string must be ** ISO-Latin-1. ** ** The return status is NULL if the DS-DN OM object cannot be created. ** A message is returned if a user error is detected parsing the ** input string. ** Parsing of the input string assumes that: ** 1 ) the format of the string conforms to the grammar for the External ** Representation ** 2 ) the keyword representing the attribute type is known to this ** function. It must be an exact match of the known types, or ** a unique partial match. If not, an error is returned. ** ** Examples of the input string format are ** cn=Francis Black, ou=Sales, o=Abacus, c=US ** and ** CN=Martin Jones, ** OU=Entertainment, ** O=Plus Films, ** C=GB ** ** ** FORMAL PARAMETERS: ** ** workspace: IN ** Value of OM workspace. ** ** name: IN ** Address of buffer containing null-terminated external ** representation of Distinguished Name to be processed. ** ** error_text: OUT ** Address of pointer to a buffer which contains an message. ** The pointer is modified to the address of the buffer ** allocated by this routine, which contains a null-terminated ** message describing an error parsing the input string. ** If the address is NULL, an error message is not returned. ** ** pos: OUT ** Address of an unsigned integer whose value is modified in the event ** of a parsing error to the index of the character in the input ** string where the problem was detected. If the addess is NULL, ** this value is not modified. ** ** RETURN VALUE: ** ** DS-DN OM private object representing input Distinguished Name if ** successful, or NULL if the object could not be created. ** ** CALLER OBLIGATIONS: ** ** Delete the returned DS-DN OM private object when no longer required ** by calling om_delete(). ** To deallocate the buffer 'error_text' using free() ** if an error message is returned. ** ** PRECONDITIONS: ** ** The caller must have created an OM workspace. **-- */ extern OM_private_object dsX_dn_string_to_object( OM_workspace workspace, /* IN - workspace */ char * name, /* IN - null-terminated string */ char ** error_text, /* OUT - pointer to error text */ unsigned int * pos /* OUT - pointer to error position */ ); /* dsX_dn_object_to_string() **++ ** FUNCTIONAL DESCRIPTION: ** ** This function is used to convert a Distinguished Name as an OM object ** to a string value. The input value must be a DS-DN OM object ** (private or public). The output string conforms to the grammar defined ** above. ** If an attribute type is unrecognised, the text 'unknown attribute' ** is inserted. If the syntax of an attribute value is not ** a string, or the external representation of the string cannot be created, ** NULL is returned. ** ** FORMAL PARAMETERS: ** ** name: IN ** Value of a DS-DN OM object to be converted to the external ** representation. The OM object may be private or public. ** ** RETURN VALUE: ** ** Address of a buffer containing a null-terminated external ** representation of the Distinguished Name, or NULL if there ** was an error. ** ** SIDE EFFECTS: ** ** None ** ** CALLER OBLIGATIONS: ** ** Deallocate the returned buffer when it is no longer required by ** calling free(). */ extern char * dsX_dn_object_to_string( OM_object name); /* IN - name object */ /* dsX_make_session() **++ ** FUNCTIONAL DESCRIPTION: ** ** This function generates a Session OM object that can be passed to ** ds_bind(). Specifically, this routine creates a Session OM object ** containing the credentials provided by the caller, and other default ** values. ** If the user provided credentials are NULL, the returned Session OM ** object contains no credentials. ** If the Session OM Object cannot be created, NULL is returned to the ** Caller. ** ** Note that this function assumes that the password is a stored ** in a Digital extension DSX_PASSWORD OM Attribute. This may not ** be portable to other implementations of XDS. ** ** FORMAL PARAMETERS: ** ** workspace: IN ** Value of OM workspace where the object is to be created. ** ** name: IN ** Value of a DS-DN OM private object which is the name of the ** requestor to be used in the credentials, or NULL if there is ** no name. ** ** password: IN ** Address of a buffer containing a null-terminated value of the ** password to be used in the credentials, or NULL if there is ** no password. ** ** RETURN VALUE: ** ** Session OM private object or NULL if an error is detected. ** ** ** SIDE EFFECTS: ** ** None ** ** CALLER OBLIGATIONS: ** ** Delete the returned Session OM private object when no longer required, ** using om_delete(). ** ** PRECONDITIONS: ** ** The caller must have created a OM workspace. ** The application defaults must contain the presentation address ** of the DSA which the session is to be established. ** See the Digital X.500 Directory Service Management guide. ** **-- */ extern OM_private_object dsX_make_session( OM_workspace workspace, /* IN - OM workspace */ OM_private_object name, /* IN - name object */ char *password ); /* IN - null-terminated password */ /* dsX_make_selection() **++ ** FUNCTIONAL DESCRIPTION: ** ** This function is used to generate a list of attributes which ** ds_read() or ds_search() are to return. Specifically, ** this function creates an Entry-Information-Selection OM private object ** from a given list of attribute types. If there are no attribute ** types, the Entry-Information-Selection OM object is set to return all ** attributes. ** The DS_INFORMATION_TYPE OM Attribute of this object is always ** set to the value of DS_TYPE_AND_VALUES. ** ** In the event of an error creating the object, NULL is returned. ** ** FORMAL PARAMETERS: ** ** workspace: IN ** Value of OM workspace where the object is to be created. ** ** attributes: IN ** Pointer to a null-terminated array of pointers to the ** OM_object_identifier which describe the Directory attributes to be ** included in this object, or NULL. ** ** RETURN VALUE: ** ** Entry-Information-Selection OM private object, or NULL if there ** was an error creating the object. ** ** SIDE EFFECTS: ** ** None ** ** CALLER OBLIGATIONS: ** ** Delete the returned OM object when it is no longer required using ** om_delete(). ** **-- */ extern OM_private_object dsX_make_selection( OM_workspace workspace, /* IN - workspace */ OM_object_identifier ** attributes /* IN - list of attributes required, null-terminated */ ); /* ** Filters specify which entries are to be returned in the results of a ** search. Filters are explained in X.511, and need to be understood ** before using these functions. ** ** The filter generation routines below permit the building ** of filter expressions in a simple way. The filter expressions ** must be built top down. ** ** For example, to find a person who is a clerk, and surname sounds ** something like 'Moore' or 'Shaw', a filter needs to be generated. ** A logical expression of the above filter is ** ** ( ** ObjectClass=Person ** AND ** Title=*Clerk* ** AND ** ( ** Surname=~Moore ** OR ** Surname=~Shaw ** ) ** ) ** ** The simplest method of generating this filter expression using ** XDSHLI is to create the AND filter and its filter-items, and ** then create the OR filter as a subordinate of the AND filter. ** The following pseudo-code fragment demonstrates how this might be done. ** ** ** ** -- Create the AND Filter ** AND_filter = dsX_make_filter(workspace, DS_AND) ; ** ** -- Add the 'ObjectClass=Person' Filter-Item to the AND Filter ** dsX_add_filter_item( AND_Filter, DS_A_OBJECT_CLASS, DS_EQUALITY, ** DS_O_PERSON, OM_S_OBJECT_IDENTIFIER ) ; ** ** -- Add the 'Title=*Clerk*' Filter Item to the AND Filter ** dsX_add_substring_filter_item( AND_Filter, DS_A_TITLE, "*Clerk*"); ** ** -- Create the OR Filter and add it as a subordinate to the AND Filter ** OR_filter = dsX_add_filter( AND_Filter, DS_OR ) ; ** ** -- Add the 'Surname=~Moore' Filter-Item to the OR Filter ** dsX_add_filter_item( OR_Filter, DS_A_SURNAME, DS_APPROXIMATE_MATCH, ** "Moore", OM_S_PRINTABLE_STRING ) ; ** ** -- Add the 'Surname=~Shaw' Filter-Item to the OR Filter ** dsX_add_filter_item( OR_Filter, DS_A_SURNAME, DS_APPROXIMATE_MATCH, ** "Shaw", OM_S_PRINTABLE_STRING ) ; ** ** ** The AND Filter is now passed to ds_search() to find the ** required entries. */ /* dsX_make_filter() **++ ** FUNCTIONAL DESCRIPTION: ** ** This function is used to create a top-level Filter OM object. ** Specifically, this routine creates a Filter OM private object with the ** given logical operator (one of DS_AND, DS_OR, or DS_NOT) in the ** given OM workspace. ** ** FORMAL PARAMETERS: ** ** workspace: IN ** Value of the OM workspace where the object is to be created. ** ** filter_type: IN ** Member of OM enumeration DS_Filter_Type indicating logical ** operation of Filter object. ** ** RETURN VALUE: ** ** The generated Filter private OM object or NULL if the object ** could not be created. ** ** SIDE EFFECTS: ** ** None ** ** PRECONDITIONS: ** ** The caller must have created an OM workspace. ** ** CALLER OBLIGATIONS: ** ** If the returned OM object is the 'top' of a filter ** expression and the whole filter is no longer required, delete ** the returned OM object using om_delete(). ** **-- */ extern OM_private_object dsX_make_filter( OM_workspace workspace, /* IN - workspace */ OM_enumeration filter_type /* IN - logical operator */ ); /* dsX_add_filter() **++ ** FUNCTIONAL DESCRIPTION: ** ** This function is used to add a Filter to a parent Filter. Specifically, ** this function inserts a subordinate Filter OM object with the given ** logical operator (one of DS_AND, DS_OR, or DS_NOT), into the given ** parent Filter OM object. ** The returned value is the subordinate Filter OM private object, ** or NULL if the operation failed. ** ** FORMAL PARAMETERS: ** ** filter: IN/MODIFIED ** Filter OM private object which will be modified to reference a ** subordinate Filter OM private object. ** ** filter_type: IN ** Value representing logical operation of the subordinate Filter OM ** private object. Member of the DS_Filter_Type OM enumeration ** ** RETURN VALUE: ** ** Value of the subordinate Filter OM private object, or NULL if ** the operation failed. ** ** SIDE EFFECTS: ** ** Modifies the parent Filter OM private object.If the operation ** fails, the parent Filter OM private object is unchanged. ** **-- */ extern OM_private_object dsX_add_filter( OM_private_object filter, /* IN/MOD - parent filter */ OM_enumeration filter_type /* IN - logical operator */ ); /* dsX_add_filter_item() **++ ** FUNCTIONAL DESCRIPTION: ** ** This function is used to place a filter item into a filter. ** Specifically, this routine adds a Filter-Item OM object containing ** the given Attribute Type, Value, and relational operator ** (one of DS_EQUALITY, DS_APPROXIMATE_MATCH etc) to the given parent ** Filter OM Object. If the operation succeeds, the value of the ** Filter-Item OM private object is returned, otherwise NULL is returned. ** If the relational operator is DS_PRESENT, an attribute value ** is not required, and the 'value' and 'value_syntax' parameters ** are ignored. ** ** FORMAL PARAMETERS: ** ** filter: IN/MODIFIED ** Value of the parent Filter OM private object that is to be ** modified to refer to the Filter-Item OM object. ** ** type: IN ** Address of an OM_object_identifier which refers to the Object ** Identifier of the X.500 Attribute Type to be included in the ** Filter-Item OM object. ** ** filter_item_type: IN ** Value of the one of the relational operators which are specified ** in DS_Filter_Item_Type OM enumeration, which the Filter-Item ** OM object is to take. ** ** value: IN ** Address of an OM value structure which contains the attribute ** value to be included in the Filter-Item OM object. ** If the value of the 'filter_item_type' parameter is DS_PRESENT, ** the value of this parameter is ignored. ** ** value_syntax: IN ** The value of the syntax of 'value' parameter. This is one of the ** syntax (OM_S_...) bitmasks. ** If the value of the 'filter_item_type' parameter is DS_PRESENT, ** the value of this parameter is ignored. ** ** ** ** ** RETURN VALUE: ** ** None. ** ** SIDE EFFECTS: ** ** Modifies the parent Filter OM private object.If the operation ** fails, the parent Filter OM private object is unchanged. ** **-- */ extern void dsX_add_filter_item( OM_private_object filter, /* IN/MOD- parent filter */ OM_object_identifier * type, /* IN - attribute type */ OM_enumeration filter_item_type,/* IN - relational operator*/ OM_value * value, /* IN - value */ OM_syntax value_syntax /* IN - value syntax */ ); /* dsX_add_substring_filter_item() **++ ** FUNCTIONAL DESCRIPTION: ** ** This function is used to create a filter item containing wildcards ** and insert it into a filter. Specifically, this function generates ** a Filter-Item OM object and inserts it into the given parent Filter ** OM private object. ** ** The Filter-Item OM object is generated from the Directory attribute ** type indicated by the 'type' parameter, and the substring values ** in the 'value' parameter. ** The 'values' parameter references a string. The string may contain ** substring values separated by wildcard characters ('*'). ** ** Examples of such values and their meanings are: ** "J*Smith" - initial substring of 'J', final substring of 'Smith' ** "J*Sm*th*" - initial substring of 'J', a sequence of substrings ** of 'Sm' and 'th', no final substring ** ** If the string value does not contain any wildcard characters, ** a filter item of type DS_EQUALITY is generated. ** If the string contains only one or more wildcards and no other ** characters, or it is NULL or empty, the filter DS_PRESENT is generated. ** ** FORMAL PARAMETERS: ** ** filter: IN/MODIFIED ** Filter OM private object which is to be modified to reference ** the Filter-Item OM object containing the substrings. ** type: IN ** Address of an OM_object_identifier describing the object identifier ** of Directory Attribute Type to be used in the Filter-Item OM ** object. ** value: IN ** Address of a null-terminated character buffer which contains ** the string value to be expressed in the Filter-Item. ** If the value contains a wildcard ('*') character, it is treated ** as a separator of substrings, and the substrings are assigned ** appropriate meanings and inserted into the Filter-Item OM object. ** If no wildcard characters are in the string, a Filter-Item ** of type equality is created. ** ** RETURN VALUE: ** ** None. ** ** SIDE EFFECTS: ** ** Modifies the parent Filter OM private object. ** **-- */ extern void dsX_add_substring_filter_item( OM_private_object filter, /* IN/MOD- parent filter */ OM_object_identifier * type, /* IN - attribute type */ char * value /* IN - value string */ ); /* dsX_count_result_entries() **++ ** FUNCTIONAL DESCRIPTION: ** ** This function is used to determine the initial status of the results ** of a search. Specifically, this function returns the number of entries ** in a Search-Result OM private object, and indicates if the results are ** complete, or if a Partial Outcome Qualifier is present. ** ** FORMAL PARAMETERS: ** ** result: IN ** Search-Result OM private object which is to be checked. ** ** count: OUT ** Address of an unsigned integer whose value is modified to ** indicate the number of Entry-Information OM objects present ** in the results. ** ** is_complete OUT ** Address of an unsigned integer which is modified to either TRUE ** if the results are complete, or FALSE if a ** Partial-Outcome Qualifier OM object is present in the results. ** ** RETURN VALUE: ** ** None. ** ** SIDE EFFECTS: ** ** None. ** **-- */ extern void dsX_count_result_entries( OM_private_object result, /* IN - search result */ unsigned int * count, /* OUT - no. of entries in result*/ unsigned int * is_complete /* OUT - if results are complete*/ ); /* dsX_get_result_entry() **++ ** FUNCTIONAL DESCRIPTION: ** ** This function returns an entry from the results of a search. ** Specifically, this function returns an Entry-Information OM public ** object from the given Search-Result OM private object, indexed by the ** value of the 'pos' paremeter. ** If the value of the 'pos' index is greater than the number of ** Entry-Information OM objects in the Search-Results, NULL is ** returned. ** The input value of 'pos' is zero if the first Entry-Information ** in the Search-Result is to be selected. ** ** FORMAL PARAMETERS: ** ** result: IN ** Search-Result OM private object containing the entry information ** required. ** ** pos: IN/MODIFIED ** Address of an OM_value_position which specifies the index of ** the Entry-Information OM object to be returned. The first ** Entry-Information in a Search-Results is indicated by the input ** value of zero, the second by that input value of one, and so on. ** The value is incremented if an object is returned. If an object ** is not returned, the output behavior of 'pos' is undefined. ** ** RETURN VALUE: ** ** Entry-Information OM public object, or NULL if the Entry-Information ** OM object specified by 'pos' there were no further entries in the ** results, or the operation failed. ** ** SIDE EFFECTS: ** ** None. ** ** CALLER OBLIGATIONS: ** ** To delete the returned Entry-Information OM object when no longer ** required by calling om_delete(). ** **-- */ extern OM_public_object dsX_get_result_entry( OM_private_object result, /* IN - search result */ OM_value_position *pos /* IN/MOD - entry to read, incremented on exit */ ); /* dsX_find_entry_name() **++ ** FUNCTIONAL DESCRIPTION: ** ** This function finds and returns the Name of an entry. Specifically, ** this function finds the DS-DN OM public object representing the name ** of an Directory entry described by the given Entry-Information OM ** public object, and returns a pointer to it. ** If the name of the entry cannot be found, NULL is returned. ** ** FORMAL PARAMETERS: ** ** entry: IN ** Entry-Information OM public object which contains the information ** required. ** ** RETURN VALUE: ** ** DS-DN OM public object, or NULL if the operation failed. ** ** SIDE EFFECTS: ** ** None. ** ** CALLER OBLIGATIONS: ** ** Not to delete the returned DS-DN OM object; it's ** a member of the given Entry-Information OM object. ** **-- */ extern OM_public_object dsX_find_entry_name( OM_public_object entry /* IN - entry-information */ ); /* dsX_find_attribute() **++ ** FUNCTIONAL DESCRIPTION: ** ** This function finds and returns information about a specific attribute ** in an entry. Specifically, this function finds the required Attribute ** OM object in the given Entry-Information OM object, and returns ** information about it. ** It returns a pointer to the first OM descriptor of type ** DS_ATTRIBUTE_VALUES, and the number of values that exist, in the ** Attribute OM object corresponding to the Directory Attribute Type ** indicated by the 'type' parameter. ** This function is likely to be used in conjunction with ** dsX_get_result_entry(). ** ** FORMAL PARAMETERS: ** ** entry: IN ** Entry-Information OM public object which contains the information ** required. ** ** type: IN ** Address of an OM_object_identifier that specifies the object ** identifier of the Directory Attribute type that the caller ** requires the values for. If the Directory Attribute type ** does not exist in the results, a 'count' of zero is returned, ** and the 'value' output paramter is NULL. ** ** count: OUT ** Address of an unsigned integer that is modified to indicate the ** number of values that exist for this Directory Attribute Type. ** ** value: OUT ** Address of pointer to the first OM_descriptor of type ** DS_ATTRIBUTE_VALUES in the Attrribute OM object that corresponds ** to the Directory Attribute Type specified by the 'type' input ** parameter. If the attribute exists, but no values exist in the ** Entry-Information OM public object (due to access control in ** the Directory), the 'value' will reference an OM descriptor ** whose OM_type field is not DS_ATTRIBUTE_VALUES. ** ** RETURN VALUE: ** ** None. ** ** SIDE EFFECTS: ** ** None. ** ** PRECONDITIONS: ** ** The caller must have created a OM workspace. ** **-- */ extern void dsX_find_attribute( OM_public_object entry, /* IN - in expanded entry */ OM_object_identifier * type, /* IN - attribute type */ unsigned int * count, /* OUT - count of values */ OM_descriptor ** value /* OUT - pointer to first value */ ); /* dsX_find_next_attribute() **++ ** FUNCTIONAL DESCRIPTION: ** ** This function finds and returns information about an attribute ** in an entry. Specifically, this function returns information about ** an Attribute OM object in a Entry-Information OM object indicated ** by the value of 'pos'. ** The routine returns a pointer to the first DS_ATTRIBUTE_VALUES ** OM descriptor, and the number of values in the Attribute OM object. ** If the 'pos' parameter exceeds the number of Attribute OM objects ** in the Entry-Information OM object, 'count' is returned as zero, ** and 'value' as NULL. ** The referenced value of 'pos' is incremented on return. ** ** FORMAL PARAMETERS: ** ** entry: IN ** Entry-Information OM public object containing the Attribute OM ** objects to be returned. ** ** pos: IN/MODIFIED ** Address of an unsigned integer that indicates the position of the ** Attribute OM object in the Entry-Information OM object ** about which information is required. This value is incremented ** on return. To select the first attribute, the value of 'pos' ** should be 0. ** ** type: OUT ** Address of a pointer to an OM_object_identifier, where the pointer ** is modified to point to an OM_object_identifier referencing ** Directory Attribute Type. ** ** count: OUT ** Address of an integer which is modified to indicate the number of ** values in the Attribute OM object specified by the 'pos' input ** value. ** If such an Attribute OM object specified by the input value of ** 'pos' does not exist, this value is returned as zero. ** ** value: OUT ** Address of a pointer to an OM_descriptor, where the pointer is ** modified to point to the first OM descriptor of type ** DS_ATTRIBUTE_VALUES in the Attribute OM object specified by the ** 'pos' input value. ** If such an Attribute OM object does not exist, this value ** is returned as NULL. If the Attribute OM object does exist, ** but there no values have been returned (due to access control ** in the Directory), value references an OM descriptor whose ** OM_type field is not DS_ATTRIBUTE_VALUES. ** ** RETURN VALUE: ** ** None ** ** SIDE EFFECTS: ** ** None. ** ** PRECONDITIONS: ** ** The caller must have created a OM workspace. ** ** **-- */ extern void dsX_find_next_attribute( OM_public_object entry, /* IN - in expanded entry */ unsigned int * pos, /* IN/OUT - attribute pointer */ OM_object_identifier ** type, /* OUT - attribute type */ unsigned int * count, /* OUT - count of values */ OM_descriptor ** value /* OUT - pointer to first value */ ); /* dsX_process_error() **++ ** FUNCTIONAL DESCRIPTION: ** ** This function returns information about an Error OM object, provided ** from a Directory operation. ** This routine returns the class of the error, the problem code, ** and a text message describing the problem. ** If the error is unrecognised, or cannot be processed, all parameters ** returned are NULL. ** If the OM object is a Referral, only the error_class parameter ** is returned. The calling application must decide how to handle this ** status. ** ** FORMAL PARAMETERS: ** ** error: IN ** Value of type DS_status containing the error information. ** ** error_class: OUT ** Pointer to a variable of enumerated type dsX_Error_Class ** which is modified to indicate the class of the error detected. ** If the error is unrecognised, the pointer is modified to NULL. ** ** problem: OUT ** Pointer to variable of OM enumeration type DS_Problem, which is ** modified to indicate the problem type of Error. ** If the OM object is a Referral, or unrecognised, the pointer is ** modified to NULL. ** ** text: IN/MODIFIED ** Address of a pointer to a text buffer; the pointer is modified ** to the address of a null-terminated buffer containing text ** that describes the problem. ** If the value of the 'text' input parameter is NULL, ** no message is provided by the function. ** If the OM object is a Referral, or unrecognised, the pointer is ** modified to NULL. ** ** name: IN/MODIFIED ** Address of a pointer to a text buffer; the pointer is modified ** to the address of a null-terminated buffer containing the textual ** representation of the Distinguished Name returned in the error. ** If the value of the 'name' input parameter is NULL, ** no name is returned by the function. ** If the Error does not contain a Distinguished Name, or a Referral ** is received, pointer is modified to NULL. ** ** RETURN VALUE: ** ** None ** ** SIDE EFFECTS: ** ** None. ** ** CALLER OBLIGATIONS: ** ** Deallocate the 'text' buffer and 'name' buffer when no longer required. ** **-- */ extern void dsX_process_error( DS_status error, /* IN - error object */ enum dsX_Error_Class * error_class, /* OUT - class of error */ OM_enumeration * problem, /* OUT - problem enumeration */ char ** text, /* OUT - text error message, if required */ char ** name /* OUT - text DN, if required if available */ ); /* omX_find_om_type() **++ ** FUNCTIONAL DESCRIPTION: ** ** This functions finds the required OM_descriptor in a given ** OM public object, and returns a pointer to it. ** The routine steps through a given public object, and returns ** an address of the OM_descriptor whose OM_type field matches the ** value passed in. If no match is found, NULL is returned. ** Sub-objects are not searched. ** ** FORMAL PARAMETERS: ** ** object: IN ** Value of an OM_public_object to be searched. ** ** type: IN ** Value of the OM_type field of the OM_descriptor to be returned ** RETURN VALUE: ** ** Address of the OM_descriptor in 'object' whose OM_type value ** matches 'type'. ** ** SIDE EFFECTS: ** ** None. ** ** CALLER OBLIGATIONS: ** ** None **++ */ extern OM_descriptor *omX_find_om_type(OM_public_object object, OM_type type ); /* omX_count_om_types() **++ ** FUNCTIONAL DESCRIPTION: ** ** This functions returns the number of instances of a type of ** OM descriptor in a given public object. ** The routine finds the first occurance of the OM Attribute type ** in the given OM public object, and then returns the total ** number of OM descriptors of that type. ** ** FORMAL PARAMETERS: ** ** object: IN ** An OM_public_object to be searched. ** ** type: IN ** The OM_type field of the OM_descriptor to be counted ** ** RETURN VALUE: ** ** Number of occurances of the type in the OM public object. ** ** SIDE EFFECTS: ** ** None. ** ** CALLER OBLIGATIONS: ** ** None **++ */ extern unsigned int omX_count_om_types( OM_public_object object,/* IN - object to be searched */ OM_type type );/* IN - type to be counted */ /* omX_compare_om_strings() **++ ** FUNCTIONAL DESCRIPTION: ** ** This functions compares two given strings, and indicates if ** their contents match. ** The routine compares the lengths of the strings, and if ** if these are the same, compares the contents of the strings for ** equality. ** ** FORMAL PARAMETERS: ** ** string1: IN ** Address of a OM_string value to be compared. ** ** string2: IN ** Address of a OM_string value to be compared. ** ** RETURN VALUE: ** ** OM_TRUE is the strings are identical, OM_FALSE if they are not. ** ** SIDE EFFECTS: ** ** None. ** ** CALLER OBLIGATIONS: ** ** None **++ */ extern OM_boolean omX_compare_om_strings( OM_string *string1, OM_string *string2); #endif /* XDSHLI_INCLUDED */