From: Adam Dickmeiss Date: Fri, 21 Feb 2003 12:06:05 +0000 (+0000) Subject: Separate SOAP/SRW chapter X-Git-Tag: YAZ.2.0~16 X-Git-Url: http://sru.miketaylor.org.uk/?a=commitdiff_plain;h=add5a2db6b4360b1b448ad09f991a3977eb1220d;p=yaz-moved-to-github.git Separate SOAP/SRW chapter --- diff --git a/doc/Makefile.am b/doc/Makefile.am index 44d6dd9..0e79a3b 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -1,11 +1,11 @@ -## $Id: Makefile.am,v 1.38 2003-02-21 00:24:26 adam Exp $ +## $Id: Makefile.am,v 1.39 2003-02-21 12:06:05 adam Exp $ docdir=$(datadir)/doc/@PACKAGE@ XMLFILES=yaz.xml.in introduction.xml installation.xml indexdata.xml \ asn.xml tools.xml odr.xml comstack.xml frontend.xml license.xml \ future.xml client.xml zoom.xml credits.xml ztest-options.xml \ - yaz-client-commands.xml + yaz-client-commands.xml soap.xml HTMLFILES = \ asn.external.html asn.html asn.oid.html asn.pdu.html asn.preparing.html \ @@ -18,7 +18,8 @@ HTMLFILES = \ license.html license.other.html odr.debugging.html odr.html \ odr.programming.html odr.use.html server.backendfunctions.html \ server.backend.html server.frontend.html server.html server.invocation.html \ - server.main.html tools.html tools.nmem.html tools.oid.html yaz.html \ + server.main.html soap.html soap.http.html soap.xml.html \ + tools.html tools.nmem.html tools.oid.html yaz.html \ zoom.events.html zoom.html zoom.options.html zoom.query.html \ zoom.records.html zoom.resultsets.html zoom.scan.html diff --git a/doc/comstack.xml b/doc/comstack.xml index 4c2c6ba..335eb0d 100644 --- a/doc/comstack.xml +++ b/doc/comstack.xml @@ -1,4 +1,4 @@ - + The COMSTACK Module Synopsis (blocking mode) @@ -60,8 +60,8 @@ if (buf) The &comstack; subsystem provides a transparent interface to different types of transport - stacks for the exchange of BER-encoded data. At present, the - RFC1729 method (BER over TCP/IP), local UNIX socket and an + stacks for the exchange of BER-encoded data and HTTP packets. + At present, the RFC1729 method (BER over TCP/IP), local UNIX socket and an experimental SSL stack are supported, but others may be added in time. The philosophy of the module is to provide a simple interface by hiding unused options and @@ -115,16 +115,17 @@ if (buf) tcpip_type - TCP/IP (BER over TCP/IP) + TCP/IP (BER over TCP/IP or HTTP over TCP/IP) ssl_type Secure Socket Layer (SSL). This COMSTACK - is experimental and is not fully implemented. + is experimental and is not fully implemented. If + HTTP is used, this effectively is HTTPS. unix_type - Unix socket (unix only). Fast local transfer via + Unix socket (unix only). Local Transfer via file socket. See unix 7. @@ -137,7 +138,7 @@ if (buf) The blocking parameter should be one if you wish the association to operate in blocking mode, zero otherwise. The protocol field should be - PROTO_Z3950. + PROTO_Z3950 or PROTO_HTTP. Protocol PROTO_SR is no longer supported. @@ -186,7 +187,8 @@ if (buf) - Receives a PDU from the peer. Returns the number of bytes read. + Receives a PDU or HTTP Response from the peer. Returns the number of + bytes read. In nonblocking mode, it is possible that not all of the packet can be read at once. In this case, the function returns 1. To simplify the interface, the function is diff --git a/doc/future.xml b/doc/future.xml index 2533b8e..fde8d9e 100644 --- a/doc/future.xml +++ b/doc/future.xml @@ -1,4 +1,4 @@ - + Future Directions @@ -10,13 +10,6 @@ - The 'retrieval' module needs to be finalized and documented. We think - it can form a useful resource for people dealing with complex record - structures, but for now, you'll mostly have to chew through the code - yourself to make use of it. Not acceptable. - - - &yaz; is a BER toolkit and as such should support all protocols out there based on that. We'd like to see running ILL applications. It shouldn't be that hard. Another thing that would be interesting is @@ -25,11 +18,25 @@ + The SOAP implementation is incomplete. In the future we hope + to add more features to it. Perhaps make a WSDL/XML Schema compiler. + The authors of libxml2 are already working on XML Schema / RelagNG + compilers so this may not be too hard. + + + + It would be neat to have a proper module mechanism for the Generic + Frontend Server so that backend would be dynamically + loaded (as shared objects / DLLs). + + + Other than that, &yaz; generally moves in the directions which appear to make the most people happy (including ourselves, as prime users of the software). If there's something you'd like to see in here, then drop us a note and let's see what we can come up with. + + Introduction @@ -110,11 +110,15 @@ documents the most commonly used Z39.50 C data structures offered by the &yaz; API. Client - developers using ZOOM you do not need reading this. - For the remaining client developers (not using ZOOM), - reading this chapter is a must. - Z39.50 server implementors should read this, unless you're - developing a simple server (or SRW only). + developers using ZOOM and non-Z39.50 implementors may skip this. + + + + + + describes how SRW and SOAP is used + in &yaz;. Only if you're developing SOAP/SRW applications + this section is a must. diff --git a/doc/soap.xml b/doc/soap.xml new file mode 100644 index 0000000..8a962b2 --- /dev/null +++ b/doc/soap.xml @@ -0,0 +1,190 @@ + +SOAP and SRW + 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. + + + Like the Z39.50 ASN.1 module, the &yaz; SRW implementation uses + simple C structs to represent SOAP packages as well as + HTTP packages. + + + HTTP + + &yaz; only offers HTTP as transport carrier for SOAP, but it is + relatively easy to change that. + + + The following definition of Z_GDU (Generic Data + Unit) allows for both HTTP and Z39.50 in one packet. + + +#include <yaz/zgdu.h> + +#define Z_GDU_Z3950 1 +#define Z_GDU_HTTP_Request 2 +#define Z_GDU_HTTP_Response 3 +typedef struct { + int which; + union { + Z_APDU *z3950; + Z_HTTP_Request *HTTP_Request; + Z_HTTP_Response *HTTP_Response; + } u; +} Z_GDU ; + + + The corresponding Z_GDU encoder/decoder is z_GDU. + The z3950 is any of the known BER encoded Z39.50 + APDUs. + HTTP_Request and HTTP_Response + is the HTTP Request and Response respectively. + + + SOAP Packages + + Every SOAP package in &yaz; is represented as follows: + +#include <yaz/soap.h> + +typedef struct { + char *fault_code; + char *fault_string; + char *details; +} Z_SOAP_Fault; + +typedef struct { + int no; + char *ns; + void *p; +} Z_SOAP_Generic; + +#define Z_SOAP_fault 1 +#define Z_SOAP_generic 2 +#define Z_SOAP_error 3 +typedef struct { + int which; + union { + Z_SOAP_Fault *fault; + Z_SOAP_Generic *generic; + Z_SOAP_Fault *soap_error; + } u; + const char *ns; +} Z_SOAP; + + + + The fault and soap_error + arms represent both a SOAP fault - struct + Z_SOAP_Fault. Any other generic + (valid) package is represented by Z_SOAP_Generic. + + + The ns as part of Z_SOAP + is the namespace for SOAP itself and reflects the SOAP + version. For version 1.1 it is + http://schemas.xmlsoap.org/soap/envelope/, + for version 1.2 it is + http://www.w3.org/2001/06/soap-envelope. + + +int z_soap_codec(ODR o, Z_SOAP **pp, + char **content_buf, int *content_len, + Z_SOAP_Handler *handlers); + + + 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/. + + + Each handler is define as follows: + +typedef struct { + char *ns; + void *client_data; + Z_SOAP_fun f; +} Z_SOAP_Handler; + + The ns is namespace of service associated with + handler f. client_data + is user-defined data which is passed to handler. + + + The prototype for a handler is: + +int handler(ODR o, void * ptr, void **handler_data, + void *client_data, const char *ns); + + + + SRW + + SRW is just one kind of SOAP handler as described in the previous + section. + +#include <yaz/soap.h> + +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; + int *maximumRecords; + char *recordSchema; + char *recordPacking; + char *database; +} Z_SRW_searchRetrieveRequest; + +typedef struct { + int * numberOfRecords; + char * resultSetId; + int * resultSetIdleTime; + + Z_SRW_record *records; + int num_records; + + Z_SRW_diagnostic *diagnostics; + int num_diagnostics; + int *nextRecordPosition; +} Z_SRW_searchRetrieveResponse; + +#define Z_SRW_searchRetrieve_request 1 +#define Z_SRW_searchRetrieve_response 2 + +typedef struct { + int which; + union { + Z_SRW_searchRetrieveRequest *request; + Z_SRW_searchRetrieveResponse *response; + } u; +} Z_SRW_searchRetrieve; + + [more to be written] + + + + diff --git a/doc/yaz.xml.in b/doc/yaz.xml.in index 718d034..a066d7d 100644 --- a/doc/yaz.xml.in +++ b/doc/yaz.xml.in @@ -9,6 +9,7 @@ + @@ -24,7 +25,7 @@ COMSTACK"> ZOOM"> ]> - + YAZ User's Guide and Reference @@ -61,6 +62,7 @@ &chap-frontend; &chap-client; &chap-asn; + &chap-soap; &chap-tools; &chap-odr; &chap-comstack;