lib/Net/Z3950/ZOOM.pm

   1 # $Id: ZOOM.pm,v 1.14 2006-04-07 07:48:42 mike Exp $
   2
   3 package Net::Z3950::ZOOM;
   4
   5 use 5.008;
   6 use strict;
   7 use warnings;
   8
   9 our $VERSION = '1.05';
  10
  11 require XSLoader;
  12 XSLoader::load('Net::Z3950::ZOOM', $VERSION);
  13
  14 my($vs, $ss) = ("x" x 100, "x" x 100); # allocate space for these strings
  15 my $version = Net::Z3950::ZOOM::yaz_version($vs, $ss);
  16 if ($version < 0x02010B && ! -f "/tmp/ignore-ZOOM-YAZ-version-mismatch") {
  17     warn <<__EOT__;
  18 *** WARNING!
  19 ZOOM-Perl requires at least version 2.0.11 of YAZ, but is currently
  20 running against only version $vs (sys-string '$ss').
  21 Some things may not work.
  22 __EOT__
  23 }
  24
  25 # The only thing this module does is define the following constants,
  26 # which MUST BE KEPT SYNCHRONISED with the definitions in <yaz/zoom.h>
  27
  28 # Error codes, as returned from connection_error()
  29 sub ERROR_NONE { 0 }
  30 sub ERROR_CONNECT { 10000 }
  31 sub ERROR_MEMORY { 10001 }
  32 sub ERROR_ENCODE { 10002 }
  33 sub ERROR_DECODE { 10003 }
  34 sub ERROR_CONNECTION_LOST { 10004 }
  35 sub ERROR_INIT { 10005 }
  36 sub ERROR_INTERNAL { 10006 }
  37 sub ERROR_TIMEOUT { 10007 }
  38 sub ERROR_UNSUPPORTED_PROTOCOL { 10008 }
  39 sub ERROR_UNSUPPORTED_QUERY { 10009 }
  40 sub ERROR_INVALID_QUERY { 10010 }
  41 sub ERROR_CQL_PARSE { 10011 }
  42 sub ERROR_CQL_TRANSFORM { 10012 }
  43
  44 # Event types, as returned from connection_last_event()
  45 sub EVENT_NONE { 0 }
  46 sub EVENT_CONNECT { 1 }
  47 sub EVENT_SEND_DATA { 2 }
  48 sub EVENT_RECV_DATA { 3 }
  49 sub EVENT_TIMEOUT { 4 }
  50 sub EVENT_UNKNOWN { 5 }
  51 sub EVENT_SEND_APDU { 6 }
  52 sub EVENT_RECV_APDU { 7 }
  53 sub EVENT_RECV_RECORD { 8 }
  54 sub EVENT_RECV_SEARCH { 9 }
  55
  56
  57 =head1 NAME
  58
  59 Net::Z3950::ZOOM - Perl extension for invoking the ZOOM-C API.
  60
  61 =head1 SYNOPSIS
  62
  63  use Net::Z3950::ZOOM;
  64  $conn = Net::Z3950::ZOOM::connection_new($host, $port);
  65  $errcode = Net::Z3950::ZOOM::connection_error($conn, $errmsg, $addinfo);
  66  Net::Z3950::ZOOM::connection_option_set($conn, databaseName => "foo");
  67  # etc.
  68
  69 =head1 DESCRIPTION
  70
  71 This module provides a simple thin-layer through to the ZOOM-C
  72 functions in the YAZ toolkit for Z39.50 and SRW/U communication.  You
  73 should not be using this very nasty, low-level API.  You should be
  74 using the C<ZOOM> module instead, which implements a nice, Perlish API
  75 on top of this module, conformant to the ZOOM Abstract API described at
  76 http://zoom.z3950.org/api/
  77
  78 To enforce the don't-use-this-module prohibition, I am not even going
  79 to document it.  If you really, really, really want to use it, then it
  80 pretty much follows the API described in the ZOOM-C documentation at
  81 http://www.indexdata.dk/yaz/doc/zoom.tkl
  82
  83 The only additional (non-ZOOM-C) function provided by this module is
  84 C<eventstr()>, which takes as its argument an event code such as
  85 C<Net::Z3950::ZOOM::EVENT_SEND_APDU>, and returns a corresponding
  86 short string.
  87
  88 =cut
  89
  90 sub eventstr {
  91     my($code) = @_;
  92
  93     if ($code == EVENT_NONE) {
  94         return "none";
  95     } elsif ($code == EVENT_CONNECT) {
  96         return "connect";
  97     } elsif ($code == EVENT_SEND_DATA) {
  98         return "send data";
  99     } elsif ($code == EVENT_RECV_DATA) {
 100         return "receive data";
 101     } elsif ($code == EVENT_TIMEOUT) {
 102         return "timeout";
 103     } elsif ($code == EVENT_UNKNOWN) {
 104         return "unknown";
 105     } elsif ($code == EVENT_SEND_APDU) {
 106         return "send apdu";
 107     } elsif ($code == EVENT_RECV_APDU) {
 108         return "receive apdu";
 109     } elsif ($code == EVENT_RECV_RECORD) {
 110         return "receive record";
 111     } elsif ($code == EVENT_RECV_SEARCH) {
 112         return "receive search";
 113     }
 114     return "impossible event " . $code;
 115 }
 116
 117 =head1 SEE ALSO
 118
 119 The C<ZOOM> module, included in the same distribution as this one.
 120
 121 =head1 AUTHOR
 122
 123 Mike Taylor, E<lt>mike@indexdata.comE<gt>
 124
 125 =head1 COPYRIGHT AND LICENCE
 126
 127 Copyright (C) 2005 by Index Data.
 128
 129 This library is free software; you can redistribute it and/or modify
 130 it under the same terms as Perl itself, either Perl version 5.8.4 or,
 131 at your option, any later version of Perl 5 you may have available.
 132
 133 =cut
 134
 135 1;