From: Adam Dickmeiss Date: Sun, 23 Feb 2003 14:24:09 +0000 (+0000) Subject: More on SRW. X-Git-Tag: YAZ.2.0~11 X-Git-Url: http://sru.miketaylor.org.uk/?a=commitdiff_plain;h=8c2af81438405f3bbbd01a73265ce20edbd5bb73;p=yaz-moved-to-github.git More on SRW. --- diff --git a/doc/soap.xml b/doc/soap.xml index a954ccf..33951f7 100644 --- a/doc/soap.xml +++ b/doc/soap.xml @@ -1,4 +1,4 @@ - + SOAP and SRW Introduction @@ -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 + The handlers is a list of SOAP codec handlers - one handler for each service namespace. For SRW, the - namespace is http://www.loc.gov/zing/srw/v1.0/. + 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,45 +138,86 @@ 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 - SRW is just one kind of SOAP handler as described in the previous - section. + SRW is just one implementation of a SOAP handler as described + in the previous section. + The encoder/decoder handler for SRW 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; @@ -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]