![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to q-operations.tex CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [CSRG BSD Unix] / 43BSDReno / contrib / isode-beta / doc / manual|
Return to q-operations.tex CVS log | Up to [CSRG BSD Unix] / 43BSDReno / contrib / isode-beta / doc / manual |
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.