X-Git-Url: http://git.indexdata.com/?p=simpleserver-moved-to-github.git;a=blobdiff_plain;f=SimpleServer.pm;h=f6a4c399b84b02263b068638fb756ea986cb4d5c;hp=35f96f263f42687bfd41598ddae5786856e58cfd;hb=eb69046dd58ade30eada3a5ec5f2d4c05fb3b9b5;hpb=3253ded6f7e5fbd840152247ecc54f6e591feb6c

diff --git a/SimpleServer.pm b/SimpleServer.pm
index 35f96f2..f6a4c39 100644
--- a/SimpleServer.pm
+++ b/SimpleServer.pm
@@ -1,5 +1,5 @@
 ##
-##  Copyright (c) 2000-2004, Index Data.
+##  Copyright (c) 2000-2006, Index Data.
 ##
 ##  Permission to use, copy, modify, distribute, and sell this software and
 ##  its documentation, in whole or in part, for any purpose, is hereby granted,
@@ -25,7 +25,7 @@
 ##
 ##
 
-## $Id: SimpleServer.pm,v 1.28 2006-07-21 22:14:19 mike Exp $
+## $Id: SimpleServer.pm,v 1.35 2007-08-15 13:21:22 mike Exp $
 
 package Net::Z3950::SimpleServer;
 
@@ -39,7 +39,7 @@ require AutoLoader;
 
 @ISA = qw(Exporter AutoLoader DynaLoader);
 @EXPORT = qw( );
-$VERSION = '1.02';
+$VERSION = '1.06';
 
 bootstrap Net::Z3950::SimpleServer $VERSION;
 
@@ -69,6 +69,13 @@ sub launch_server {
 	my $self = shift;
 	my @args = @_;
 
+	### This modal internal interface, in which we set a bunch of
+	#   globals and then call start_server(), is asking for
+	#   trouble.  Instead, we should just pass the $self object
+	#   as a parameter into start_server().
+	if (defined($self->{GHANDLE})) {
+		set_ghandle($self->{GHANDLE});
+	}
 	if (defined($self->{INIT})) {
 		set_init_handler($self->{INIT});
 	}
@@ -151,15 +158,14 @@ Net::Z3950::SimpleServer - Simple Perl API for building Z39.50 servers.
 	}
   }
 
-
   ## Register custom event handlers:
+  my $z = new Net::Z3950::SimpleServer(GHANDLE = $someObject,
+				       INIT   =>  \&my_init_handler,
+				       CLOSE  =>  \&my_close_handler,
+				       SEARCH =>  \&my_search_handler,
+				       FETCH  =>  \&my_fetch_handler);
 
-  my $z = new Net::Z3950::SimpleServer(		INIT   =>  \&my_init_handler,
-						CLOSE  =>  \&my_close_handler,
-						SEARCH =>  \&my_search_handler,
-						FETCH  =>  \&my_fetch_handler);
   ## Launch server:
-
   $z->launch_server("ztest.pl", @ARGV);
 
 =head1 DESCRIPTION
@@ -218,6 +224,11 @@ means of the SimpleServer object constructor
 			FETCH	=>	\&my_fetch_handler,
   			EXPLAIN =>	\&my_explain_handler);
 
+In addition, the arguments to the constructor may include GHANDLE, a
+global handle which is made available to each invocation of every
+callback function.  This is typically a reference to either a hash or
+an object.
+
 If you want your SimpleServer to start a thread (threaded mode) to
 handle each incoming Z39.50 request instead of forking a process
 (forking mode), you need to register the handlers by symbol rather
@@ -269,6 +280,7 @@ The argument hash passed to the init handler has the form
 	     			    ## this member contains user name
 	     PASS      =>  "yyy"    ## Under same conditions, this member
 	     			    ## contains the password in clear text
+	     GHANDLE   =>  $obj     ## Global handler specified at creation
 	     HANDLE    =>  undef    ## Handler of Perl data structure
 	  };
 
@@ -298,6 +310,7 @@ mous hash. The structure is the following:
   $args = {
 	  			    ## Request parameters:
 
+	     GHANDLE   =>  $obj     ## Global handler specified at creation
 	     HANDLE    =>  ref,     ## Your session reference.
 	     SETNAME   =>  "id",    ## ID of the result set
 	     REPL_SET  =>  0,       ## Replace set if already existing?
@@ -507,6 +520,7 @@ The informations exchanged between client and present handle are:
   $args = {
 				    ## Client/server request:
 
+	     GHANDLE   =>  $obj     ## Global handler specified at creation
 	     HANDLE    =>  ref,     ## Reference to datastructure
 	     SETNAME   =>  "id",    ## Result set ID
 	     START     =>  xxx,     ## Start position
@@ -533,6 +547,7 @@ The parameters exchanged between the server and the fetch handler are
   $args = {
 				    ## Client/server request:
 
+	     GHANDLE   =>  $obj     ## Global handler specified at creation
 	     HANDLE    =>  ref	    ## Reference to data structure
 	     SETNAME   =>  "id"     ## ID of the requested result set
 	     OFFSET    =>  nnn      ## Record offset number
@@ -581,7 +596,10 @@ an index of a book, you always find something! The parameters exchanged are
   $args = {
 						## Client request
 
-		HANDLE		=> $ref		## Reference to data structure
+		GHANDLE		=> $obj,	## Global handler specified at creation
+		HANDLE		=> $ref,	## Reference to data structure
+		DATABASES	=> ["xxx"],	## Reference to a list of data-
+						## bases to search
 		TERM		=> 'start',	## The start term
 		NUMBER		=> xx,		## Number of requested terms
 		POS		=> yy,		## Position of starting point
@@ -615,20 +633,23 @@ should point at a data structure of this kind,
 				...
 	];
 
-The $status flag should be assigned one of two values:
+The $status flag is only meaningful after a successful scan, and
+should be assigned one of two values:
 
-  Net::Z3950::SimpleServer::ScanSuccess  On success (default)
-  Net::Z3950::SimpleServer::ScanPartial  Less terms returned than requested
+  Net::Z3950::SimpleServer::ScanSuccess  Full success (default)
+  Net::Z3950::SimpleServer::ScanPartial  Fewer terms returned than requested
 
 The STEP member contains the requested number of entries in the term-list
 between two adjacent entries in the response.
 
 =head2 Close handler
 
-The argument hash recieved by the close handler has one element only:
+The argument hash recieved by the close handler has two elements only:
 
   $args = {
 				    ## Server provides:
+
+	     GHANDLE   =>  $obj     ## Global handler specified at creation
 	     HANDLE    =>  ref      ## Reference to data structure
 	  };