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         DDF& string(long val);
  82         DDF& string(double val);
  83         DDF& integer(long val);
  84         DDF& integer(const char* val);
  85         DDF& floating(double val);
  86         DDF& floating(const char* val);
  87         DDF& structure();
  88         DDF& list();
  89         DDF& pointer(void* val);
  90
  91         // list/struct methods
  92         DDF& add(DDF& child);
  93         DDF& addbefore(DDF& child, DDF& before);
  94         DDF& addafter(DDF& child, DDF& after);
  95         void swap(DDF& arg);
  96         DDF& remove();
  97
  98         // C-style iterators
  99         DDF parent() const;
 100         DDF first();
 101         DDF next();
 102         DDF last();
 103         DDF previous();
 104
 105         // indexed operators
 106         DDF operator[](unsigned long index) const;
 107         DDF operator[](const char* path) const { return getmember(path); }
 108
 109         // named member access/creation
 110         DDF addmember(const char* path);
 111         DDF getmember(const char* path) const;
 112
 113         // debugging
 114         void dump(FILE* f=NULL, int indent=0) const;
 115
 116         // serialization functions need private access
 117         friend SHIBSP_API std::ostream& operator<<(std::ostream& os, const DDF& obj);
 118         friend SHIBSP_API std::istream& operator>>(std::istream& is, DDF& obj);
 119         /// @endcond
 120     private:
 121         struct ddf_body_t* m_handle;
 122     };
 123
 124     /**
 125      * Serializes a DDF object to a stream.
 126      *
 127      * @param os    output stream
 128      * @param obj   DDF object to serialize
 129      * @return reference to the output stream
 130      */
 131     SHIBSP_API std::ostream& operator<<(std::ostream& os, const DDF& obj);
 132
 133     /**
 134      * Reconstitutes a DDF object from a stream.
 135      *
 136      * @param is    input stream
 137      * @param obj   DDF object to reconstitute
 138      * @return reference to the input stream
 139      */
 140     SHIBSP_API std::istream& operator>>(std::istream& is, DDF& obj);
 141
 142     /**
 143      * A "smart pointer" for disposing of DDF objects when they leave scope.
 144      */
 145     class SHIBSP_API DDFJanitor
 146     {
 147     public:
 148         DDFJanitor(DDF& obj) : m_obj(obj) {}
 149         ~DDFJanitor() { m_obj.destroy(); }
 150     private:
 151         DDF& m_obj;
 152         DDFJanitor(const DDFJanitor&);
 153         DDFJanitor& operator=(const DDFJanitor&);
 154     };
 155
 156 }
 157
 158 #endif // __ddf_h__