src/Notes.h

   1 #ifndef SQUID_NOTES_H
   2 #define SQUID_NOTES_H
   3
   4 #include "acl/forward.h"
   5 #include "base/RefCount.h"
   6 #include "CbDataList.h"
   7 #include "format/Format.h"
   8 #include "MemPool.h"
   9 #include "SquidString.h"
  10 #include "typedefs.h"
  11
  12 #if HAVE_STRING
  13 #include <string>
  14 #endif
  15 #include <vector>
  16
  17 class HttpRequest;
  18 class HttpReply;
  19 typedef RefCount<AccessLogEntry> AccessLogEntryPointer;
  20
  21 /**
  22  * Used to store a note configuration. The notes are custom key:value
  23  * pairs ICAP request headers or ECAP options used to pass
  24  * custom transaction-state related meta information to squid
  25  * internal subsystems or to adaptation services.
  26  */
  27 class Note: public RefCountable
  28 {
  29 public:
  30     typedef RefCount<Note> Pointer;
  31     /// Stores a value for the note.
  32     class Value: public RefCountable
  33     {
  34     public:
  35         typedef RefCount<Value> Pointer;
  36         String value; ///< Configured annotation value, possibly with %macros
  37         ACLList *aclList; ///< The access list used to determine if this value is valid for a request
  38         /// Compiled annotation value format
  39         Format::Format *valueFormat;
  40         explicit Value(const String &aVal) : value(aVal), aclList(NULL), valueFormat(NULL) {}
  41         ~Value();
  42     };
  43     typedef std::vector<Value::Pointer> Values;
  44
  45     explicit Note(const String &aKey): key(aKey) {}
  46
  47     /**
  48      * Adds a value to the note and returns a  pointer to the
  49      * related Value object.
  50      */
  51     Value::Pointer addValue(const String &value);
  52
  53     /**
  54      * Walks through the  possible values list of the note and selects
  55      * the first value which matches the given HttpRequest and HttpReply
  56      * or NULL if none matches.
  57      * If an AccessLogEntry given and Value::valueFormat is not null, the
  58      * formatted value returned.
  59      */
  60     const char *match(HttpRequest *request, HttpReply *reply, const AccessLogEntryPointer &al);
  61
  62     String key; ///< The note key
  63     Values values; ///< The possible values list for the note
  64 };
  65
  66 class ConfigParser;
  67 /**
  68  * Used to store a notes configuration list.
  69  */
  70 class Notes
  71 {
  72 public:
  73     typedef std::vector<Note::Pointer> NotesList;
  74     typedef NotesList::iterator iterator; ///< iterates over the notes list
  75     typedef NotesList::const_iterator const_iterator; ///< iterates over the notes list
  76
  77     Notes(const char *aDescr, const char **metasBlacklist, bool allowFormatted = false): descr(aDescr), blacklisted(metasBlacklist), formattedValues(allowFormatted) {}
  78     Notes(): descr(NULL), blacklisted(NULL) {}
  79     ~Notes() { notes.clear(); }
  80     /**
  81      * Parse a notes line and returns a pointer to the
  82      * parsed Note object.
  83      */
  84     Note::Pointer parse(ConfigParser &parser);
  85     /**
  86      * Dump the notes list to the given StoreEntry object.
  87      */
  88     void dump(StoreEntry *entry, const char *name);
  89     void clean(); /// clean the notes list
  90
  91     /// points to the first argument
  92     iterator begin() { return notes.begin(); }
  93     /// points to the end of list
  94     iterator end() { return notes.end(); }
  95     /// return true if the notes list is empty
  96     bool empty() { return notes.empty(); }
  97
  98     NotesList notes; ///< The Note::Pointer objects array list
  99     const char *descr; ///< A short description for notes list
 100     const char **blacklisted; ///< Null terminated list of blacklisted note keys
 101     bool formattedValues; ///< Whether the formatted values are supported
 102
 103 private:
 104     /**
 105      * Adds a note to the notes list and returns a pointer to the
 106      * related Note object. If the note key already exists in list,
 107      * returns a pointer to the existing object.
 108      */
 109     Note::Pointer add(const String &noteKey);
 110 };
 111
 112 /**
 113  * Used to store list of notes
 114  */
 115 class NotePairs: public RefCountable
 116 {
 117 public:
 118     typedef RefCount<NotePairs> Pointer;
 119
 120     /**
 121      * Used to store a note key/value pair.
 122      */
 123     class Entry
 124     {
 125     public:
 126         Entry(const char *aKey, const char *aValue): name(aKey), value(aValue) {}
 127         String name;
 128         String value;
 129         MEMPROXY_CLASS(Entry);
 130     };
 131
 132     NotePairs() {}
 133     ~NotePairs();
 134
 135     /**
 136      * Append the entries of the src NotePairs list to our list.
 137      */
 138     void append(const NotePairs *src);
 139
 140     /**
 141      * Append any new entries of the src NotePairs list to our list.
 142      * Entries which already exist in the destination set are ignored.
 143      */
 144     void appendNewOnly(const NotePairs *src);
 145
 146     /**
 147      * Returns a comma separated list of notes with key 'noteKey'.
 148      * Use findFirst instead when a unique kv-pair is needed.
 149      */
 150     const char *find(const char *noteKey) const;
 151
 152     /**
 153      * Returns the first note value for this key or an empty string.
 154      */
 155     const char *findFirst(const char *noteKey) const;
 156
 157     /**
 158      * Adds a note key and value to the notes list.
 159      * If the key name already exists in list, add the given value to its set
 160      * of values.
 161      */
 162     void add(const char *key, const char *value);
 163
 164     /**
 165      * Adds a note key and values strList to the notes list.
 166      * If the key name already exists in list, add the new values to its set
 167      * of values.
 168      */
 169     void addStrList(const char *key, const char *values);
 170
 171     /**
 172      * Return true if the key/value pair is already stored
 173      */
 174     bool hasPair(const char *key, const char *value) const;
 175
 176     /**
 177      * Convert NotePairs list to a string consist of "Key: Value"
 178      * entries separated by sep string.
 179      */
 180     const char *toString(const char *sep = "\r\n") const;
 181
 182     /**
 183      * True if there are not entries in the list
 184      */
 185     bool empty() const {return entries.empty();}
 186
 187     std::vector<NotePairs::Entry *> entries;      ///< The key/value pair entries
 188
 189 private:
 190     NotePairs &operator = (NotePairs const &); // Not implemented
 191     NotePairs(NotePairs const &); // Not implemented
 192 };
 193
 194 MEMPROXY_CLASS_INLINE(NotePairs::Entry);
 195
 196 class AccessLogEntry;
 197 /**
 198  * Keep in sync HttpRequest and the corresponding AccessLogEntry objects
 199  */
 200 NotePairs &SyncNotes(AccessLogEntry &ale, HttpRequest &request);
 201
 202 #endif