doc/asn.xml

   1 <!-- $Header: /home/cvsroot/yaz/doc/asn.xml,v 1.2 2001-07-19 12:46:57 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="field">Z_InitRequest</entry>
 355 </row>
 356
 357 <row><entry>
 358 referenceId</entry><entry>Z_ReferenceId</entry><entry>NULL
 359 </entry></row>
 360
 361 <row><entry>
 362 protocolVersion</entry><entry>Odr_bitmask</entry><entry>Empty bitmask
 363 </entry></row>
 364
 365 <row><entry>
 366 options</entry><entry>Odr_bitmask</entry><entry>Empty bitmask
 367 </entry></row>
 368
 369 <row><entry>
 370 preferredMessageSize</entry><entry>int</entry><entry>30*1024
 371 </entry></row>
 372
 373 <row><entry>
 374 maximumRecordSize</entry><entry>int</entry><entry>30*1024
 375 </entry></row>
 376
 377 <row><entry>
 378 idAuthentication</entry><entry>Z_IdAuthentication</entry><entry>NULL
 379 </entry></row>
 380
 381 <row><entry>
 382 implementationId</entry><entry>char*</entry><entry>"YAZ (id=81)"
 383 </entry></row>
 384
 385 <row><entry>
 386 implementationName</entry><entry>char*</entry><entry>"Index Data/YAZ"
 387 </entry></row>
 388
 389 <row><entry>
 390 implementationVersion</entry><entry>char*</entry><entry>YAZ_VERSION
 391 </entry></row>
 392
 393 <row><entry>
 394 userInformationField</entry><entry>Z_UserInformation</entry><entry>NULL
 395 </entry></row>
 396
 397 <row><entry>
 398 otherInfo</entry><entry>Z_OtherInformation</entry><entry>NULL
 399 </entry></row>
 400
 401 </tbody>
 402 </tgroup>
 403 </table>
 404
 405 <screen>
 406 Z_InitResponse
 407 --------------
 408 Field                        Type                Default value
 409
 410 referenceId                  Z_ReferenceId       NULL
 411 protocolVersion              Odr_bitmask         Empty bitmask
 412 options                      Odr_bitmask         Empty bitmask
 413 preferredMessageSize         int                 30*1024
 414 maximumRecordSize            int                 30*1024
 415 result                       bool_t              TRUE
 416 implementationId             char*               "YAZ (id=81)"
 417 implementationName           char*               "Index Data/YAZ"
 418 implementationVersion        char*               YAZ_VERSION
 419 userInformationField         Z_UserInformat..    NULL
 420 otherInfo                    Z_OtherInformation  NULL
 421 </screen>
 422
 423 <screen>
 424 Z_SearchRequest
 425 ---------------
 426 Field                        Type                Default value
 427
 428 referenceId                  Z_ReferenceId       NULL
 429 smallSetUpperBound           int                 0
 430 largeSetLowerBound           int                 1
 431 mediumSetPresentNumber       int                 0
 432 replaceIndicator             bool_t              TRUE
 433 resultSetName                char*               "default"
 434 num_databaseNames            int                 0
 435 databaseNames                char**              NULL
 436 smallSetElementSetNames      Z_ElementSetNames   NULL
 437 mediumSetElementSetNames     Z_ElementSetNames   NULL
 438 preferredRecordSyntax        Odr_oid             NULL
 439 query                        Z_Query             NULL
 440 additionalSearchInfo         Z_OtherInformation  NULL
 441 otherInfo                    Z_OtherInformation  NULL
 442 </screen>
 443
 444 <screen>
 445 Z_SearchResponse
 446 ----------------
 447 Field                        Type                Default value
 448
 449 referenceId                  Z_ReferenceId       NULL
 450 resultCount                  int                 0
 451 numberOfRecordsReturned      int                 0
 452 nextResultSetPosition        int                 0
 453 searchStatus                 bool_t              TRUE
 454 resultSetStatus              int                 NULL
 455 presentStatus                int                 NULL
 456 records                      Z_Records           NULL
 457 additionalSearchInfo         Z_OtherInformation  NULL
 458 otherInfo                    Z_OtherInformation  NULL
 459 </screen>
 460
 461 <screen>
 462 Z_PresentRequest
 463 ----------------
 464 Field                        Type                Default value
 465
 466 referenceId                  Z_ReferenceId       NULL
 467 resultSetId                  char*               "default"
 468 resultSetStartPoint          int                 1
 469 numberOfRecordsRequested     int                 10
 470 num_ranges                   int                 0
 471 additionalRanges             Z_Range             NULL
 472 recordComposition            Z_RecordComposition NULL
 473 preferredRecordSyntax        Odr_oid             NULL
 474 maxSegmentCount              int                 NULL
 475 maxRecordSize                int                 NULL
 476 maxSegmentSize               int                 NULL
 477 otherInfo                    Z_OtherInformation  NULL
 478 </screen>
 479
 480 <screen>
 481 Z_PresentResponse
 482 -----------------
 483 Field                        Type                Default value
 484
 485 referenceId                  Z_ReferenceId       NULL
 486 numberOfRecordsReturned      int                 0
 487 nextResultSetPosition        int                 0
 488 presentStatus                int                 Z_PRES_SUCCESS
 489 records                      Z_Records           NULL
 490 otherInfo                    Z_OtherInformation  NULL
 491 </screen>
 492
 493 <screen>
 494 Z_DeleteResultSetRequest
 495 ------------------------
 496 Field                        Type                Default value
 497
 498 referenceId                  Z_ReferenceId       NULL
 499 deleteFunction               int                 Z_DeleteRequest_list
 500 num_ids                      int                 0
 501 resultSetList                char**              NULL
 502 otherInfo                    Z_OtherInformation  NULL
 503 </screen>
 504
 505 <screen>
 506 Z_DeleteResultSetResponse
 507 -------------------------
 508 Field                        Type                Default value
 509
 510 referenceId                  Z_ReferenceId       NULL
 511 deleteOperationStatus        int                 Z_DeleteStatus_success
 512 num_statuses                 int                 0
 513 deleteListStatuses           Z_ListStatus**      NULL
 514 numberNotDeleted             int                 NULL
 515 num_bulkStatuses             int                 0
 516 bulkStatuses                 Z_ListStatus        NULL
 517 deleteMessage                char*               NULL
 518 otherInfo                    Z_OtherInformation  NULL
 519 </screen>
 520
 521 <screen>
 522 Z_ScanRequest
 523 -------------
 524 Field                        Type                Default value
 525
 526 referenceId                  Z_ReferenceId       NULL
 527 num_databaseNames            int                 0
 528 databaseNames                char**              NULL
 529 attributeSet                 Odr_oid             NULL
 530 termListAndStartPoint        Z_AttributesPlus... NULL
 531 stepSize                     int                 NULL
 532 numberOfTermsRequested       int                 20
 533 preferredPositionInResponse  int                 NULL
 534 otherInfo                    Z_OtherInformation  NULL
 535 </screen>
 536
 537 <screen>
 538 Z_ScanResponse
 539 --------------
 540 Field                        Type                Default value
 541
 542 referenceId                  Z_ReferenceId       NULL
 543 stepSize                     int                 NULL
 544 scanStatus                   int                 Z_Scan_success
 545 numberOfEntriesReturned      int                 0
 546 positionOfTerm               int                 NULL
 547 entries                      Z_ListEntris        NULL
 548 attributeSet                 Odr_oid             NULL
 549 otherInfo                    Z_OtherInformation  NULL
 550 </screen>
 551
 552 <screen>
 553 Z_TriggerResourceControlRequest
 554 -------------------------------
 555 Field                        Type                Default value
 556
 557 referenceId                  Z_ReferenceId       NULL
 558 requestedAction              int                 Z_TriggerResourceCtrl_resou..
 559 prefResourceReportFormat     Odr_oid             NULL
 560 resultSetWanted              bool_t              NULL
 561 otherInfo                    Z_OtherInformation  NULL
 562 </screen>
 563
 564 <screen>
 565 Z_ResourceControlRequest
 566 ------------------------
 567 Field                        Type                Default value
 568
 569 referenceId                  Z_ReferenceId       NULL
 570 suspendedFlag                bool_t              NULL
 571 resourceReport               Z_External          NULL
 572 partialResultsAvailable      int                 NULL
 573 responseRequired             bool_t              FALSE
 574 triggeredRequestFlag         bool_t              NULL
 575 otherInfo                    Z_OtherInformation  NULL
 576 </screen>
 577
 578 <screen>
 579 Z_ResourceControlResponse
 580 -------------------------
 581 Field                        Type                Default value
 582
 583 referenceId                  Z_ReferenceId       NULL
 584 continueFlag                 bool_t              TRUE
 585 resultSetWanted              bool_t              NULL
 586 otherInfo                    Z_OtherInformation  NULL
 587 </screen>
 588
 589 <screen>
 590 Z_AccessControlRequest
 591 ----------------------
 592 Field                        Type                Default value
 593
 594 referenceId                  Z_ReferenceId       NULL
 595 which                        enum                Z_AccessRequest_simpleForm;
 596 u                            union               NULL
 597 otherInfo                    Z_OtherInformation  NULL
 598 </screen>
 599
 600 <screen>
 601 Z_AccessControlResponse
 602 -----------------------
 603 Field                        Type                Default value
 604
 605 referenceId                  Z_ReferenceId       NULL
 606 which                        enum                Z_AccessResponse_simpleForm
 607 u                            union               NULL
 608 diagnostic                   Z_DiagRec           NULL
 609 otherInfo                    Z_OtherInformation  NULL
 610 </screen>
 611
 612 <screen>
 613 Z_Segment
 614 ---------
 615 Field                        Type                Default value
 616
 617 referenceId                  Z_ReferenceId       NULL
 618 numberOfRecordsReturned      int                 value=0
 619 num_segmentRecords           int                 0
 620 segmentRecords               Z_NamePlusRecord    NULL
 621 otherInfo                    Z_OtherInformation  NULL
 622 </screen>
 623
 624 <screen>
 625 Z_Close
 626 -------
 627 Field                        Type                Default value
 628
 629 referenceId                  Z_ReferenceId       NULL
 630 closeReason                  int                 Z_Close_finished
 631 diagnosticInformation        char*               NULL
 632 resourceReportFormat         Odr_oid             NULL
 633 resourceFormat               Z_External          NULL
 634 otherInfo                    Z_OtherInformation  NULL
 635
 636 </screen>
 637
 638 </sect1>
 639 </chapter>