src/Notes.h

   1 #ifndef SQUID_NOTES_H
   2 #define SQUID_NOTES_H
   3
   4 #include "HttpHeader.h"
   5 #include "HttpHeaderTools.h"
   6 #include "typedefs.h"
   7
   8 #if HAVE_STRING
   9 #include <string>
  10 #endif
  11
  12 class HttpRequest;
  13 class HttpReply;
  14
  15 /**
  16  * Used to store notes. The notes are custom key:value pairs
  17  * ICAP request headers or ECAP options used to pass
  18  * custom transaction-state related meta information to squid
  19  * internal subsystems or to addaptation services.
  20  */
  21 class Note: public RefCountable
  22 {
  23 public:
  24     typedef RefCount<Note> Pointer;
  25     /// Stores a value for the note.
  26     class Value: public RefCountable
  27     {
  28     public:
  29         typedef RefCount<Value> Pointer;
  30         String value; ///< a note value
  31         ACLList *aclList; ///< The access list used to determine if this value is valid for a request
  32         explicit Value(const String &aVal) : value(aVal), aclList(NULL) {}
  33         ~Value();
  34     };
  35     typedef Vector<Value::Pointer> Values;
  36
  37     explicit Note(const String &aKey): key(aKey) {}
  38
  39     /**
  40      * Adds a value to the note and returns a  pointer to the
  41      * related Value object.
  42      */
  43     Value::Pointer addValue(const String &value);
  44
  45     /**
  46      * Walks through the  possible values list of the note and selects
  47      * the first value which matches the given HttpRequest and HttpReply
  48      * or NULL if none matches.
  49      */
  50     const char *match(HttpRequest *request, HttpReply *reply);
  51
  52     /**
  53      * Returns the first value for this key or an empty string.
  54      */
  55     const char *firstValue() const { return (values.size()>0&&values[0]->value.defined()?values[0]->value.termedBuf():""); }
  56
  57     String key; ///< The note key
  58     Values values; ///< The possible values list for the note
  59 };
  60
  61 class ConfigParser;
  62 /**
  63  * Used to store a notes list.
  64  */
  65 class Notes
  66 {
  67 public:
  68     typedef Vector<Note::Pointer> NotesList;
  69     typedef NotesList::iterator iterator; ///< iterates over the notes list
  70     typedef NotesList::const_iterator const_iterator; ///< iterates over the notes list
  71
  72     Notes(const char *aDescr, const char **metasBlacklist): descr(aDescr), blacklisted(metasBlacklist) {}
  73     Notes(): descr(NULL), blacklisted(NULL) {}
  74     ~Notes() { notes.clean(); }
  75     /**
  76      * Parse a notes line and returns a pointer to the
  77      * parsed Note object.
  78      */
  79     Note::Pointer parse(ConfigParser &parser);
  80     /**
  81      * Dump the notes list to the given StoreEntry object.
  82      */
  83     void dump(StoreEntry *entry, const char *name);
  84     void clean(); /// clean the notes list
  85
  86     /// points to the first argument
  87     iterator begin() { return notes.begin(); }
  88     /// points to the end of list
  89     iterator end() { return notes.end(); }
  90     /// return true if the notes list is empty
  91     bool empty() { return notes.empty(); }
  92
  93     /**
  94      * Adds a note key and value to the notes list.
  95      * If the key name already exists in list, add the given value to its set of values.
  96      */
  97     void add(const String &noteKey, const String &noteValue);
  98
  99     /**
 100      * Adds a set of notes from another notes list to this set.
 101      * Creating entries for any new keys needed.
 102      * If the key name already exists in list, add the given value to its set of values.
 103      *
 104      * WARNING:
 105      * The list entries are all of shared Pointer type. Altering the src object(s) after
 106      * using this function will update both Notes lists. Likewise, altering this
 107      * destination NotesList will affect any relevant copies of src still in use.
 108      */
 109     void add(const Notes &src);
 110
 111     /**
 112      * Returns a pointer to an existing Note with given key name or nil.
 113      */
 114     Note::Pointer find(const String &noteKey) const;
 115
 116     NotesList notes; ///< The Note::Pointer objects array list
 117     const char *descr; ///< A short description for notes list
 118     const char **blacklisted; ///< Null terminated list of blacklisted note keys
 119
 120 private:
 121     /**
 122      * Adds a note to the notes list and returns a pointer to the
 123      * related Note object. If the note key already exists in list,
 124      * returns a pointer to the existing object.
 125      */
 126     Note::Pointer add(const String &noteKey);
 127 };
 128
 129 class NotePairs : public HttpHeader
 130 {
 131 public:
 132     NotePairs() : HttpHeader(hoNote) {}
 133
 134     /// convert a NotesList into a NotesPairs
 135     /// appending to any existing entries already present
 136     void append(const Notes::NotesList &src) {
 137         for (Notes::NotesList::const_iterator m = src.begin(); m != src.end(); ++m)
 138             for (Note::Values::iterator v =(*m)->values.begin(); v != (*m)->values.end(); ++v)
 139                 putExt((*m)->key.termedBuf(), (*v)->value.termedBuf());
 140     }
 141
 142     void append(const NotePairs *src) {
 143         HttpHeader::append(dynamic_cast<const HttpHeader*>(src));
 144     }
 145 };
 146
 147 #endif