doc/asn.xml

   1 <!-- $Header: /home/cvsroot/yaz/doc/asn.xml,v 1.1 2001-01-04 13:36:24 adam Exp $ -->
   2 <chapter><title>The ASN Module</title>
   3 <sect1><title>Introduction</title>
   4 <para>
   5 The &asn; module provides you with a set of C struct definitions for the
   6 various PDUs of the protocol, as well as for the complex types
   7 appearing within the PDUs. For the primitive data types, the C
   8 representation often takes the form of an ordinary C language type,
   9 such as <literal>int</literal>. For ASN.1 constructs that have no direct
  10 representation in C, such as general octet strings and bit strings,
  11 the &odr; module (see section <link linkend="odr">The ODR Module</link>)
  12 provides auxiliary definitions.
  13 </para>
  14 </sect1>
  15 <sect1><title>Preparing PDUs</title>
  16
  17 <para>
  18 A structure representing a complex ASN.1 type doesn't in itself contain the
  19 members of that type. Instead, the structure contains
  20 <emphasis>pointers</emphasis> to the members of the type.
  21 This is necessary, in part, to allow a mechanism for specifying which
  22 of the optional structure (SEQUENCE) members are present, and which
  23 are not. It follows that you will need to somehow provide space for
  24 the individual members of the structure, and set the pointers to
  25 refer to the members.
  26 </para>
  27 <para>
  28 The conversion routines don't care how you allocate and maintain your
  29 C structures - they just follow the pointers that you provide.
  30 Depending on the complexity of your application, and your personal
  31 taste, there are at least three different approaches that you may take
  32 when you allocate the structures.
  33 </para>
  34
  35 <para>
  36 You can use static or automatic local variables in the function that
  37 prepares the PDU. This is a simple approach, and it provides the most
  38 efficient form of memory management. While it works well for flat
  39 PDUs like the InitReqest, it will generally not be sufficient for say,
  40 the generation of an arbitrarily complex RPN query structure.
  41 </para>
  42 <para>
  43 You can individually create the structure and its members using the
  44 <function>malloc(2)</function> function. If you want to ensure that
  45 the data is freed when it is no longer needed, you will have to
  46 define a function that individually releases each member of a
  47 structure before freeing the structure itself.
  48 </para>
  49 <para>
  50 You can use the <function>odr_malloc()</function> function (see section
  51 <link linkend="odr-use">Using ODR</link> for details). When you use
  52 <function>odr_malloc()</function>, you can release all of the
  53 allocated data in a single operation, independent of any pointers and
  54 relations between the data. <function>odr_malloc()</function> is based on a
  55 &quot;nibble-memory&quot;
  56 scheme, in which large portions of memory are allocated, and then
  57 gradually handed out with each call to <function>odr_malloc()</function>.
  58 The next time you call <function>odr_reset()</function>, all of the
  59 memory allocated since the last call is recycled for future use (actually,
  60 it is placed on a free-list).
  61 </para>
  62 <para>
  63 You can combine all of the methods described here. This will often be
  64 the most practical approach. For instance, you might use
  65 <function>odr_malloc()</function> to allocate an entire structure and
  66 some of its elements, while you leave other elements pointing to global
  67 or per-session default variables.
  68 </para>
  69
  70 <para>
  71 The &asn; module provides an important aid in creating new PDUs. For
  72 each of the PDU types (say, <function>Z_InitRequest</function>), a
  73 function is provided that allocates and initializes an instance of
  74 that PDU type for you. In the case of the InitRequest, the function is
  75 simply named <function>zget_InitRequest()</function>, and it sets up
  76 reasonable default value for all of the mandatory members. The optional
  77 members are generally initialized to null pointers. This last aspect
  78 is very important: it ensures that if the PDU definitions are
  79 extended after you finish your implementation (to accommodate
  80 new versions of the protocol, say), you won't get into trouble with
  81 uninitialized pointers in your structures. The functions use
  82 <function>odr_malloc()</function> to
  83 allocate the PDUs and its members, so you can free everything again with a
  84 single call to <function>odr_reset()</function>. We strongly recommend
  85 that you use the <literal>zget_*</literal>
  86 functions whenever you are preparing a PDU (in a C++ API, the
  87 <literal>zget_</literal>
  88 functions would probably be promoted to constructors for the
  89 individual types).
  90 </para>
  91 <para>
  92 The prototype for the individual PDU types generally look like this:
  93 </para>
  94 <synopsis>
  95   Z_&lt;type> *zget_&lt;type>(ODR o);
  96 </synopsis>
  97
  98 <para>
  99 eg.:
 100 </para>
 101
 102 <synopsis>
 103   Z_InitRequest *zget_InitRequest(ODR o);
 104 </synopsis>
 105
 106 <para>
 107 The &odr; handle should generally be your encoding stream, but it needn't be.
 108 </para>
 109 <para>
 110 As well as the individual PDU functions, a function <function>
 111 zget_APDU()</function> is
 112 provided, which allocates a toplevel Z-APDU of the type requested:
 113 </para>
 114
 115 <synopsis>
 116   Z_APDU *zget_APDU(ODR o, int which);
 117 </synopsis>
 118
 119 <para>
 120 The <varname>which</varname> parameter is (of course) the discriminator
 121 belonging to the <varname>Z_APDU</varname> <literal>CHOICE</literal> type.
 122 All of the interface described here is provided by the &asn; module, and
 123 you access it through the <filename>proto.h</filename> header file.
 124
 125 </para>
 126 </sect1>
 127 <sect1><title id="oid">Object Identifiers</title>
 128 <para>
 129 When you refer to object identifiers in your application, you need to
 130 be aware that SR and Z39.50 use two different set of OIDs to refer to
 131 the same objects. To handle this easily, &yaz; provides a utility module
 132 to &asn; which provides an internal representation of the OIDs used in
 133 both protocols. Each oid is described by a structure:
 134 </para>
 135
 136 <screen>
 137 typedef struct oident
 138 {
 139     enum oid_proto proto;
 140     enum oid_class class;
 141     enum oid_value value;
 142     int oidsuffix[OID_SIZE];
 143     char *desc;
 144 } oident;
 145 </screen>
 146
 147 <para>
 148 The <literal>proto</literal> field can be set to either
 149 <literal>PROTO_SR</literal> or <literal>PROTO_Z3950</literal>.
 150 The <literal>class</literal> might be, say,
 151 <literal>CLASS_RECSYN</literal>, and the <literal>value</literal> might be
 152 <literal>VAL_USMARC</literal> for the USMARC record format. Functions
 153 </para>
 154
 155 <screen>
 156 int *oid_ent_to_oid(struct oident *ent, int *dst);
 157 struct oident *oid_getentbyoid(int *o);
 158 </screen>
 159
 160 <para>
 161 are provided to map between object identifiers and database entries.
 162 If you store a member of the <literal>oid_proto</literal> type in
 163 your association state information, it's a simple matter, at runtime,
 164 to generate the correct OID when you need it. For decoding, you can
 165 simply ignore the proto field, or if you're strict, you can verify
 166 that your peer is using the OID family from the correct protocol.
 167 The <literal>desc</literal> field is a short, human-readable name
 168 for the PDU, useful mainly for diagnostic output.
 169 </para>
 170
 171 <note>
 172 <para>
 173 The old function <function>oid_getoidbyent</function> still exists but is
 174 not thread safe. Use <function>oid_ent_to_oid</function> instead
 175 and pass an array of size <literal>OID_SIZE</literal>.
 176 </para>
 177 </note>
 178
 179 <note>
 180 <para>
 181 Plans are underway to merge the two protocols into a single
 182 definition, with one set of object identifiers. When this happens, the
 183 oid module will no longer be required to support protocol
 184 independence, but it should still be useful as a simple OID database.
 185 </para>
 186 </note>
 187
 188 </sect1>
 189 <sect1><title>EXTERNAL Data</title>
 190
 191 <para>
 192 In order to achieve extensibility and adaptability to different
 193 application domains, the new version of the protocol defines many
 194 structures outside of the main ASN.1 specification, referencing them
 195 through ASN.1 EXTERNAL constructs. To simplify the construction and access
 196 to the externally referenced data, the &asn; module defines a
 197 specialized version of the EXTERNAL construct, called
 198 <literal>Z_External</literal>.It is defined thus:
 199 </para>
 200
 201 <screen>
 202 typedef struct Z_External
 203 {
 204     Odr_oid *direct_reference;
 205     int *indirect_reference;
 206     char *descriptor;
 207     enum
 208     {
 209         /* Generic types */
 210         Z_External_single = 0,
 211         Z_External_octet,
 212         Z_External_arbitrary,
 213
 214         /* Specific types */
 215         Z_External_SUTRS,
 216         Z_External_explainRecord,
 217         Z_External_resourceReport1,
 218         Z_External_resourceReport2
 219
 220         ...
 221
 222     } which;
 223     union
 224     {
 225         /* Generic types */
 226         Odr_any *single_ASN1_type;
 227         Odr_oct *octet_aligned;
 228         Odr_bitmask *arbitrary;
 229
 230         /* Specific types */
 231         Z_SUTRS *sutrs;
 232         Z_ExplainRecord *explainRecord;
 233         Z_ResourceReport1 *resourceReport1;
 234         Z_ResourceReport2 *resourceReport2;
 235
 236         ...
 237
 238     } u;
 239 } Z_External;
 240 </screen>
 241
 242 <para>
 243 When decoding, the &asn; module will attempt to determine which
 244 syntax describes the data by looking at the reference fields
 245 (currently only the direct-reference). For ASN.1 structured data, you
 246 need only consult the <literal>which</literal> field to determine the type of
 247 data. You can the access  the data directly through the union. When
 248 constructing data for encoding, you set the union pointer to point to
 249 the data, and set the <literal>which</literal> field accordingly.
 250 Remember also to set the direct (or indirect) reference to the correct
 251 OID for the data type.
 252 For non-ASN.1 data such as MARC records, use the
 253 <literal>octet_aligned</literal> arm of the union.
 254 </para>
 255
 256 <para>
 257 Some servers return ASN.1 structured data values (eg. database
 258 records) as BER-encoded records placed in the <literal>octet-aligned</literal>
 259 branch of the EXTERNAL CHOICE. The ASN-module will <emphasis>not</emphasis>
 260 automatically decode these records. To help you decode the records in
 261 the application, the function
 262 </para>
 263
 264 <screen>
 265 Z_ext_typeent *z_ext_gettypebyref(oid_value ref);
 266 </screen>
 267
 268 <para>
 269 Can be used to retrieve information about the known, external data
 270 types. The function return a pointer to a static area, or NULL, if no
 271 match for the given direct reference is found. The
 272 <literal>Z_ext_typeent</literal>
 273 is defined as:
 274 </para>
 275
 276 <screen>
 277 typedef struct Z_ext_typeent
 278 {
 279     oid_value dref;    /* the direct-reference OID value. */
 280     int what;          /* discriminator value for the external CHOICE */
 281     Odr_fun fun;       /* decoder function */
 282 } Z_ext_typeent;
 283 </screen>
 284
 285 <para>
 286 The <literal>what</literal> member contains the <literal>Z_External</literal>
 287 union discriminator value for the given type: For the SUTRS record
 288 syntax, the value would be <literal>Z_External_sutrs</literal>.
 289 The <literal>fun</literal> member contains a pointer to the
 290 function which encodes/decodes the given type. Again, for the SUTRS
 291 record syntax, the value of <literal>fun</literal> would be
 292 <literal>z_SUTRS</literal> (a function pointer).
 293 </para>
 294
 295 <para>
 296 If you receive an EXTERNAL which contains an octet-string value that
 297 you suspect of being an ASN.1-structured data value, you can use
 298 <literal>z_ext_gettypebyref</literal> to look for the provided
 299 direct-reference.
 300 If the return value is different from NULL, you can use the provided
 301 function to decode the BER string (see section <link linkend="odr-use">
 302 Using ODR</link>).
 303 </para>
 304
 305 <para>
 306 If you want to <emphasis>send</emphasis> EXTERNALs containing
 307 ASN.1-structured values in the occtet-aligned branch of the CHOICE, this
 308 is possible too. However, on the encoding phase, it requires a somewhat
 309 involved juggling around of the various buffers involved.
 310 </para>
 311 <para>
 312 If you need to add new, externally defined data types, you must update
 313 the struct above, in the source file <filename>prt-ext.h</filename>, as
 314 well as the encoder/decoder in the file <filename>prt-ext.c</filename>.
 315 When changing the latter, remember to update both the <literal>arm</literal>
 316 arrary and the list <literal>type_table</literal>, which drives the CHOICE
 317 biasing that is necessary to tell the different, structured types apart
 318 on decoding.
 319 </para>
 320
 321 <note>
 322 <para>
 323 Eventually, the EXTERNAL processing will most likely
 324 automatically insert the correct OIDs or indirect-refs. First,
 325 however, we need to determine how application-context management
 326 (specifically the presentation-context-list) should fit into the
 327 various modules.
 328 </para>
 329 </note>
 330
 331 </sect1>
 332 <sect1><title>PDU Contents Table</title>
 333
 334 <para>
 335 We include, for reference, a listing of the fields of each top-level
 336 PDU, as well as their default settings.
 337 </para>
 338
 339
 340 <table frame="top"><title>Default settings for Z39.50 PDU's</title>
 341 <tgroup cols="3">
 342 <colspec colname="field"></colspec>
 343 <colspec colname="type"></colspec>
 344 <colspec colname="value"></colspec>
 345 <thead>
 346 <row>
 347 <entry>Field</entry>
 348 <entry>Type</entry>
 349 <entry>Default Value</entry>
 350 </row>
 351 </thead>
 352 <tbody>
 353 <row>
 354 <entry namest="field" nameend="value">Z_InitRequest</entry>
 355 </row>
 356
 357 <row><entry>
 358 referenceId
 359 </entry><entry>
 360 Z_ReferenceId
 361 </entry><entry>
 362 NULL
 363 </entry></row>
 364
 365 <row><entry>
 366 protocolVersion
 367 </entry><entry>
 368 Odr_bitmask
 369 </entry><entry>
 370 Empty bitmask
 371 </entry></row>
 372
 373 <row><entry>
 374 options
 375 </entry><entry>
 376 Odr_bitmask
 377 </entry><entry>
 378 Empty bitmask
 379 </entry></row>
 380
 381 </tbody>
 382 </tgroup>
 383 </table>
 384
 385 <screen>
 386 Z_InitRequest
 387 -------------
 388 Field                        Type                Default value
 389
 390 referenceId                  Z_ReferenceId       NULL
 391 protocolVersion              Odr_bitmask         Empty bitmask
 392 options                      Odr_bitmask         Empty bitmask
 393 preferredMessageSize         int                 30*1024
 394 maximumRecordSize            int                 30*1024
 395 idAuthentication             Z_IdAuthentication  NULL
 396 implementationId             char*               "YAZ (id=81)"
 397 implementationName           char*               "Index Data/YAZ"
 398 implementationVersion        char*               YAZ_VERSION
 399 userInformationField         Z_UserInformation   NULL
 400 otherInfo                    Z_OtherInformation  NULL
 401 </screen>
 402
 403 <screen>
 404 Z_InitResponse
 405 --------------
 406 Field                        Type                Default value
 407
 408 referenceId                  Z_ReferenceId       NULL
 409 protocolVersion              Odr_bitmask         Empty bitmask
 410 options                      Odr_bitmask         Empty bitmask
 411 preferredMessageSize         int                 30*1024
 412 maximumRecordSize            int                 30*1024
 413 result                       bool_t              TRUE
 414 implementationId             char*               "YAZ (id=81)"
 415 implementationName           char*               "Index Data/YAZ"
 416 implementationVersion        char*               YAZ_VERSION
 417 userInformationField         Z_UserInformat..    NULL
 418 otherInfo                    Z_OtherInformation  NULL
 419 </screen>
 420
 421 <screen>
 422 Z_SearchRequest
 423 ---------------
 424 Field                        Type                Default value
 425
 426 referenceId                  Z_ReferenceId       NULL
 427 smallSetUpperBound           int                 0
 428 largeSetLowerBound           int                 1
 429 mediumSetPresentNumber       int                 0
 430 replaceIndicator             bool_t              TRUE
 431 resultSetName                char*               "default"
 432 num_databaseNames            int                 0
 433 databaseNames                char**              NULL
 434 smallSetElementSetNames      Z_ElementSetNames   NULL
 435 mediumSetElementSetNames     Z_ElementSetNames   NULL
 436 preferredRecordSyntax        Odr_oid             NULL
 437 query                        Z_Query             NULL
 438 additionalSearchInfo         Z_OtherInformation  NULL
 439 otherInfo                    Z_OtherInformation  NULL
 440 </screen>
 441
 442 <screen>
 443 Z_SearchResponse
 444 ----------------
 445 Field                        Type                Default value
 446
 447 referenceId                  Z_ReferenceId       NULL
 448 resultCount                  int                 0
 449 numberOfRecordsReturned      int                 0
 450 nextResultSetPosition        int                 0
 451 searchStatus                 bool_t              TRUE
 452 resultSetStatus              int                 NULL
 453 presentStatus                int                 NULL
 454 records                      Z_Records           NULL
 455 additionalSearchInfo         Z_OtherInformation  NULL
 456 otherInfo                    Z_OtherInformation  NULL
 457 </screen>
 458
 459 <screen>
 460 Z_PresentRequest
 461 ----------------
 462 Field                        Type                Default value
 463
 464 referenceId                  Z_ReferenceId       NULL
 465 resultSetId                  char*               "default"
 466 resultSetStartPoint          int                 1
 467 numberOfRecordsRequested     int                 10
 468 num_ranges                   int                 0
 469 additionalRanges             Z_Range             NULL
 470 recordComposition            Z_RecordComposition NULL
 471 preferredRecordSyntax        Odr_oid             NULL
 472 maxSegmentCount              int                 NULL
 473 maxRecordSize                int                 NULL
 474 maxSegmentSize               int                 NULL
 475 otherInfo                    Z_OtherInformation  NULL
 476 </screen>
 477
 478 <screen>
 479 Z_PresentResponse
 480 -----------------
 481 Field                        Type                Default value
 482
 483 referenceId                  Z_ReferenceId       NULL
 484 numberOfRecordsReturned      int                 0
 485 nextResultSetPosition        int                 0
 486 presentStatus                int                 Z_PRES_SUCCESS
 487 records                      Z_Records           NULL
 488 otherInfo                    Z_OtherInformation  NULL
 489 </screen>
 490
 491 <screen>
 492 Z_DeleteResultSetRequest
 493 ------------------------
 494 Field                        Type                Default value
 495
 496 referenceId                  Z_ReferenceId       NULL
 497 deleteFunction               int                 Z_DeleteRequest_list
 498 num_ids                      int                 0
 499 resultSetList                char**              NULL
 500 otherInfo                    Z_OtherInformation  NULL
 501 </screen>
 502
 503 <screen>
 504 Z_DeleteResultSetResponse
 505 -------------------------
 506 Field                        Type                Default value
 507
 508 referenceId                  Z_ReferenceId       NULL
 509 deleteOperationStatus        int                 Z_DeleteStatus_success
 510 num_statuses                 int                 0
 511 deleteListStatuses           Z_ListStatus**      NULL
 512 numberNotDeleted             int                 NULL
 513 num_bulkStatuses             int                 0
 514 bulkStatuses                 Z_ListStatus        NULL
 515 deleteMessage                char*               NULL
 516 otherInfo                    Z_OtherInformation  NULL
 517 </screen>
 518
 519 <screen>
 520 Z_ScanRequest
 521 -------------
 522 Field                        Type                Default value
 523
 524 referenceId                  Z_ReferenceId       NULL
 525 num_databaseNames            int                 0
 526 databaseNames                char**              NULL
 527 attributeSet                 Odr_oid             NULL
 528 termListAndStartPoint        Z_AttributesPlus... NULL
 529 stepSize                     int                 NULL
 530 numberOfTermsRequested       int                 20
 531 preferredPositionInResponse  int                 NULL
 532 otherInfo                    Z_OtherInformation  NULL
 533 </screen>
 534
 535 <screen>
 536 Z_ScanResponse
 537 --------------
 538 Field                        Type                Default value
 539
 540 referenceId                  Z_ReferenceId       NULL
 541 stepSize                     int                 NULL
 542 scanStatus                   int                 Z_Scan_success
 543 numberOfEntriesReturned      int                 0
 544 positionOfTerm               int                 NULL
 545 entries                      Z_ListEntris        NULL
 546 attributeSet                 Odr_oid             NULL
 547 otherInfo                    Z_OtherInformation  NULL
 548 </screen>
 549
 550 <screen>
 551 Z_TriggerResourceControlRequest
 552 -------------------------------
 553 Field                        Type                Default value
 554
 555 referenceId                  Z_ReferenceId       NULL
 556 requestedAction              int                 Z_TriggerResourceCtrl_resou..
 557 prefResourceReportFormat     Odr_oid             NULL
 558 resultSetWanted              bool_t              NULL
 559 otherInfo                    Z_OtherInformation  NULL
 560 </screen>
 561
 562 <screen>
 563 Z_ResourceControlRequest
 564 ------------------------
 565 Field                        Type                Default value
 566
 567 referenceId                  Z_ReferenceId       NULL
 568 suspendedFlag                bool_t              NULL
 569 resourceReport               Z_External          NULL
 570 partialResultsAvailable      int                 NULL
 571 responseRequired             bool_t              FALSE
 572 triggeredRequestFlag         bool_t              NULL
 573 otherInfo                    Z_OtherInformation  NULL
 574 </screen>
 575
 576 <screen>
 577 Z_ResourceControlResponse
 578 -------------------------
 579 Field                        Type                Default value
 580
 581 referenceId                  Z_ReferenceId       NULL
 582 continueFlag                 bool_t              TRUE
 583 resultSetWanted              bool_t              NULL
 584 otherInfo                    Z_OtherInformation  NULL
 585 </screen>
 586
 587 <screen>
 588 Z_AccessControlRequest
 589 ----------------------
 590 Field                        Type                Default value
 591
 592 referenceId                  Z_ReferenceId       NULL
 593 which                        enum                Z_AccessRequest_simpleForm;
 594 u                            union               NULL
 595 otherInfo                    Z_OtherInformation  NULL
 596 </screen>
 597
 598 <screen>
 599 Z_AccessControlResponse
 600 -----------------------
 601 Field                        Type                Default value
 602
 603 referenceId                  Z_ReferenceId       NULL
 604 which                        enum                Z_AccessResponse_simpleForm
 605 u                            union               NULL
 606 diagnostic                   Z_DiagRec           NULL
 607 otherInfo                    Z_OtherInformation  NULL
 608 </screen>
 609
 610 <screen>
 611 Z_Segment
 612 ---------
 613 Field                        Type                Default value
 614
 615 referenceId                  Z_ReferenceId       NULL
 616 numberOfRecordsReturned      int                 value=0
 617 num_segmentRecords           int                 0
 618 segmentRecords               Z_NamePlusRecord    NULL
 619 otherInfo                    Z_OtherInformation  NULL
 620 </screen>
 621
 622 <screen>
 623 Z_Close
 624 -------
 625 Field                        Type                Default value
 626
 627 referenceId                  Z_ReferenceId       NULL
 628 closeReason                  int                 Z_Close_finished
 629 diagnosticInformation        char*               NULL
 630 resourceReportFormat         Odr_oid             NULL
 631 resourceFormat               Z_External          NULL
 632 otherInfo                    Z_OtherInformation  NULL
 633
 634 </screen>
 635
 636 </sect1>
 637 </chapter>