shibsp/remoting/ddf.h

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