shibsp/remoting/ddf.h

   1 /*
   2  *  Copyright 2001-2007 Internet2
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  *     http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17 /**
  18  * @file shibsp/remoting/ddf.h
  19  *
  20  * C++ DDF abstraction for interpretive RPC
  21  */
  22
  23 #ifndef __ddf_h__
  24 #define __ddf_h__
  25
  26 #include <shibsp/base.h>
  27
  28 #include <cstdio>
  29 #include <iostream>
  30
  31 namespace shibsp {
  32
  33     /**
  34      * DDF objects are implemented with a handle-body idiom and require explicit
  35      * destruction in order to allow stack objects to be freely mixed in structures
  36      * with heap objects. When stack objects leave scope, only the handle is freed.
  37      * Copying and assigning handle objects is a constant time operation equivalent
  38      * to a single pointer assignment, handled by compiler-generated behavior.
  39      */
  40     class SHIBSP_API DDF
  41     {
  42     public:
  43         /// @cond OFF
  44         // constructors
  45         DDF() : m_handle(NULL) {}
  46         DDF(const char* n);
  47         DDF(const char* n, const char* val);
  48         DDF(const char* n, long val);
  49         DDF(const char* n, double val);
  50         DDF(const char* n, void* val);
  51
  52         DDF& destroy();         // deep destructor
  53         DDF copy() const;       // deep copy routine
  54
  55         // property accessors
  56         const char* name() const;           DDF& name(const char* n);
  57
  58         // basic type checking
  59         bool isnull() const;
  60         bool isempty() const;
  61         bool isstring() const;
  62         bool isint() const;
  63         bool isfloat() const;
  64         bool isstruct() const;
  65         bool islist() const;
  66         bool ispointer() const;
  67
  68         // type conversion and value extraction
  69         const char* string() const;     // legal for str
  70         long        integer() const;    // legal for all types
  71         double      floating() const;   // legal for float
  72         void*       pointer() const;    // legal for pointer
  73
  74         // string helper methods
  75         size_t strlen() const;
  76         bool operator==(const char* s) const;
  77
  78         // destructive node conversion methods
  79         DDF& empty();
  80         DDF& string(const char* val) {
  81             return string(const_cast<char*>(val), true);
  82         }
  83         DDF& string(char* val, bool copyit=true);
  84         DDF& string(long val);
  85         DDF& string(double val);
  86         DDF& integer(long val);
  87         DDF& integer(const char* val);
  88         DDF& floating(double val);
  89         DDF& floating(const char* val);
  90         DDF& structure();
  91         DDF& list();
  92         DDF& pointer(void* val);
  93
  94         // list/struct methods
  95         DDF& add(DDF& child);
  96         DDF& addbefore(DDF& child, DDF& before);
  97         DDF& addafter(DDF& child, DDF& after);
  98         void swap(DDF& arg);
  99         DDF& remove();
 100
 101         // C-style iterators
 102         DDF parent() const;
 103         DDF first();
 104         DDF next();
 105         DDF last();
 106         DDF previous();
 107
 108         // indexed operators
 109         DDF operator[](unsigned long index) const;
 110         DDF operator[](const char* path) const { return getmember(path); }
 111
 112         // named member access/creation
 113         DDF addmember(const char* path);
 114         DDF getmember(const char* path) const;
 115
 116         // debugging
 117         void dump(FILE* f=NULL, int indent=0) const;
 118
 119         // serialization functions need private access
 120         friend SHIBSP_API std::ostream& operator<<(std::ostream& os, const DDF& obj);
 121         friend SHIBSP_API std::istream& operator>>(std::istream& is, DDF& obj);
 122         /// @endcond
 123     private:
 124         struct ddf_body_t* m_handle;
 125     };
 126
 127     /**
 128      * Serializes a DDF object to a stream.
 129      *
 130      * @param os    output stream
 131      * @param obj   DDF object to serialize
 132      * @return reference to the output stream
 133      */
 134     SHIBSP_API std::ostream& operator<<(std::ostream& os, const DDF& obj);
 135
 136     /**
 137      * Reconstitutes a DDF object from a stream.
 138      *
 139      * @param is    input stream
 140      * @param obj   DDF object to reconstitute
 141      * @return reference to the input stream
 142      */
 143     SHIBSP_API std::istream& operator>>(std::istream& is, DDF& obj);
 144
 145     /**
 146      * A "smart pointer" for disposing of DDF objects when they leave scope.
 147      */
 148     class SHIBSP_API DDFJanitor
 149     {
 150     public:
 151         DDFJanitor(DDF& obj) : m_obj(obj) {}
 152         ~DDFJanitor() { m_obj.destroy(); }
 153     private:
 154         DDF& m_obj;
 155         DDFJanitor(const DDFJanitor&);
 156         DDFJanitor& operator=(const DDFJanitor&);
 157     };
 158
 159 }
 160
 161 #endif // __ddf_h__