///////////////////////////////////////////////////////////////////
//
// Simple Digital Library Interoperability Protocol (SDLIP)
//
// Documentation:
//   Protocol is described at 
//     http://www-diglib.stanford.edu/~testbed/doc2/SDLIP
//   There are two interfaces in this module:
//     - Search:        methods used by clients to send queries to library
//                      services proxies (LSPs)
//     - Result Access: methods used by clients to access query results
//   This IDL spec is used for the operations between client apps and
//   their client transport module, and between LSPs and their server
//   transport module. For these operations, file SDLIPLocal.idl
//   imports this file.
//   This same spec is also used to specify communication between
//   transport modules which communicate via CORBA. For these installations,
//   file SDLIPCorba.idl imports this file.
//
// Last Modified: Jul 18, 1999 (Andreas Paepcke)
//
///////////////////////////////////////////////////////////////////
//
// Revisions:
//
// Thu Jul  01 08:58:07 1999 (Sergey Melnik) melnik@DB.stanford.EDU
//  Split into AbstractInterface and CorbaMapping with CommonPart.
//  SDLIP exception codes are now integers, added exception codes constants.
//  Also added constants for default parameters.
// Tue Jun  29 14:20:37 1997 (Andreas Paepcke) paepcke@Haddock.Stanford.EDU
//  Removed asynch operations and made XMLString parms into objects.
// Tue Dec  29 14:20:37 1997 (Andreas Paepcke) paepcke@Haddock.Stanford.EDU
//  Updated parameter names to be shorter.
// Wed Dec  16 11:11:37 1997 (Andreas Paepcke) paepcke@Haddock.Stanford.EDU
//  Added server side session IDs. Modified calls to use them.
// Wed Dec  16 11:11:37 1997 (Andreas Paepcke) paepcke@Haddock.Stanford.EDU
//  Allowed server delegation only as part of the searchSynch() and
//  setSessionInfo() calls. Delegation no longer allowed in addDocs()
// Wed Dec  16 11:11:37 1997 (Andreas Paepcke) paepcke@Haddock.Stanford.EDU
//  Added Subcollections typedef and changed subcols parms to that (used
//  to be sequence of string in some cases).

    // Forward reference
    interface ResultAccess;

    // Exception
    exception SDLIPException {

	unsigned short code;
	string reason;
	XMLObject details;
    };

    // Exception codes
    const unsigned short INVALID_REQUEST_EXC = 400;
    const unsigned short UNAUTHORIZED_EXC = 401;
    const unsigned short PAYMENT_REQUIRED_EXC = 402;
    const unsigned short NOT_FOUND_EXC = 404;
    const unsigned short ILLEGAL_METHOD_EXC = 405;
    const unsigned short REQUEST_TIMEOUT_EXC = 408;
    const unsigned short QUERY_LANGUAGE_UNKNOWN_EXC = 450;
    const unsigned short BAD_QUERY_EXC = 451;
    const unsigned short INVALID_PROPERTY_EXC = 452;
    const unsigned short INVALID_SESSIONID_EXC = 453;
    const unsigned short INVALID_SUBCOLLECTION_EXC = 454;
    const unsigned short MALFORMED_XML_EXC = 455;
    const unsigned short SERVER_ERROR_EXC = 500;
    const unsigned short NOT_IMPLEMENTED_EXC = 501;
    const unsigned short SERVICE_UNAVAILABLE_EXC = 503;


  ///////////////////////////////////////////////////////////////////
  // Search Interface
  // 
  // The methods in this interface allow clients to send queries to a
  // library server proxy.
  //
  ///////////////////////////////////////////////////////////////////

  interface Search {
 
    const long RETURN_ALL_DOCS = -1;
    const long MAINTAIN_UNLIMITED = -1;
    const long UNKNOWABLE = -1;
    const long NOT_YET_KNOWN = -2;

    // The search() allows clients to submit queries to services:

    void  search(
	in long	 clientSID,		// Client-side session ID
	in XMLObject subcols,	        // Choice of collections to search
	in XMLObject query,		// The query
	in long	 numDocs,		// Number of docs to return or RETURN_ALL_DOCS
	in XMLObject docPropList,	// Properties to return for each doc
	in long	 stateTimeoutReq,	// Number of seconds to maintain
					// state at server or MAINTAIN_UNLIMITED
	in XMLObject queryOptions,	// Additional info for the LSP
        out long expectedTotal,         // Expected number of results
                                        // or UNKNOWABLE or NOT_YET_KNOWN
        out long stateTimeout,          // state timeout set at the server
        out long serverSID,	        // Server-side session ID
        out XMLObject serverDelegate,   // Address for future service requests
	out XMLObject result		// XML-Encoded result list.
    ) raises(SDLIPException);
  };


  ///////////////////////////////////////////////////////////////////
  // ResultAccess Interface
  // 
  // The methods in this interface allow clients to retrieve
  // document results
  //
  ///////////////////////////////////////////////////////////////////

  interface ResultAccess {

    const long CANCEL_ALL_REQUESTS = 0;

    // The getSessionInfo method returns information about an active session
    void getSessionInfo( 
	in  long  serverSID,	     	// The server-side session ID
	out long  expectedTotal,	// Number of documents in result
					// or UNKNOWABLE or NOT_YET_KNOWN
        out long  stateTimeout		// Time before server disposes
					// the session state (**** TOTAL)
    ) raises(SDLIPException);


    // The getDocs method is used to get more docs in existing session
    void getDocs(		
	in long	  serverSID,		// The server-side session ID 
					// of the original query
	in long	 reqID,			// new each time
	in XMLObject docPropList,	// properties to get
	in string docsToGet,		// document indices to retrieve
        out XMLObject res		// Search result XML string
    ) raises(SDLIPException);


    // The method extendStateTimeout() is used by the client to extend the
    // time that result state is kept at the server
    void  extendStateTimeout(
        in long  serverSID,	        // the server-side session ID
	in long	 additionalTime,	// additionalTime (in seconds)
        out long timeAllotted		// time allotted by server (in seconds)
    ) raises(SDLIPException);


    // The cancelRequest() Method allows the client to cancel a session
    // and/or request.
    void cancelRequest(
	in long	 serverSID,		// session to be cancelled
	in long	 reqID     		// request to be cancelled or
                                        // CANCEL_ALL_REQUESTS (of the given session)
    ) raises(SDLIPException);

  };

  ///////////////////////////////////////////////////////////////////
  // MetaData Interface
  // 
  // The methods in this interface allow clients to retrieve
  // server metadata
  //
  ///////////////////////////////////////////////////////////////////

  interface Metadata {

    // Get info about LSP's interfaces
    void getInterface(           

      out XMLObject theInterface  // XML-encoded info about the versions of each
                               // supported interface. 
                               // Ex: <SDLIPVersion>
                               //        <search>SDLIP1.0</search>
                               //        <resultAccess>SDLIP1.1</resultAccess>
                               //        <sourceMetadata>SDLIP1.0</sourceMetadata>
                               //     </SDLIPVersion>
    ) raises (SDLIPException);


    void getSubcollectionInfo(

      out XMLObject subcolInfo // XML list of subcollections and their
                               // supported query languages
    ) raises (SDLIPException);


    // This operation allows clients to retrieve information about
    // which document properties may be searched or retrieved for
    // the specified subcollection.
    void getPropertyInfo(       // Returns attrList XML string 
      in string subcolName,     // {null} If not supplied, request for default
                                // subcollection.
      out XMLObject propInfo    // Acceptable properties
                                // specified subcollection, and whether they are
                                // searchable/retrievable
    ) raises (SDLIPException);
  
  };