ACE/apps/JAWS/clients/Caching/URL_Locator.h

   1 /* -*- C++ -*- */
   2
   3
   4 //=============================================================================
   5 /**
   6  *  @file    URL_Locator.h
   7  *
   8  *  @author Nanbor Wang
   9  */
  10 //=============================================================================
  11
  12
  13 #ifndef ACE_URL_LOCATOR_H
  14 #define ACE_URL_LOCATOR_H
  15
  16 #include "URL_Properties.h"
  17
  18 /**
  19  * @class ACE_URL_Locator
  20  *
  21  * @brief Abstract Base class designates what interfaces a URL_Locator
  22  * should provide.
  23  *
  24  * This class defines the basic URL_Locator APIs.
  25  * An URL locator provides services for URL clients to
  26  * query specific URL location that has certain properties
  27  * and URL providers to export their services and a set of
  28  * APIs to maintain their offers.
  29  */
  30 class ACE_Svc_Export ACE_URL_Locator
  31 {
  32 public:
  33   // Request type
  34   enum ACE_URL_Locator_Op_Type
  35   {
  36     QUERY = 0,
  37     EXPORT,
  38     WITHDRAW,
  39     DESCRIBE,
  40     MODIFY,
  41     INVALID_OPERATION           // LAST
  42   };
  43
  44   /// Human Readable operation name.
  45   static const char * const opname[];
  46
  47   // = Specify how to select offers.
  48   enum ACE_Selection_Criteria
  49   {
  50     NONE = 0,                   // URL that contains none of the properties.
  51     SOME,                       // URL that contains some of the properties.
  52     ALL,                        // URL that contains all of the properties.
  53     INVALID_SELECTION           // Invalid.
  54   };
  55
  56   static const char * const selection_name[];
  57
  58     /// errno will set to one of these value.
  59   enum ACE_URL_Locator_Error
  60   {
  61     OK,                         // Everything is fine.
  62     OFFER_EXIST,                // trying to register an offer.
  63                                 // that is already exist in repository.
  64     NO_SUCH_OFFER,              // No such offer in the repository.
  65     INVALID_ARGUMENT,           // Invalid argument encountered.
  66     UNIMPLEMENTED,              // function not implemented.
  67     UNKNOWN,                    // Unknown error.
  68     MAX_URL_ERROR
  69   };
  70   // Possible error code of URL_Locator.
  71
  72   /// Human readable error status.
  73   static const char * const err_name[];
  74
  75   /// Default destructor.
  76   virtual ~ACE_URL_Locator () = 0;
  77
  78   /**
  79    * Query the locator for HTTP with designate properties (none, some,
  80    * or all).  The locator being queried will return a sequence of
  81    * offers with <how_many> offers in it.  This interface allocates
  82    * <offer> so users must deallocate it after use.
  83    */
  84   virtual int url_query (const ACE_Selection_Criteria how,
  85                          const ACE_URL_Property_Seq *pseq,
  86                          const size_t how_many,
  87                          size_t &num_query,
  88                          ACE_URL_Offer_Seq *offer) = 0;
  89
  90   /// Export an offer to the locator.
  91   virtual int export_offer (ACE_URL_Offer *offer,
  92                             ACE_WString &offer_id) = 0;
  93
  94   /// Withdraw an offer.  return 0 if succeed, -1 otherwise.
  95   virtual int withdraw_offer (const ACE_WString &offer_id) = 0;
  96
  97   /// Query a specific offer.
  98   virtual int describe_offer (const ACE_WString &offer_id,
  99                               ACE_URL_Offer *offer) = 0;
 100
 101   /// Modify a previously registered offer.
 102   virtual int modify_offer (const ACE_WString &offer_id,
 103                             const ACE_WString *url = 0,
 104                             const ACE_URL_Property_Seq *del = 0,
 105                             const ACE_URL_Property_Seq *modify = 0) = 0;
 106
 107   /// Provide a human readable error status.
 108   virtual const char *error_status ();
 109 };
 110
 111 #endif /* ACE_WEB_LOCATOR_H */