X-Git-Url: http://git.indexdata.com/?p=yaz-moved-to-github.git;a=blobdiff_plain;f=doc%2Fsoap.xml;h=c665367aefdace831944751af099482af67791ab;hp=8a962b24202e386ddffea749f91193640e1fe1c0;hb=053367cbe356fb3ce0def34b065dae589d700daf;hpb=add5a2db6b4360b1b448ad09f991a3977eb1220d diff --git a/doc/soap.xml b/doc/soap.xml index 8a962b2..c665367 100644 --- a/doc/soap.xml +++ b/doc/soap.xml @@ -1,15 +1,15 @@ - -SOAP and SRW +SOAP and SRU Introduction - &yaz; uses a very simple implementation of SOAP that only, - currenly, supports what is sufficient to offer SRW functionality. - The implementation uses the - tree - API of libxml2 to encode and decode SOAP packages. + &yaz; uses a very simple implementation of + SOAP that only, + currenly, supports what is sufficient to offer SRU SOAP functionality. + The implementation uses the + tree API of + libxml2 to encode and decode SOAP packages. - Like the Z39.50 ASN.1 module, the &yaz; SRW implementation uses + Like the Z39.50 ASN.1 module, the &yaz; SRU implementation uses simple C structs to represent SOAP packages as well as HTTP packages. @@ -98,16 +98,34 @@ int z_soap_codec(ODR o, Z_SOAP **pp, Z_SOAP_Handler *handlers); - The content_buf and content_len + The content_buf and content_len is XML buffer and length of buffer respectively. - The handlers is a list of SOAP services codec - handlers - one handler for each service namespace. For SRW, the - namespace is http://www.loc.gov/zing/srw/v1.0/. + The handlers is a list of SOAP codec + handlers - one handler for each service namespace. For SRU SOAP, the + namespace would be http://www.loc.gov/zing/srw/v1.0/. - Each handler is define as follows: + When decoding, the z_soap_codec + inspects the XML content + and tries to match one of the services namespaces of the + supplied handlers. If there is a match a handler function + is invoked which decodes that particular SOAP package. + If successful, the returned Z_SOAP package will be + of type Z_SOAP_Generic. + Member no is + set the offset of handler that matched; ns + is set to namespace of matching handler; the void pointer + p is set to the C data structure assocatiated + with the handler. + + + When a NULL namespace is met (member ns bwlow), + that specifies end-of-list. + + + Each handler is defined as follows: typedef struct { char *ns; @@ -120,50 +138,91 @@ typedef struct { is user-defined data which is passed to handler. - The prototype for a handler is: + The prototype for a SOAP service handler is: int handler(ODR o, void * ptr, void **handler_data, void *client_data, const char *ns); + The o specifies the mode (decode/encode) + as usual. The second argument, ptr, + is a libxml2 tree node pointer (xmlNodePtr) + and is a pointer to the Body element + of the SOAP package. The handler_data + is an opaque pointer to a C definitions associated with the + SOAP service. client_data is the pointer + which was set as part of the Z_SOAP_handler. + Finally, ns the service namespace. - SRW + SRU - SRW is just one kind of SOAP handler as described in the previous - section. + SRU SOAP is just one implementation of a SOAP handler as described + in the previous section. + The encoder/decoder handler for SRU is defined as + follows: -#include <yaz/soap.h> +#include <yaz/srw.h> +int yaz_srw_codec(ODR o, void * pptr, + Z_SRW_GDU **handler_data, + void *client_data, const char *ns); + + Here, Z_SRW_GDU is either + searchRetrieveRequest or a searchRetrieveResponse. + + + + The xQuery and xSortKeys are not handled yet by + the SRW implementation of &yaz;. Explain is also missing. + Future versions of &yaz; will include these features. + + + + The definition of searchRetrieveRequest is: + typedef struct { - char *recordSchema; - char *recordData_buf; - int recordData_len; - int *recordPosition; -} Z_SRW_record; -typedef struct { - int *code; - char *details; -} Z_SRW_diagnostic; - -typedef struct { - char *query; - char *pQuery; - void *xQuery; - char *sortKeys; - void *xSortKeys; - int *startRecord; +#define Z_SRW_query_type_cql 1 +#define Z_SRW_query_type_xcql 2 +#define Z_SRW_query_type_pqf 3 + int query_type; + union { + char *cql; + char *xcql; + char *pqf; + } query; + +#define Z_SRW_sort_type_none 1 +#define Z_SRW_sort_type_sort 2 +#define Z_SRW_sort_type_xSort 3 + int sort_type; + union { + char *none; + char *sortKeys; + char *xSortKeys; + } sort; + int *startRecord; int *maximumRecords; char *recordSchema; char *recordPacking; char *database; } Z_SRW_searchRetrieveRequest; - + + Please observe that data of type xsd:string is represented + as a char pointer (char *). A null pointer + means that the element is absent. + Data of type xsd:integer is representd as a pointer to + an int (int *). Again, a null pointer + us used for absent elements. + + + The SearchRetrieveResponse has the following definition. + typedef struct { int * numberOfRecords; char * resultSetId; int * resultSetIdleTime; - + Z_SRW_record *records; int num_records; @@ -171,19 +230,34 @@ typedef struct { int num_diagnostics; int *nextRecordPosition; } Z_SRW_searchRetrieveResponse; - -#define Z_SRW_searchRetrieve_request 1 -#define Z_SRW_searchRetrieve_response 2 - + + The num_records and num_diagnostics + is number of returned records and diagnostics respectively and also + correspond to the "size of" arrays records + and diagnostics. + + + A retrieval record is defined as follows: + typedef struct { - int which; - union { - Z_SRW_searchRetrieveRequest *request; - Z_SRW_searchRetrieveResponse *response; - } u; -} Z_SRW_searchRetrieve; + char *recordSchema; + char *recordData_buf; + int recordData_len; + int *recordPosition; +} Z_SRW_record; + + The record data is defined as a buffer of some length so that + data can be of any type. SRW 1.0 currenly doesn't allow for this + (only XML), but future versions might do. + + + And, a diagnostic as: + +typedef struct { + int *code; + char *details; +} Z_SRW_diagnostic; - [more to be written]