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