src/base/Packable.h

   1 /*
   2  * Copyright (C) 1996-2015 The Squid Software Foundation and contributors
   3  *
   4  * Squid software is distributed under GPLv2+ license and includes
   5  * contributions from numerous individuals and organizations.
   6  * Please see the COPYING and CONTRIBUTORS files for details.
   7  */
   8
   9 #ifndef SQUID_SRC_BASE_PACKABLE_H
  10 #define SQUID_SRC_BASE_PACKABLE_H
  11
  12 /**
  13  * A uniform interface to store-like modules
  14  *
  15  * Rationale:
  16  * ----------
  17  *
  18  * We have two major interfaces Comm and Store, which take a variety of
  19  * different data buffering objects and have different output actions
  20  * to be performed on data.
  21  *
  22  * Store has a nice storeAppend[Printf] capability which makes "storing"
  23  * things easy and painless.
  24  *
  25  * Comm lacks commAppend[Printf] because Comm does not handle its own
  26  * buffers (no mem_obj equivalent for Comm).
  27  *
  28  * Thus, if one wants to be able to Store _and_ Comm::Write an object, 'e
  29  * has to implement almost identical functions for using all the data
  30  * storage objects and their associated actions. Doing this for all the
  31  * available data storage types is a tedious nightmare of almost-duplicated
  32  * code.
  33  *
  34  * Packer
  35  * ------
  36  *
  37  * Objects inheriting from Packable provide a uniform interface for code to
  38  * assemble data before passing to Store and Comm modules.
  39  *
  40  * Packable objects have their own append and printf routines that "know"
  41  * where to send incoming data. In case of Store interface, sending data to
  42  * storeAppend. Packable buffer objects retain the data such that it can be
  43  * flushed later to Comm::Write.
  44  *
  45  * Thus, one can write just one function that will take a Packable object
  46  * and either "pack" things for Comm::Write or "append" things to Store,
  47  * depending on actual Packable object supplied.
  48  */
  49 class Packable
  50 {
  51 public:
  52     /// Appends a c-string to existing packed data.
  53     virtual void append(const char *buf, int size) = 0;
  54
  55     /// Append operation with printf-style arguments.
  56     void appendf(const char *fmt,...) PRINTF_FORMAT_ARG2
  57     {
  58         va_list args;
  59         va_start(args, fmt);
  60         vappendf(fmt, args);
  61         va_end(args);
  62     }
  63
  64     /** Append operation, with vsprintf(3)-style arguments.
  65      *
  66      * \note arguments may be evaluated more than once, be careful
  67      *       of side-effects
  68      */
  69     virtual void vappendf(const char *fmt, va_list ap) = 0;
  70 };
  71
  72 #endif /* SQUID_SRC_BASE_PACKABLE_H */
  73