Return to q-operations.tex CVS log

Up to [CSRG BSD Unix] / 43BSDReno / contrib / isode-beta / doc / manual

Annotation of 43BSDReno/contrib/isode-beta/doc/manual/q-operations.tex, revision 1.1

1.1     ! root        1: % run this through LaTeX with the appropriate wrapper
        !             2: 
        !             3: \chapter {The Procedural DUA}
        !             4: \label{DUA:proc}
        !             5: 
        !             6: The \man libdsap(3n) library defines a set of procedure calls which
        !             7: correspond to each 
        !             8: of the X.500 abstract operations.
        !             9: This chapter describes those procedure calls.
        !            10: 
        !            11: \section {Procedure Model}
        !            12: \label{proc_model}
        !            13: 
        !            14: Each operation is accessed via a procedure call of the same name as the
        !            15: operation, prefixed by ``\verb"ds_"''.
        !            16: The procedure is supplied an argument structure, and returns either an error
        !            17: or result structure.
        !            18: For example the \verb"read" operation is invoked by calling
        !            19: \verb"ds_read (argument,error,result)".
        !            20: 
        !            21: The return value of the procedures have the following common values, which
        !            22: indicated whether an error or result is returned:-
        !            23: \begin{describe}
        !            24: \item [\verb"DS\_OK":]        Operation completed successfully, the result
        !            25: structure will have the corresponding result (if the operation generates
        !            26: results).
        !            27: \item [\verb"DS\_ERROR\_LOCAL":] Error within the DUA module.
        !            28: \item [\verb"DS\_ERROR\_CONNECT":] Failed to connect to a remote DSA.
        !            29: \item [\verb"DS\_ERROR\_PROVIDER":] Other OSI provider error.
        !            30: \item [\verb"DS\_ERROR\_REMOTE":] Remote error.  Further details will  
        !            31: be in the error parameter in the procedure call.
        !            32: \item [\verb"DS\_X500\_ERROR":] This is the same as \verb"DS_ERROR_REMOTE".
        !            33: \end{describe}
        !            34: These values defined in \file{quipu/ds\_error.h}, which must be included
        !            35: in your program (there are other return values defined here, but these
        !            36: should only occur within the DSA, and should not be returned by a DUA call).
        !            37: 
        !            38: \section {Common Parameters}
        !            39: All of the DAP operations described in Sections \ref{dap:bind} to \ref{modifyrdn}
        !            40: have certain common parameters in their arguments and results.
        !            41: These structures are now described.
        !            42: 
        !            43: 
        !            44: \subsection {Arguments}
        !            45: \label{common_args}
        !            46: 
        !            47: The common arguments are represented by the following structure:-
        !            48: \begin{quote}\index{CommonArgs}\small\begin{verbatim}
        !            49: typedef struct common_args {
        !            50:     ServiceControl        ca_servicecontrol;
        !            51:     DN                    ca_requestor;
        !            52:     struct op_progress    ca_progress;
        !            53:     int                   ca_aliased_rdns;
        !            54: #define CA_NO_ALIASDEREFERENCED -1
        !            55:     struct security_parms * ca_security;
        !            56:     struct signature    * ca_sig;
        !            57:     struct extension    * ca_ext;
        !            58: } CommonArgs;
        !            59: \end{verbatim}\end{quote}
        !            60: 
        !            61: The fields \verb"ca_ext", \verb"ca_progress", \verb"ca_requestor" 
        !            62: and \verb"ca_aliased_rdns" are provided as
        !            63: they are defined within X.500.  Neither the QUIPU DSA or DUA use these fields.
        !            64: 
        !            65: The field \verb"ca_servicecontrol" is used to select the type of service
        !            66: the DSA should provide, the structure is given below
        !            67: 
        !            68: \begin{quote}\index{ServiceControl}\small\begin{verbatim}
        !            69: typedef struct svccontrol {    
        !            70:     int         svc_options;
        !            71: #define SVC_OPT_PREFERCHAIN             0X001
        !            72: #define SVC_OPT_CHAININGPROHIBIT        0X002
        !            73: #define SVC_OPT_LOCALSCOPE              0X004
        !            74: #define SVC_OPT_DONTUSECOPY             0X008
        !            75: #define SVC_OPT_DONTDERFERERENCEALIAS   0X010
        !            76:     char        svc_prio;
        !            77: #define SVC_PRIO_LOW    0
        !            78: #define SVC_PRIO_MED    1
        !            79: #define SVC_PRIO_HIGH   2
        !            80:     int         svc_timelimit; 
        !            81: #define SVC_NOTIMELIMIT -1
        !            82:     int         svc_sizelimit;
        !            83: #define SVC_NOSIZELIMIT -1
        !            84:     int         svc_scopeofreferral;
        !            85: #define SVC_REFSCOPE_NONE       -1
        !            86: #define SVC_REFSCOPE_DMD        0
        !            87: #define SVC_REFSCOPE_COUNTRY    1
        !            88: } svccontrol, ServiceControl;
        !            89: \end{verbatim}\end{quote}
        !            90: 
        !            91: The values takes by each field within the ServiceControl
        !            92: structure are described in full
        !            93: in \cite{CCITT.Directory}.
        !            94: 
        !            95: \subsection {Results}
        !            96: \label{common_results}
        !            97: 
        !            98: \begin{quote}\index{CommonResults}\small\begin{verbatim}
        !            99: typedef struct common_results {
        !           100:     DN      cr_requestor;
        !           101:     char    cr_aliasdereferenced;
        !           102: } common_results, CommonResults;
        !           103: \end{verbatim}\end{quote}
        !           104: 
        !           105: The filed \verb"cr_aliasdereferenced" is set to \verb"TRUE" if the base
        !           106: object of the operation was an alias, and was dereferenced.
        !           107: 
        !           108: The field \verb"cr_requestor" is provided as
        !           109: it is are defined within X.500.  Neither the QUIPU DSA or DUA use this field.
        !           110: 
        !           111: 
        !           112: \section {Continuation References}
        !           113: \label{cont_ref}
        !           114: 
        !           115: ``Continuation References'' are returned by the directory when the operation
        !           116: asked for could not be fully completed, in which case
        !           117: the structure \verb"ContinuationRef" is returned as part of the error or
        !           118: results structures.
        !           119: The structure is explained below:-
        !           120: 
        !           121: \begin{quote}\index{ContinuationRef}\small\begin{verbatim}
        !           122: typedef struct continuation_ref {
        !           123:     DN          cr_name;
        !           124:     struct op_progress cr_progress;
        !           125:     int         cr_rdn_resolved;
        !           126: #define CR_RDNRESOLVED_NOTDEFINED  -1
        !           127:     int         cr_aliasedRDNs;
        !           128: #define CR_NOALIASEDRDNS -1
        !           129:     int         cr_reftype;
        !           130: #define RT_UNDEFINED    -1
        !           131: #define RT_SUPERIOR     1
        !           132: #define RT_SUBORDINATE  2
        !           133: #define RT_CROSS        3
        !           134: #define RT_NONSPECIFICSUBORDINATE 4
        !           135:     struct access_point * cr_accesspoints;
        !           136:     struct continuation_ref *cr_next;
        !           137: }continuation_ref, *ContinuationRef;
        !           138: \end{verbatim}\end{quote}
        !           139: 
        !           140: \begin{describe}
        !           141: \item [\verb"cr\_name":] The DN that has only been partially explored.
        !           142: \item [\verb"cr\_rdn\_resolved":] The number of RDNs in the name that have
        !           143: been examined --- hence how far down the DIT the query has been taken.
        !           144: \item [\verb"cr\_aliasedRDNs":] If \verb"TRUE" then some of the RDNs were
        !           145: aliases.
        !           146: \item [\verb"cr\_reftype":] The type of reference that was used to get this
        !           147: information.
        !           148: \item [\verb"cr\_accesspoints":] The access point of the DSA to 
        !           149: contact\footnote{The was an \verb+access\_point+, not \verb+access\_point *+ in
        !           150: ISODE-5.0.}.
        !           151: The structure for an access point is as follows:-
        !           152: \begin{quote}\index{access\_point}\small\begin{verbatim}
        !           153: struct access_point { 
        !           154:     DN                  ap_name;
        !           155:     struct PSAPaddr     *ap_address;
        !           156:     struct access_point *ap_next;
        !           157: };
        !           158: \end{verbatim}\end{quote}
        !           159: \begin{describe}
        !           160: \item [\verb"ap\_name":] The DN of the DSA to contact.
        !           161: \item [\verb"ap\_address":] The address of the DSA (derivable from 
        !           162: the name)\footnote{The was an \verb+PSAPaddr+, not \verb+PSAPaddr *+ in
        !           163: ISODE-5.0.}.
        !           164: \item [\verb"ap\_next":] There may be more than one access point, hence they
        !           165: form a linked list structure.
        !           166: \end{describe}
        !           167: \item [\verb"cr\_next":] There may be more than one access point, if so they form
        !           168: a linked list structure.
        !           169: \end{describe}
        !           170: 
        !           171: 
        !           172: \section {Errors}
        !           173: 
        !           174: All DAP operations return a common error structure, which maps closely 
        !           175: onto the service definitions.
        !           176: An error is only returned if the operation failed, if successful (indicated
        !           177: by the return value DS\_OK) the error structure returned is undefined.
        !           178: 
        !           179: \begin{quote}\index{DSError}\small\begin{verbatim}
        !           180: struct DSError {
        !           181:     int dse_type;
        !           182: #define DSE_LOCALERROR          -2
        !           183: #define DSE_REMOTEERROR         -1
        !           184: #define DSE_NOERROR             0
        !           185: #define DSE_ATTRIBUTEERROR      1
        !           186: #define DSE_NAMEERROR           2
        !           187: #define DSE_SERVICEERROR        3
        !           188: #define DSE_REFERRAL            4
        !           189: #define DSE_ABANDONED           5
        !           190: #define DSE_SECURITYERROR       6
        !           191: #define DSE_ABANDON_FAILED      7
        !           192: #define DSE_UPDATEERROR         8
        !           193: #define DSE_DSAREFERRAL         9
        !           194:     union {
        !           195:        struct DSE_attribute    dse_un_attribute;
        !           196:        struct DSE_name         dse_un_name;
        !           197:        struct DSE_service      dse_un_service;
        !           198:        struct DSE_referral     dse_un_referral;
        !           199:        struct DSE_abandon_fail dse_un_abandon_fail;
        !           200:        struct DSE_security     dse_un_security;
        !           201:        struct DSE_update       dse_un_update;
        !           202:     }   dse_un;
        !           203: };
        !           204: \end{verbatim}\end{quote}
        !           205: 
        !           206: The field \verb"dse_type" is used to indicate what sort of error has
        !           207: occurred, and hence which structure from the union is used.
        !           208: 
        !           209: The value \verb"DSE_LOCALERROR" is used to indicate that the 
        !           210: error came from within the DUA, there is no associated 
        !           211: structure in the union for this error.
        !           212: 
        !           213: The value \verb"DSE_REMOTEERROR" is used to indicate that an
        !           214: error occurred at the DSA end, and the request was rejected, again  there is
        !           215: no associated structure in the union for this error.
        !           216: 
        !           217: The structures in the union for the other
        !           218: error conditions are as described in the following Sections.
        !           219: 
        !           220: 
        !           221: \subsection{Attribute Error}
        !           222: \begin{quote}\small\begin{verbatim}
        !           223: struct DSE_attribute {
        !           224:     DN DSE_at_name;
        !           225:     struct DSE_at_problem DSE_at_plist;
        !           226: };
        !           227: \end{verbatim}\end{quote}
        !           228: 
        !           229: \begin{describe}
        !           230: \item [\verb"DSE\_at\_name":] The name of the entry causing the error.
        !           231: \item [\verb"DSE\_at\_plist":] A list of the errors:-
        !           232: \begin{quote}\small\begin{verbatim}
        !           233: struct DSE_at_problem {
        !           234:     int                     DSE_at_what;
        !           235: #define DSE_AT_NOSUCHATTRIBUTE          1
        !           236: #define DSE_AT_INVALIDATTRIBUTESYNTAX   2
        !           237: #define DSE_AT_UNDEFINEDATTRIBUTETYPE   3
        !           238: #define DSE_AT_INAPPROPRIATEMATCHING    4
        !           239: #define DSE_AT_CONSTRAINTVIOLATION      5
        !           240: #define DSE_AT_TYPEORVALUEEXISTS        6
        !           241:     AttributeType           DSE_at_type;
        !           242:     AttributeValue          DSE_at_value;
        !           243:     struct DSE_at_problem * dse_at_next;
        !           244: };
        !           245: #define DSE_AT_NOPROBLEM ((struct DSE_at_problem*)0)
        !           246: \end{verbatim}\end{quote}
        !           247: 
        !           248: The fields are used as follows:-
        !           249: \begin{describe}
        !           250: \item [\verb"DSE\_at\_what":] Indicates which error has occurred.
        !           251: \item [\verb"DSE\_at\_type":] The attribute type causing the error.
        !           252: \item [\verb"DSE\_at\_value":] The associated value (if any).
        !           253: \item [\verb"dse\_at\_next":] There may be more than one such error --- if
        !           254: so they form a linked list.
        !           255: \end{describe}
        !           256: \end{describe}
        !           257: 
        !           258: 
        !           259: 
        !           260: \subsection{Name Error}
        !           261: \begin{quote}\small\begin{verbatim}
        !           262: struct DSE_name {
        !           263:     int DSE_na_problem;
        !           264: #define DSE_NA_NOSUCHOBJECT             1
        !           265: #define DSE_NA_ALIASPROBLEM             2
        !           266: #define DSE_NA_INVALIDATTRIBIBUTESYNTAX 3
        !           267: #define DSE_NA_ALIASDEREFERENCE         4
        !           268:     DN  DSE_na_matched;
        !           269: };
        !           270: \end{verbatim}\end{quote}
        !           271: 
        !           272: \verb"DSE_na_matched" is the part of the DN successfully matched.
        !           273: 
        !           274: \subsection{Referral Errors}
        !           275: 
        !           276: \begin{quote}\small\begin{verbatim}
        !           277: struct DSE_referral {
        !           278:     ContininuationRef DSE_ref_candidates;
        !           279:     DN                DSE_ref_prefix;
        !           280: };
        !           281: \end{verbatim}\end{quote}
        !           282: 
        !           283: The continuation reference supplies information on how the continue the
        !           284: query.
        !           285: The structure is described in Section~\ref{cont_ref}
        !           286: 
        !           287: The field \verb"DSE_ref_prefix" is for DSP only.
        !           288: 
        !           289: Quipu-6.0 will, due to enhanced security, issue more ``referrals'' than
        !           290: Quipu-5.0. You should now generally chase such referrals.
        !           291: 
        !           292: \subsection{Security Error}
        !           293: \label{error_sec}
        !           294: \begin{quote}\small\begin{verbatim}
        !           295: struct DSE_security {
        !           296:     int DSE_sc_problem;
        !           297: #define DSE_SC_AUTHENTICATION           1
        !           298: #define DSE_SC_INVALIDCREDENTIALS       2
        !           299: #define DSE_SC_ACCESSRIGHTS             3
        !           300: #define DSE_SC_INVALIDSIGNATURE         4
        !           301: #define DSE_SC_PROTECTIONREQUIRED       5
        !           302: #define DSE_SC_NOINFORMATION            6
        !           303: };
        !           304: \end{verbatim}\end{quote}
        !           305: 
        !           306: \subsection{Service Error}
        !           307: \label{error_ser}
        !           308: \begin{quote}\small\begin{verbatim}
        !           309: struct DSE_service {
        !           310:     int DSE_sv_problem;
        !           311: #define DSE_SV_BUSY                         1
        !           312: #define DSE_SV_UNAVAILABLE                  2
        !           313: #define DSE_SV_UNWILLINGTOPERFORM           3
        !           314: #define DSE_SV_CHAININGREQUIRED             4
        !           315: #define DSE_SV_UNABLETOPROCEED              5
        !           316: #define DSE_SV_INVALIDREFERENCE             6
        !           317: #define DSE_SV_TIMELIMITEXCEEDED            7
        !           318: #define DSE_SV_ADMINLIMITEXCEEDED           8
        !           319: #define DSE_SV_LOOPDETECT                   9
        !           320: #define DSE_SV_UNAVAILABLECRITICALEXTENSION 10
        !           321: #define DSE_SV_OUTOFSCOPE                   11
        !           322: #define DSE_SV_DITERROR                     12
        !           323: };
        !           324: \end{verbatim}\end{quote}
        !           325: 
        !           326: \subsection{Update Error}
        !           327: \begin{quote}\small\begin{verbatim}
        !           328: struct DSE_update {
        !           329:     int DSE_up_problem;
        !           330: #define DSE_UP_NAMINGVIOLATION          1
        !           331: #define DSE_UP_OBJECTCLASSVIOLATION     2
        !           332: #define DSE_UP_NOTONNONLEAF             3
        !           333: #define DSE_UP_NOTONRDN                 4
        !           334: #define DSE_UP_ALREADYEXISTS            5
        !           335: #define DSE_UP_AFFECTSMULTIPLEDSAS      6
        !           336: #define DSE_UP_NOOBJECTCLASSMODS        7
        !           337: };
        !           338: \end{verbatim}\end{quote}
        !           339: 
        !           340: \subsection{Abandon Failure}
        !           341: If an abandon operation fails then the following is used:-
        !           342: \begin{quote}\small\begin{verbatim}
        !           343: struct DSE_abandon_fail {
        !           344:     int DSE_ab_problem;
        !           345: #define DSE_AB_NOSUCHOPERATION  1
        !           346: #define DSE_AB_TOOLATE          2
        !           347: #define DSE_AB_CANNOTABANDON    3
        !           348:     int DSE_ab_invokeid;
        !           349: };
        !           350: \end{verbatim}\end{quote}
        !           351: 
        !           352: \subsection {Error Handling Procedures}
        !           353: 
        !           354: The \man libdsap(3n) library has three routines for handling errors.
        !           355: 
        !           356: \begin{quote}\index{ds\_error}\small\begin{verbatim}
        !           357: ds_error (ps,error)
        !           358: PS ps;
        !           359: struct DSError * error;
        !           360: \end{verbatim}\end{quote}
        !           361: 
        !           362: This routine will take the error, and pretty-print the contents to the
        !           363: PStream \verb"ps".
        !           364: 
        !           365: \begin{quote}\index{log\_ds\_error}\small\begin{verbatim}
        !           366: log_ds_error (error)
        !           367: struct DSError * error;
        !           368: \end{verbatim}\end{quote}
        !           369: 
        !           370: This routine will take the error, print a simple message
        !           371: in ``dsap\_log'' at ``LLOG\_EXCEPTIONS'' logging level, and a more detailed
        !           372: report at ``LLOG\_TRACE'' logging level.
        !           373: 
        !           374: \begin{quote}\small\begin{verbatim}
        !           375: ds_error_free (err)
        !           376: struct DSError * err;
        !           377: \end{verbatim}\end{quote}
        !           378: 
        !           379: This frees the embedded structures within the error structure, BUT NOT
        !           380: \verb"DSError" itself.
        !           381: 
        !           382: \section {Binding and Unbinding}
        !           383: \label{dap:bind}
        !           384: 
        !           385: Before operations may be invoked, the DUA must BIND to the DSA.
        !           386: 
        !           387: The \verb"bind" procedure
        !           388: \begin{quote}\index{secure\_ds\_bind}\small\begin{verbatim}
        !           389: secure_ds_bind (arg, error, result)
        !           390:     struct ds_bind_arg          * arg;
        !           391:     struct ds_bind_arg          * result;
        !           392:     struct ds_bind_error        * error;
        !           393: \end{verbatim}\end{quote}
        !           394: is used for this purpose.
        !           395: 
        !           396: You will need to include \file{quipu/bind.h} to use this procedure.
        !           397: 
        !           398: The \verb"ds_bind_arg" structure is defined as follows.
        !           399: \begin{quote}\small\begin{verbatim}
        !           400: struct ds_bind_arg {
        !           401:     int  dba_version; 
        !           402: #define DBA_VERSION_V1988 0x001
        !           403:     int dba_auth_type;
        !           404: #define DBA_AUTH_EXTERNAL -1
        !           405: #define DBA_AUTH_NONE      0
        !           406: #define DBA_AUTH_SIMPLE    1
        !           407: #define DBA_AUTH_PROTECTED 2
        !           408: #define DBA_AUTH_STRONG    3
        !           409:     char *dba_time1;
        !           410:     char *dba_time2;
        !           411:     struct random_number dba_r1;
        !           412:     struct random_number dba_r2;
        !           413:     DN dba_dn;
        !           414:     int dba_passwd_len;
        !           415: #define DBA_MAX_PASSWD_LEN 512
        !           416:     char dba_passwd[DBA_MAX_PASSWD_LEN];
        !           417:     struct signature *dba_sig;
        !           418:     struct certificate_list *dba_cpath;
        !           419: };
        !           420: \end{verbatim}\end{quote}
        !           421: 
        !           422: \begin{describe}
        !           423: \item [\verb"dba\_version":] should always be set to
        !           424: \verb"DBA_VERSION_V1988".
        !           425: \item [\verb"dsa\_auth\_type":] is used to select the type of authentication
        !           426: required.
        !           427: \item [\verb"dba\_dn":] is the name of the entity you wish to bind as, this
        !           428: can be \verb"NULLDN" if you only require access to ``publically readable''
        !           429: information.
        !           430: \item [\verb"dba\_passwd":] The password required to bind as the entity.
        !           431: This will be checked against the ``userPassword'' attribute in the entity.
        !           432: \item [\verb"dba\_passwd\_len"] The length of the string in
        !           433: \verb"dsa_passwd".
        !           434: \item [\verb"dba\_sig"] The strong authentication signature (must be
        !           435: provided if strong authentication is used).
        !           436: \item [\verb"dba\_cpath"] The strong authentication certification path
        !           437: (optional).
        !           438: \item [\verb"dba\_time1"] Used for protected and strong authentication.
        !           439: \item [\verb"dba\_time2"] Optionally used for protected simple authentication.
        !           440: \item [\verb"dba\_r1"] Random number used for protected and strong
        !           441: authentication.
        !           442: \item [\verb"dba\_r2"] Optionally used for protected simple
        !           443: authentication.
        !           444: \end{describe}
        !           445: 
        !           446: The \verb"bind" operation will try to connect to the DSA, whose address is
        !           447: defined in the external \verb"char *", ``\verb"dsa_address"'', the syntax of
        !           448: the string is that of an ISODE PSAP address.
        !           449: 
        !           450: If \verb"secure_ds_bind()" returns \verb"DS_OK", then you have a successful connection,
        !           451: otherwise a \verb"ds_bind_error" structure will inform you 
        !           452: of the error condition.
        !           453: 
        !           454: \begin{quote}\small\begin{verbatim}
        !           455: struct ds_bind_error {
        !           456:     int  dbe_version;
        !           457:     char dbe_type;
        !           458: #define DBE_TYPE_SERVICE 0
        !           459: #define DBE_TYPE_SECURITY 1
        !           460:     int  dbe_value;        
        !           461: };
        !           462: \end{verbatim}\end{quote}
        !           463: 
        !           464: The filed \verb"dbe_value" takes a value as defined for a \verb"DSE_security"
        !           465: or \verb"DSE_service" error shown in Sections \ref{error_sec} and
        !           466: \ref{error_ser}.
        !           467: 
        !           468: \subsection{No Authentication}
        !           469: 
        !           470: To bind without using any authentication, 
        !           471: \verb+dsa_auth_type+ should be set to \verb+DBA_AUTH_NONE+.
        !           472: The fields \verb+dba_version+ and \verb+dba_dn+ must be filled in.
        !           473: 
        !           474: \subsection{Simple Authentication}
        !           475: 
        !           476: To bind using simple authentication, 
        !           477: the \verb+dsa_auth_type+ field should be set to the value
        !           478: \verb+DBA_AUTH_SIMPLE+.
        !           479: The fields \verb+dba_version+, \verb+dba_dn+,
        !           480: \verb+dba_passwd+ and \verb+dba_passwd_len+ must be filled in.
        !           481: 
        !           482: For backwards compatibility the routine
        !           483: \begin{quote}\index{ds\_bind}\small\begin{verbatim}
        !           484: ds_bind (arg, error, result)
        !           485:     struct ds_bind_arg          * arg;
        !           486:     struct ds_bind_arg          * result;
        !           487:     struct ds_bind_error        * error;
        !           488: \end{verbatim}\end{quote}
        !           489: is still supplied, and gives you a unprotected simple bind request.
        !           490: 
        !           491: 
        !           492: \subsection{Protected Simple Authentication}
        !           493: 
        !           494: To bind using protected simple authentication, 
        !           495: the \verb+dsa_auth_type+ field should be set to to the value
        !           496: \verb+DBA_AUTH_PROTECTED+.
        !           497: The fields \verb+dba_version+, \verb+dba_dn+, \verb+dba_time1+, \verb+dba_r1+,
        !           498: \verb+dba_passwd+ and \verb+dba_passwd_len+ must be filled in. The fields
        !           499: \verb+dba_time2+ and \verb+dba_r2+ must be either filled in or set to 
        !           500: \verb+NULL+.
        !           501: 
        !           502: \subsection{Strong Authentication}
        !           503: 
        !           504: To bind using strong authentication, 
        !           505: the \verb+dsa_auth_type+ field should be set to the value
        !           506: \verb+DBA_AUTH_STRONG+.
        !           507: The fields \verb+dba_version+, \verb+dba_dn+, \verb+dba_time1+, \verb+dba_r1+,
        !           508: and \verb+dba_sig+ must be filled in. The field
        !           509: \verb+dba_cpath+ must be either filled in or set to \verb+NULL+.
        !           510: 
        !           511: \section{Unbind}
        !           512: 
        !           513: The unbind operation has no parameters.
        !           514: \begin{quote}\index{ds\_unbind}\small\begin{verbatim}
        !           515: ds_unbind ()
        !           516: \end{verbatim}\end{quote}
        !           517: and is used to disconnect from the directory.
        !           518: 
        !           519: \section {Read}
        !           520: 
        !           521: The read operation is used to access information from a particular
        !           522: entity in the DSA.
        !           523: 
        !           524: \begin{quote}\index{ds\_read}\small\begin{verbatim}
        !           525: ds_read (arg, error, result)
        !           526:     struct ds_read_arg          * arg;    
        !           527:     struct ds_read_result       * result;
        !           528:     struct DSError              * error;
        !           529: \end{verbatim}\end{quote}
        !           530: 
        !           531: You will need to include \file{quipu/read.h} to use this procedure.
        !           532: 
        !           533: The argument \verb"ds_read_arg" is used to formulate the DAP request:-
        !           534: 
        !           535: \begin{quote}\small\begin{verbatim}
        !           536: struct ds_read_arg {
        !           537:     CommonArgs         rda_common;
        !           538:     DN                 rda_object;
        !           539:     EntryInfoSelection rda_eis;
        !           540: };
        !           541: \end{verbatim}\end{quote}
        !           542: 
        !           543: The parameters are used as follows:-
        !           544: \begin{describe}
        !           545: \item [\verb"rda\_common":] The common arguments as described in
        !           546: Section~\ref{common_args}
        !           547: \item [\verb"rda\_object":] The DN of the object you want to read
        !           548: \item [\verb"rda\_eis":] The ``Entry Information Selection'', which defines
        !           549: which attributes you want to be returned, this is defined in
        !           550: Section~\ref{eis}
        !           551: \end{describe}
        !           552: 
        !           553: The results returned on a \verb"DS_OK" return form the structure shown below:-
        !           554: 
        !           555: \begin{quote}\small\begin{verbatim}
        !           556: struct ds_read_result {
        !           557:     CommonResults rdr_common;
        !           558:     EntryInfo     rdr_entry;
        !           559: };
        !           560: \end{verbatim}\end{quote}
        !           561: 
        !           562: \begin{describe}
        !           563: \item [\verb"rdr\_common":] The common results as described in
        !           564: Section~\ref{common_results}
        !           565: \item [\verb"rdr\_entry":] The ``Entry Information'', which contains the
        !           566: attributes you requested. The structure is defined in Section~\ref{einfo}.
        !           567: \end{describe}
        !           568: 
        !           569: \subsection {Entry Information Selection}
        !           570: \label{eis}
        !           571: 
        !           572: Operations that return an Entry Information structure, will have an ``Entry
        !           573: Information Selection'' in their arguments to specify exactly what the DSA
        !           574: should return.   The structure is represented thus:-
        !           575: 
        !           576: \begin{quote}\index{EntryInfoSelection}\small\begin{verbatim}
        !           577: typedef struct {
        !           578:     char                eis_allattributes;
        !           579:     Attr_Sequence       eis_select;
        !           580:     char                eis_infotypes;
        !           581: #define EIS_ATTRIBUTETYPESONLY  0
        !           582: #define EIS_ATTRIBUTESANDVALUES 1
        !           583: } EntryInfoSelection;
        !           584: \end{verbatim}\end{quote}
        !           585: 
        !           586: The parameters are used as follows:-
        !           587: \begin{describe}
        !           588: \item [\verb"eis\_allattributes":] If \verb"TRUE" the all attributes are
        !           589: required.
        !           590: \item [\verb"eis\_select":] If \verb"eis_allattributes" is \verb"FALSE" then
        !           591: this field is used to specify the attributes you want.
        !           592: ONLY the attribute types of this structure need to be set, any attribute
        !           593: values will be ignored.
        !           594: \item [\verb"eis\_infotypes":] If \verb"EIS_ATTRIBUTETYPESONLY" is set, then
        !           595: only attribute types will be returned, otherwise the
        !           596: values will also be returned.
        !           597: \end{describe}
        !           598: 
        !           599: \subsection {Entry Information}
        !           600: \label{einfo}
        !           601: 
        !           602: The structure ``Entry Information'' is used by some of the operations to
        !           603: return data to the DUA.
        !           604: 
        !           605: \begin{quote}\index{EntryInfo}\small\begin{verbatim}
        !           606: typedef struct entrystruct { 
        !           607:     DN                  ent_dn;
        !           608:     Attr_Sequence       ent_attr;
        !           609:     int                 ent_iscopy;
        !           610: #define INFO_MASTER 0x000
        !           611: #define INFO_COPY   0x001
        !           612: #define INFO_CACHE  0x002
        !           613:     time_t              ent_age;
        !           614:     struct entrystruct  *ent_next;
        !           615: } entrystruct, EntryInfo;
        !           616: \end{verbatim}\end{quote}
        !           617: 
        !           618: The parameters are used as follows:-
        !           619: \begin{describe}
        !           620: \item [\verb"ent\_dn":] The DN of the entry.
        !           621: \item [\verb"ent\_attr":] The requested attributes of the requested entry.
        !           622: \item [\verb"ent\_iscopy":] This is either \verb"INFO_MASTER" or
        !           623: \verb"INFO_COPY" indicating whether master data or
        !           624: copied data was used to generate the results.
        !           625: \verb"INFO_CACHE" is not applicable to a DUA.
        !           626: \item [\verb"ent\_age":] This field is for DSA use only.
        !           627: \item [\verb"ent\_next":] There may be many results, this is used to link them.
        !           628: \end{describe}
        !           629: 
        !           630: NOTE, the fields \verb"ent_dn" and \verb"ent_attr" will only be partially
        !           631: decoded when this structure is returned.
        !           632: You should call the routines \verb"dn_decode()" and \verb"as_decode()"
        !           633: described in Section~\ref{quipu_conv} if you want to use the structures
        !           634: fully decoded.
        !           635: 
        !           636: \section {Compare}
        !           637: 
        !           638: The compare operation is used to compare an asserted attribute, with an
        !           639: attribute in the directory.
        !           640: 
        !           641: \begin{quote}\index{ds\_compare}\small\begin{verbatim}
        !           642: ds_compare (arg, error, result)
        !           643:     struct ds_compare_arg       * arg;    
        !           644:     struct ds_compare_result    * result;
        !           645:     struct DSError              * error;
        !           646: \end{verbatim}\end{quote}
        !           647: 
        !           648: You will need to include \file{quipu/compare.h} to use this procedure.
        !           649: 
        !           650: The argument is as follows:-
        !           651: \begin{quote}\small\begin{verbatim}
        !           652: struct ds_compare_arg {
        !           653:     CommonArgs cma_common;
        !           654:     DN         cma_object;
        !           655:     AVA        cma_purported;
        !           656: };
        !           657: \end{verbatim}\end{quote}
        !           658: 
        !           659: \begin{describe}
        !           660: \item [\verb"cma\_common":] The common arguments as described in
        !           661: Section~\ref{common_args}.
        !           662: \item [\verb"cma\_object":] The DN of the object you want to attribute
        !           663: against.
        !           664: \item [\verb"cma\_purported":] The attribute you want to compare.  This
        !           665: structure is defined in Section~\ref{ava}.
        !           666: \end{describe}
        !           667: 
        !           668: If successful, the result structure is as follows:-
        !           669: \begin{quote}\small\begin{verbatim}
        !           670: struct ds_compare_result {
        !           671:     CommonResults cmr_common;
        !           672:     DN            cmr_object;
        !           673:     char          cmr_matched; 
        !           674:     char          cmr_iscopy; 
        !           675: };
        !           676: \end{verbatim}\end{quote}
        !           677: 
        !           678: \begin{describe}
        !           679: \item [\verb"cmr\_common":] The common results as described in
        !           680: Section~\ref{common_results}.
        !           681: \item [\verb"cmr\_object":] The DN of the entry the attribute was compared
        !           682: against.  This may not be the same as the DN supplied in the argument (e.g.,
        !           683: if an alias was dereferenced).
        !           684: \item [\verb"cmr\_matched":] If \verb"TRUE" then the attributes were the
        !           685: same, otherwise they were different.
        !           686: \item [\verb"cmr\_iscopy":] If \verb"TRUE" then the compare took place
        !           687: against a copy of the attribute.
        !           688: \end{describe}
        !           689: 
        !           690: 
        !           691: \subsection {Attribute Value Assertion}
        !           692: \label{ava}
        !           693: 
        !           694: An ``Attribute Value Assertion'' is used by some of the operations to
        !           695: specify an attribute type/value pair, the structure used in this case is
        !           696: shown below.
        !           697: 
        !           698: \begin{quote}\index{AVA}\small\begin{verbatim}
        !           699: typedef struct {
        !           700:     AttributeType  ava_type;
        !           701:     AttributeValue ava_value;
        !           702: }AVA;
        !           703: \end{verbatim}\end{quote}
        !           704: 
        !           705: \section {List}
        !           706: 
        !           707: The list operation is show below.
        !           708: This returns a list of subordinates of the specified entry.
        !           709: 
        !           710: \begin{quote}\index{ds\_list}\small\begin{verbatim}
        !           711: ds_list (arg, error, result)
        !           712:     struct ds_list_arg          * arg;    
        !           713:     struct ds_list_result       * result;
        !           714:     struct DSError              * error;
        !           715: \end{verbatim}\end{quote}
        !           716: 
        !           717: You will need to include \file{quipu/list.h} to use this procedure.
        !           718: 
        !           719: \begin{quote}\small\begin{verbatim}
        !           720: struct ds_list_arg {
        !           721:     CommonArgs lsa_common;
        !           722:     DN         lsa_object;
        !           723: };
        !           724: \end{verbatim}\end{quote}
        !           725: 
        !           726: \begin{describe}
        !           727: \item [\verb"lsa\_common":] The common arguments as described in
        !           728: Section~\ref{common_args}.
        !           729: \item [\verb"lsa\_object":] The DN of the object you want to list the
        !           730: children of.
        !           731: \end{describe}
        !           732: 
        !           733: The results of a successful list form the following structure:-
        !           734: 
        !           735: \begin{quote}\small\begin{verbatim}
        !           736: struct ds_list_result {
        !           737:     CommonResults        lsr_common;
        !           738:     DN                   lsr_object;
        !           739:     time_t               lsr_age;
        !           740:     struct subordinate * lsr_subordinates;
        !           741:     int                  lsr_limitproblem;
        !           742: #define LSR_NOLIMITPROBLEM      0
        !           743: #define LSR_TIMELIMITEXCEEDED   1
        !           744: #define LSR_SIZELIMITEXCEEDED   2
        !           745: #define LSR_ADMINSIZEEXCEEDED   3
        !           746:     ContinuationRef      lsr_cr;
        !           747: };
        !           748: \end{verbatim}\end{quote}
        !           749: 
        !           750: \begin{describe}
        !           751: \item [\verb"lsr\_common":] The common results as described in
        !           752: Section~\ref{common_results}.
        !           753: \item [\verb"lsr\_object":]The DN of the entry whose children were listed.
        !           754: This may not be the same as the DN supplied in the argument (e.g.,
        !           755: if an alias was dereferenced). 
        !           756: \item [\verb"lsr\_age";] Not currently used.
        !           757: \item [\verb"lsr\_subordinates":] This structure contains the RDNs
        !           758: that were found below the base object.  The structure is as follows:-
        !           759: \begin{quote}\small\begin{verbatim}
        !           760: struct subordinate {
        !           761:     RDN                  sub_rdn;
        !           762:     char                 sub_aliasentry; 
        !           763:     char                 sub_copy;
        !           764:     struct subordinate * sub_next;
        !           765: };
        !           766: \end{verbatim}\end{quote}
        !           767: 
        !           768: \begin{describe}
        !           769: \item [\verb"sub\_rdn":] The RDN of this child.
        !           770: \item [\verb"sub\_aliasentry":] If \verb"TRUE" then it is an alias entry.
        !           771: \item [\verb"sub\_copy":] If \verb"TRUE" then the list took place
        !           772: against a copy of the object.
        !           773: \item [\verb"sub\_next":] A pointer to the next element in the list.
        !           774: \end{describe}
        !           775: 
        !           776: \item [\verb"lsr\_limitproblem":] If NON zero, then the specified limit
        !           777: problem occurred during the operation.
        !           778: \item [\verb"lsr\_cr":] A list of continuation references.
        !           779: Continuation References are described in 
        !           780: Section~\ref{cont_ref}.
        !           781: \end{describe}
        !           782: 
        !           783: \section {Search}
        !           784: \label{proc_search}
        !           785: The search operation performs a key Directory functionality.  This is done on
        !           786: the basis of 
        !           787: filters as described in Section~\ref{filters} below
        !           788: The operation is defined as:-
        !           789: \begin{quote}\index{ds\_search}\small\begin{verbatim}
        !           790: ds_search (arg, error, result)
        !           791:     struct ds_search_arg        * arg;    
        !           792:     struct ds_search_result     * result;
        !           793:     struct DSError              * error;
        !           794: \end{verbatim}\end{quote}
        !           795: 
        !           796: You will need to include \file{quipu/ds\_search.h} to use this procedure.
        !           797: 
        !           798: \begin{quote}\small\begin{verbatim}
        !           799: struct ds_search_arg {
        !           800:     CommonArgs         sra_common;
        !           801:     DN                 sra_baseobject;
        !           802:     int                sra_subset;
        !           803: #define SRA_BASEOBJECT          0
        !           804: #define SRA_ONELEVEL            1
        !           805: #define SRA_WHOLESUBTREE        2
        !           806:     Filter             sra_filter;
        !           807:     char              sra_searchalias;
        !           808:     EntryInfoSelection sra_eis;
        !           809: };
        !           810: \end{verbatim}\end{quote}
        !           811: 
        !           812: \begin{describe}
        !           813: \item [\verb"sra\_common":] The common arguments as described in
        !           814: Section~\ref{common_args}.
        !           815: \item [\verb"sra\_baseobject":] The DN of the object you want to start the
        !           816: search from.
        !           817: \item [\verb"sra\_subset":] This specifies which part of the DIT to search.
        !           818: \item [\verb"sra\_filter":] The filter to apply to the searched entries to
        !           819: see if the entry is required.  Filters are discussed in Section~\ref{filters}
        !           820: \item [\verb"sra\_searchalias":] If \verb+TRUE+ aliases encountered below
        !           821: the search baseobject are dereferenced, and the dereferenced object searched.  
        !           822: Note how this is different to the service control
        !           823: ``\verb+dontderferencealiases+ which is used to control dereferencing of
        !           824: entities above the base object.
        !           825: \item [\verb"sra\_eis":] The ``Entry Information Selection'', which defines
        !           826: which attributes you want to be returned (if the filter is matched), 
        !           827: this is defined in Section \ref{eis}.
        !           828: \end{describe}
        !           829: 
        !           830: The results form the following structure:-
        !           831: 
        !           832: \begin{quote}\small\begin{verbatim}
        !           833: struct ds_search_result {
        !           834:     char  srr_correlated;
        !           835:     union {
        !           836:         struct ds_search_unit   * srr_unit;
        !           837:         struct ds_search_result * srr_parts;
        !           838:     }     srr_un;
        !           839:     struct ds_search_result * srr_next;
        !           840: };
        !           841: \end{verbatim}\end{quote}
        !           842: 
        !           843: \begin{describe}
        !           844: \item [\verb"srr\_correlated":] If \verb"TRUE" the the results are 
        !           845: said to be correlated, that is, there will only be one element
        !           846: in the list of search results.
        !           847: A DSA may return uncorrelated result, in which case the routine
        !           848: \begin{quote}\index{correlate\_search\_results}\small\begin{verbatim}
        !           849: correlate_search_results(sr_res)
        !           850: struct ds_search_result * sr_res;
        !           851: \end{verbatim}\end{quote}
        !           852: can be called, which will correlate the results.
        !           853: 
        !           854: NOTE QUIPU DSAs will always return correlated results.
        !           855: 
        !           856: \item [\verb"srr\_un":] If the results are uncorrelated then the 
        !           857: union will contain a nested \verb"ds_search_result" structure, which 
        !           858: contains a list of the uncorrelated results.
        !           859: 
        !           860: If the results are correlated, then this union will
        !           861: contain a pointer to the correlated results.  These form the structure
        !           862: \begin{quote}\small\begin{verbatim}
        !           863: struct ds_search_unit {
        !           864:     CommonResults   srr_common;
        !           865:     DN              srr_object;
        !           866:     EntryInfo     * srr_entries;
        !           867:     int             srr_limitproblem;
        !           868:     ContinuationRef srr_cr;
        !           869: };
        !           870: #define CSR_common       srr_un.srr_unit->srr_common
        !           871: #define CSR_object       srr_un.srr_unit->srr_object
        !           872: #define CSR_entries      srr_un.srr_unit->srr_entries
        !           873: #define CSR_limitproblem srr_un.srr_unit->\
        !           874:                          srr_limitproblem
        !           875: #define CSR_cr           srr_un.srr_unit->srr_cr
        !           876: \end{verbatim}\end{quote}
        !           877: NOTE the \verb"#define"s to access the elements of this structure.
        !           878: The fields are used as follows:
        !           879: \begin{describe}
        !           880: \item [\verb"srr\_common":] The common results as described in
        !           881: \ref{common_results}.
        !           882: \item [\verb"srr\_object":] The DN of the entry used as the base object of
        !           883: the search.  This may not be the same as the DN supplied in the argument (e.g.,
        !           884: if an alias was dereferenced).
        !           885: \item [\verb"srr\_entries":] The ``Entry Information'', which contains the
        !           886: attributes you requested. The structure is defined in Section \ref{einfo}.
        !           887: \item [\verb"srr\_limitproblem":] If NON zero, then the specified limit
        !           888: problem occurred during the operation.
        !           889: \item [\verb"srr\_cr":] A list of continuation references.
        !           890: Continuation References are described in 
        !           891: Section~\ref{cont_ref}.
        !           892: \end{describe}
        !           893: 
        !           894: \item [\verb"srr\_next":] This is a pointer to the next 
        !           895: result in a list of uncorrelated results.
        !           896: \end{describe}
        !           897: 
        !           898: \subsection {Filters}
        !           899: \label{filters}
        !           900: 
        !           901: A filter in its simplest sense is a single \verb"filter_item".  This is
        !           902: used to perform one of six basic tests on one attribute of an entry.
        !           903: If the ``match'' is good, then the entry is returned as part of
        !           904: the search result structure.
        !           905: The six basic types of \verb"filter_item"
        !           906: are represented by the structure below:-
        !           907: 
        !           908: \begin{quote}\index{filter\_item}\small\begin{verbatim}
        !           909: struct filter_item {
        !           910:     int         fi_type;
        !           911: #define FILTERITEM_EQUALITY       0
        !           912: #define FILTERITEM_SUBSTRINGS     1
        !           913: #define FILTERITEM_GREATEROREQUAL 2
        !           914: #define FILTERITEM_LESSOREQUAL    3
        !           915: #define FILTERITEM_PRESENT        4
        !           916: #define FILTERITEM_APPROX         5
        !           917:     union {
        !           918:         AttributeType     fi_un_type;
        !           919:         AVA               fi_un_ava;
        !           920:         Filter_Substrings fi_un_substrings;
        !           921:     }           fi_un;
        !           922:     IFP         fi_ifp;
        !           923: };
        !           924: \end{verbatim}\end{quote}
        !           925: 
        !           926: \begin{describe}
        !           927: \item [\verb"fi\_type":] Defines the type of \verb"filter_item" being represented.
        !           928: \item [\verb"fi\_un.fi\_un\_type":] \verb"FILTERITEM_PRESENT"
        !           929: matches, just supply an AttributeType, an entry matches if this attribute
        !           930: exists within the entry.
        !           931: 
        !           932: \item [\verb"fi\_un.fi\_un\_ava":] \verb"FILTERITEM_EQUALITY",
        !           933: \verb"FILTERITEM_GREATEROREQUAL", \verb"FILTERITEM_LESSOREQUAL", and
        !           934: \verb"FILTERITEM_APPROX" searches all
        !           935: take an AVA (Attribute Value Assertion) structure, and return the entries
        !           936: for which the attribute in the entry matches the asserted value.
        !           937: The AVA structure is defined in Section~\ref{ava}.
        !           938: 
        !           939: \item [\verb"fi\_un.un\_substrings":] 
        !           940: \verb"FILTERITEM_SUBSTRING" matches, use the substring structure defined below, to specify
        !           941: which substrings to look for in the appropriate attribute.
        !           942: 
        !           943: \begin{quote}\small\begin{verbatim}
        !           944: typedef struct {
        !           945:             AttributeType fi_sub_type;
        !           946:             AV_Sequence   fi_sub_initial;
        !           947:             AV_Sequence   fi_sub_any;
        !           948:             AV_Sequence   fi_sub_final;
        !           949:         } Filter_Substrings;
        !           950: \end{verbatim}\end{quote}
        !           951: 
        !           952: The \verb"AV_Sequence" structure is used to represent a string, and should be
        !           953: treated as essentially a linked list of \verb"char *" parameters.
        !           954: \begin{describe}
        !           955: \item [\verb"fi\_sub\_type":] The attribute that you want to perform a
        !           956: substring search on.
        !           957: \item [\verb"fi\_sub\_initial":] This contains a single attribute value,
        !           958: that must appear at the start of the string.
        !           959: \item [\verb"fi\_sub\_any":] A set of values, which must appear in order in
        !           960: the middle of the string.
        !           961: \item [\verb"fi\_sun\_final":] This contains a single attribute value,
        !           962: that must appear at the end of the string.
        !           963: \end{describe}
        !           964: \item [\verb"fi\_ifp":] For DSA use only.
        !           965: \end{describe}
        !           966: 
        !           967: The single filter items can now be linked into a \verb"filter" structure
        !           968: to build more complex search definitions:-
        !           969: 
        !           970: \begin{quote}\index{filter}\small\begin{verbatim}
        !           971: typedef struct filter {
        !           972:     char          flt_type;
        !           973: #define FILTER_ITEM 0
        !           974: #define FILTER_AND  1
        !           975: #define FILTER_OR   2
        !           976: #define FILTER_NOT  3
        !           977:    struct filter * flt_next;
        !           978:    union {
        !           979:         struct filter_item   flt_un_item;
        !           980:         struct filter      * flt_un_filter;
        !           981:    }               flt_un;
        !           982: }filter, *Filter;
        !           983: \end{verbatim}\end{quote}
        !           984: 
        !           985: \begin{describe}
        !           986: \item [\verb"flt\_type":] This defines whether the filter is a single item,
        !           987: or a more complex filter made up of one or more components.
        !           988: \item [\verb"flt\_un.flt\_un\_item":] If the filter represents a
        !           989: \verb"filter_item", then the item is placed here.
        !           990: \item [\verb"flt\_un.flt\_un\_filter":] \verb"AND", \verb"OR" and \verb"NOT"
        !           991: filters apply to a linked list of ``children'' filters.  This element is a
        !           992: pointer to the head of that list.
        !           993: \item [\verb"flt\_next":] If the parent filter is an \verb"AND", \verb"OR".
        !           994: or \verb"NOT"
        !           995: filter, then the component filters are linked using this field. 
        !           996: NOTE that \verb"NOT" filters should contain a list of one child only.
        !           997: \end{describe}
        !           998: 
        !           999: As an example, lets us consider a filter to represent a person whose name
        !          1000: is either ``Robbins'' OR ( ``Steve'' AND ``Kille'' ).  The structure would
        !          1001: look something like:-
        !          1002: \begin{small}
        !          1003: \begin{verbatim}
        !          1004: flt_type = FILTER_OR
        !          1005:         - The filter is an OR filter
        !          1006: flt_un_filter.flt_type = FILTER_ITEM
        !          1007:         - First component or the OR is an item
        !          1008: flt_un_filter.flt_un_item = filter_item (Robbins)
        !          1009:         - The item should match "robbins"
        !          1010: flt_un_filter.flt_next->flt_type = FILTER_AND
        !          1011:         - Second component or the OR is an AND filter
        !          1012: flt_un_filter.flt_next->flt_un_filter.flt_type = FILTER_ITEM
        !          1013:         - First component or the AND is an item
        !          1014: flt_un_filter.flt_next->flt_un_filter.flt_un_item = 
        !          1015:                                         filter_item (Steve)
        !          1016:         - The item should match "Steve"
        !          1017: flt_un_filter.flt_next->flt_un_filter.flt_next->flt_type = 
        !          1018:                                         FILTER_ITEM
        !          1019:         - Second component or the AND is an item
        !          1020: flt_un_filter.flt_next->flt_un_filter.flt_next->flt_un_item = 
        !          1021:                                         filter_item (Kille)
        !          1022:         - The item should match "Kille"
        !          1023: \end{verbatim}
        !          1024: \end{small}
        !          1025: \section {Modification Operations}\label{mod-op}
        !          1026: 
        !          1027: There are 4 operations available to modify the directory.
        !          1028: 
        !          1029: NOTE: with Quipu-6.0 DSA's modify operations are only allowed over DAP,
        !          1030: attempts to modify over DSP will return referral errors.
        !          1031: 
        !          1032: \subsection {Add}
        !          1033: 
        !          1034: To add an entry to the DIT use
        !          1035: \begin{quote}\index{ds\_addentry}\small\begin{verbatim}
        !          1036: ds_addentry (arg, error)
        !          1037:     struct ds_addentry_arg      * arg;    
        !          1038:     struct DSError              * error;
        !          1039: \end{verbatim}\end{quote}
        !          1040: 
        !          1041: You will need to include \file{quipu/add.h} to use this procedure.
        !          1042: 
        !          1043: The argument you must supply is made up as follows:-
        !          1044: 
        !          1045: \begin{quote}\small\begin{verbatim}
        !          1046: struct ds_addentry_arg {
        !          1047:     CommonArgs    ada_common;
        !          1048:     DN            ada_object;
        !          1049:     Attr_Sequence ada_entry;
        !          1050: };
        !          1051: \end{verbatim}\end{quote}
        !          1052: 
        !          1053: 
        !          1054: \begin{describe}
        !          1055: \item [\verb"ada\_common":] The common arguments as described in
        !          1056: \ref{common_args}.
        !          1057: \item [\verb"ada\_object":] The DN of the object you want to add.
        !          1058: \item [\verb"ada\_entry":] The attributes you want to add for this entry.
        !          1059: This must contain the RDN of the entry, and an ``objectclass'' attribute.
        !          1060: Then, the other attribute MUST conform to the set of ``optional'' and
        !          1061: ``mandatory'' attribute for that object class.
        !          1062: \end{describe}
        !          1063: 
        !          1064: 
        !          1065: \subsection {Remove}
        !          1066: 
        !          1067: This is used to remove an entry from the DIT.
        !          1068: Only leaf entries can be removed.
        !          1069: 
        !          1070: \begin{quote}\index{ds\_removeentry}\small\begin{verbatim}
        !          1071: ds_removeentry (arg, error)
        !          1072:     struct ds_removeentry_arg   * arg;    
        !          1073:     struct DSError              * error;
        !          1074: \end{verbatim}\end{quote}
        !          1075: 
        !          1076: You will need to include \file{quipu/remove.h} to use this procedure.
        !          1077: 
        !          1078: The argument you must supply is made up as follows:-
        !          1079: 
        !          1080: \begin{quote}\small\begin{verbatim}
        !          1081: struct ds_removeentry_arg {
        !          1082:     CommonArgs rma_common;
        !          1083:     DN         rma_object;
        !          1084: };
        !          1085: \end{verbatim}\end{quote}
        !          1086: 
        !          1087: \begin{describe}
        !          1088: \item [\verb"rma\_common":] The common arguments as described in
        !          1089: \ref{common_args}.
        !          1090: \item [\verb"rma\_object":] The DN of the object you want to remove.
        !          1091: \end{describe}
        !          1092: 
        !          1093: 
        !          1094: \subsection {Modify}
        !          1095: 
        !          1096: \verb"ModifyEntry" is used to modify the attributes of the specified entry.
        !          1097: There are strong restrictions on this operation as required by X.500.
        !          1098: Invalid operations result in errors, and as such none of the requested
        !          1099: modifications are made.
        !          1100: To modify an attribute you must first \verb"remove" it then \verb"add" a new
        !          1101: attribute.
        !          1102: You can not modify the RDN, you must use the \verb"ModifyRDN" operation
        !          1103: described in Section~\ref{modifyrdn} to do this.
        !          1104: 
        !          1105: \begin{quote}\index{ds\_modifyentry}\small\begin{verbatim}
        !          1106: ds_modifyentry (arg, error)
        !          1107:     struct ds_modifyentry_arg   * arg;    
        !          1108:     struct DSError              * error;
        !          1109: \end{verbatim}\end{quote}
        !          1110: 
        !          1111: You will need to include \file{quipu/modify.h} to use this procedure.
        !          1112: 
        !          1113: The argument you must supply is made up as follows:-
        !          1114: 
        !          1115: \begin{quote}\small\begin{verbatim}
        !          1116: struct ds_modifyentry_arg {
        !          1117:     CommonArgs        mea_common;
        !          1118:     DN                mea_object;
        !          1119:     struct entrymod * mea_changes;
        !          1120: };
        !          1121: \end{verbatim}\end{quote}
        !          1122: 
        !          1123: \begin{describe}
        !          1124: \item [\verb"mea\_common":] The common arguments as described in
        !          1125: \ref{common_args}.
        !          1126: \item [\verb"mea\_object":] The DN of the object you want to modify.
        !          1127: \item [\verb"mea\_changes":] A tree structure defining the changes you want to
        !          1128: make to the entry.
        !          1129: \begin{quote}\index{entrymod}\small\begin{verbatim}
        !          1130: struct entrymod {
        !          1131:     int               em_type;
        !          1132: #define EM_ADDATTRIBUTE         0
        !          1133: #define EM_REMOVEATTRIBUTE      1
        !          1134: #define EM_ADDVALUES            2
        !          1135: #define EM_REMOVEVALUES         3
        !          1136:     Attr_Sequence     em_what;
        !          1137:     struct entrymod * em_next;
        !          1138: };
        !          1139: \end{verbatim}\end{quote}
        !          1140: \begin{describe}
        !          1141: \item [\verb"em\_type":] The type of modification this is.
        !          1142: \item [\verb"em\_what":] The attribute you want to add or remove.  If the
        !          1143: operation type is remove, then this structure should only contain an
        !          1144: attribute type, and not a value.
        !          1145: \item [\verb"em\_next":] A modify operation is built up with a series of
        !          1146: small modifications.  Hence this structure is a linked list.
        !          1147: The operation is seen as one atomic operation.
        !          1148: \end{describe}
        !          1149: \end{describe}
        !          1150: 
        !          1151: 
        !          1152: \subsection {ModifyRDN}
        !          1153: \label{modifyrdn}
        !          1154: 
        !          1155: To modify the distinguished attribute values of an entry, you MUST use this operation ---
        !          1156: \verb"modifyEntry" can not be used.
        !          1157: 
        !          1158: \begin{quote}\index{ds\_modifyrdn}\small\begin{verbatim}
        !          1159: ds_modifyrdn (arg, error)
        !          1160:     struct ds_modifyrdn_arg     * arg;    
        !          1161:     struct DSError              * error;
        !          1162: \end{verbatim}\end{quote}
        !          1163: 
        !          1164: You will need to include \file{quipu/modifyrdn.h} to use this procedure.
        !          1165: 
        !          1166: The arguments are:-
        !          1167: 
        !          1168: \begin{quote}\small\begin{verbatim}
        !          1169: struct ds_modifyrdn_arg {
        !          1170:     CommonArgs mra_common;
        !          1171:     DN         mra_object;
        !          1172:     RDN        mra_newrdn;
        !          1173:     char       mra_deleterdn; 
        !          1174: };
        !          1175: \end{verbatim}\end{quote}
        !          1176: 
        !          1177: \begin{describe}
        !          1178: \item [\verb"mra\_common":] The common arguments as described in
        !          1179: \ref{common_args}.
        !          1180: \item [\verb"mra\_object":] The DN of the object you want to modify the name
        !          1181: of.
        !          1182: \item [\verb"mra\_newrdn":] The new RDN.
        !          1183: \item [\verb"mra\_deleterdn":] if \verb"TRUE" then the old RDN will be
        !          1184: deleted as an attribute, otherwise it will remain an a non-distinguished
        !          1185: attribute.
        !          1186: \end{describe}
        !          1187: 
        !          1188: \section {Abandon}
        !          1189: 
        !          1190: The abandon operation shown below is slightly
        !          1191: different to the other DUA operations.
        !          1192: It does not make much sense for a synchronous interface to
        !          1193: handle abandon directly.
        !          1194: In the next release, transparent use of abandon will be provided.
        !          1195: 
        !          1196: \begin{quote}\index{ds\_abandon}\small\begin{verbatim}
        !          1197: ds_abandon (arg, error)
        !          1198:     struct ds_abandon_arg       * arg;    
        !          1199:     struct DSError              * error;
        !          1200: \end{verbatim}\end{quote}
        !          1201: 
        !          1202: The argument structure contains a single parameter 
        !          1203: supplies the operation invocation id.
        !          1204: 
        !          1205: \begin{quote}\small\begin{verbatim}
        !          1206: struct ds_abandon_arg {
        !          1207:     int aba_invokeid;
        !          1208: };
        !          1209: \end{verbatim}\end{quote}
        !          1210: 
        !          1211: 
        !          1212: \section {Multiple Associations}
        !          1213: 
        !          1214: The procedural interface described so far, has been based on the assumption 
        !          1215: of a connection to a single DSA.
        !          1216: However, it is possible to make connection to multiple DSAs.
        !          1217: 
        !          1218: 
        !          1219: \subsection {Multiple Binds}
        !          1220: 
        !          1221: The bind and unbind routines needed to make 
        !          1222: multiple association are as follows:-
        !          1223: \begin{quote}\index{dap\_bind}\small\begin{verbatim}
        !          1224: dap_bind (ad, arg, error, result, addr)
        !          1225:     int                         * ad;
        !          1226:     struct ds_bind_arg          *arg;
        !          1227:     struct ds_bind_arg          *result;
        !          1228:     struct ds_bind_error        *error;
        !          1229:     struct PSAPaddr             *addr;
        !          1230: 
        !          1231: dap_unbind (ad)
        !          1232:     int                         ad;
        !          1233: \end{verbatim}\end{quote}
        !          1234: 
        !          1235: The \verb"arg", \verb"error" and \verb"result" arguments are as defined 
        !          1236: in Section~\ref{dap:bind} for the routine \verb"secure_ds_bind".
        !          1237: 
        !          1238: The argument \verb"ad" is the association descriptor of the association.
        !          1239: It should be different for each association.
        !          1240: 
        !          1241: The \verb"addr" argument in the address of the DSA you wish to contact.
        !          1242: 
        !          1243: \subsection {Other DAP Operations}
        !          1244: 
        !          1245: The other DAP operations (read, list, modify\ldots), use the same format
        !          1246: a already described, but with two extra integer parameters, thus
        !          1247: \begin{quote}\index{ds\_read}\small\begin{verbatim}
        !          1248: ds_read (arg, error, result)
        !          1249: \end{verbatim}\end{quote}
        !          1250: becomes
        !          1251: \begin{quote}\index{ds\_read}\small\begin{verbatim}
        !          1252: dap_read (ad, id, arg, error, result)
        !          1253: \end{verbatim}\end{quote}
        !          1254: where \verb"ad" is the association descriptor used in the bind, and 
        !          1255: \verb"id" uniquely identifies the operation with respect to other
        !          1256: operation on the same association.
        !          1257: 
        !          1258: \section {Asynchronous Access}
        !          1259: 
        !          1260: All of the procedures so far described make synchronous
        !          1261: associations to the DSA.
        !          1262: In the next release,
        !          1263: asynchronous access will be provided.

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.