From c7cff6778b8d69f6e3c41dbfd939f44436911b90 Mon Sep 17 00:00:00 2001 From: Adam Dickmeiss Date: Fri, 4 May 2007 12:24:15 +0000 Subject: [PATCH] OID documentation update. --- doc/asn.xml | 17 +++-- doc/tools.xml | 192 ++++++++++++++++++++++++++++++++++++++++++++++++--------- 2 files changed, 176 insertions(+), 33 deletions(-) diff --git a/doc/asn.xml b/doc/asn.xml index 3420e63..7f6208e 100644 --- a/doc/asn.xml +++ b/doc/asn.xml @@ -1,4 +1,4 @@ - + The Z39.50 ASN.1 Module Introduction @@ -132,7 +132,16 @@ - Object Identifiers + Object Identifiers (YAZ 2) + + + + This material only applies to version 2 series of YAZ. You need not + read this material if you are working with YAZ 3. + See for more information on OIDs. + + + When you refer to object identifiers in your application, you need to be aware that SR and Z39.50 use two different set of OIDs to refer to @@ -271,7 +280,7 @@ typedef struct Z_External - Z_ext_typeent *z_ext_gettypebyref(oid_value ref); + Z_ext_typeent *z_ext_gettypebyref(const oid *oid); @@ -285,7 +294,7 @@ typedef struct Z_External typedef struct Z_ext_typeent { - oid_value dref; /* the direct-reference OID value. */ + int oid[OID_SIZE]; /* the direct-reference OID. */ int what; /* discriminator value for the external CHOICE */ Odr_fun fun; /* decoder function */ } Z_ext_typeent; diff --git a/doc/tools.xml b/doc/tools.xml index 7f12685..4b0d62b 100644 --- a/doc/tools.xml +++ b/doc/tools.xml @@ -1,4 +1,4 @@ - + Supporting Tools @@ -1541,30 +1541,176 @@ void cql_to_xml_stdio(struct cql_node *cn, FILE *f); The basic YAZ representation of an OID is an array of integers, - terminated with the value -1. The &odr; module provides two - utility-functions to create and copy this type of data elements: + terminated with the value -1. There is a typedef + of this integer to Odr_oid but this is not consistenly + used everywhere. - + + An OID can either be declared as a automatic variable or we can + allocated using the ODR/NMEM memory utilities. It's + guaranteed that an OID can fit in OID_SIZE integers. + + Create OID on stack + + We can create an OID for the Bib-1 attribute set with: + + int bib1[OID_SIZE]; + myoid[0] = 1; + myoid[1] = 2; + myoid[2] = 840; + myoid[3] = 10003; + myoid[4] = 3; + myoid[5] = 1; + myoid[6] = -1; + + + + + And OID may also be filled from a string-based representation using + dots (.). This is achieved by function + + int oid_dotstring_to_oid(const char *name, int *oid); + + + Using oid_oiddotstring_to_oid + + We can create the Bib-1 attribute set OID easier with: + + int bib1[OID_SIZE]; + oid_oiddotstring_to_oid("1.2.840.10003.3.1", bib1); + + + + + We can also allocate an OID dynamically on a ODR stream with: - Odr_oid *odr_getoidbystr(ODR o, char *str); + Odr_oid *odr_getoidbystr(ODR o, const char *str); + This creates an OID from string-based representation using dots. + This function take an &odr; stream as parameter. This stream is used to + allocate memory for the data elements, which is released on a + subsequent call to odr_reset() on that stream. + + + Using odr_getoidbystr + + We can create a OID for the Bib-1 attribute set with: + + Odr_oid *bib1 = odr_getoidbystr(odr, "1.2.840.10003.3.1"); + + + - Creates an OID based on a string-based representation using dots (.) - to separate elements in the OID. + The function + + char *oid_oid_to_dotstring(const int *oid, char *oidbuf) + + does the reverse of oid_oiddotstring_to_oid. It + converts an OID to the string-based representation using dots. + The supplied char buffer oidbuf holds the resulting + string and must be at least OID_STR_MAX in size. - - Odr_oid *odr_oiddup(ODR odr, Odr_oid *o); - - - Creates a copy of the OID referenced by the o - parameter. - Both functions take an &odr; stream as parameter. This stream is used to - allocate memory for the data elements, which is released on a - subsequent call to odr_reset() on that stream. + OIDs can be copied with oid_oidcpy which takes + two OID lists as arguments. Alternativly, an OID copy can be allocated + on a ODR stream with: + + Odr_oid *odr_oiddup(ODR odr, const Odr_oid *o); + + + + OIDs can be compared with oid_oidcmp which returns + zero if the two OIDs provided are identical; non-zero otherwise. + + + OID database + + From YAZ version 3 and later, the oident system has been replaced + by an OID database. OID database is a misnomer .. the old odient + was a database system too. + + + The OID database is really just a map between named Object Identifiers + (string) and their OID raw equivalents. Most operations either + convert from string to OID or other way around. + + + Unfortunately, whenever we supply a string we must also specify the + OID class. The class is necessary because some + strings correspond to multiple OIDs. An example of such a string is + Bib-1 which may either be an attribute-set + or a diagnostic-set. + + + Applications using the YAZ database should include + yaz/yaz_db.h. + + + A YAZ database handle is of type yaz_oid_db_t. + Actually that's a pointer. You need not think deal with that. + YAZ has a built-in database which can be considered "constant" for + most purposes. + We can get hold that by using function yaz_oid_std. + + + All functions with prefix yaz_string_to_oid + converts from class + string to OID. We have variants of this + operation due to different memory allocation strategies. + + + All functions with prefix + yaz_oid_to_string converts from OID to string + + class. + + + Create OID with YAZ DB + + We can create an OID for the Bib-1 attribute set on the ODR stream + odr with: + + Odr_oid *bib1 = + yaz_string_to_oid_odr(yaz_oid_std(), CLASS_ATTSET, "Bib-1", odr); + + This is more complex than using odr_getoidbystr. + You would only use yaz_string_to_oid_odr when the + string (here Bib-1) is supplied by a user or configuration. + + + + + All the object identifers in the standard OID database as returned + by yaz_oid_std can referenced directly in a + program. Each constant OID is prefixed with yaz_oid_ - + followed by OID class (lowercase) - then by OID name (normalized and + lowercase). + + + These are declared in yaz/oid_std.h but are + included by yaz/oid_db.h as well. + + + Use a built-in OID + + We can allocate our own OID filled with the constant OID for + Bib-1 with: + + Odr_oid *bib1 = odr_oiddup(o, yaz_oid_attset_bib1); + + + + + + OID oident + + + + The oident utility has been removed from YAZ version 3. This + sub section only applies to YAZ version 2. + + The OID module provides a higher-level representation of the @@ -1798,18 +1944,6 @@ typedef struct oident oidbuf and returning its address. - - Finally, the module provides the following utility functions, whose - meaning should be obvious: - - - - void oid_oidcpy(int *t, int *s); - void oid_oidcat(int *t, int *s); - int oid_oidcmp(int *o1, int *o2); - int oid_oidlen(int *o); - - The OID module has been criticized - and perhaps rightly so @@ -1826,8 +1960,8 @@ typedef struct oident + - Nibble Memory -- 1.7.10.4