shibsp/remoting/ddf.h

   1 /**
   2  * Licensed to the University Corporation for Advanced Internet
   3  * Development, Inc. (UCAID) under one or more contributor license
   4  * agreements. See the NOTICE file distributed with this work for
   5  * additional information regarding copyright ownership.
   6  *
   7  * UCAID licenses this file to you under the Apache License,
   8  * Version 2.0 (the "License"); you may not use this file except
   9  * in compliance with the License. You may obtain a copy of the
  10  * License at
  11  *
  12  * http://www.apache.org/licenses/LICENSE-2.0
  13  *
  14  * Unless required by applicable law or agreed to in writing,
  15  * software distributed under the License is distributed on an
  16  * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
  17  * either express or implied. See the License for the specific
  18  * language governing permissions and limitations under the License.
  19  */
  20
  21 /**
  22  * @file shibsp/remoting/ddf.h
  23  *
  24  * C++ DDF abstraction for interpretive RPC
  25  */
  26
  27 #ifndef __ddf_h__
  28 #define __ddf_h__
  29
  30 #include <shibsp/base.h>
  31
  32 #include <cstdio>
  33 #include <iostream>
  34
  35 namespace shibsp {
  36
  37     /**
  38      * DDF objects are implemented with a handle-body idiom and require explicit
  39      * destruction in order to allow stack objects to be freely mixed in structures
  40      * with heap objects. When stack objects leave scope, only the handle is freed.
  41      * Copying and assigning handle objects is a constant time operation equivalent
  42      * to a single pointer assignment, handled by compiler-generated behavior.
  43      */
  44     class SHIBSP_API DDF
  45     {
  46     public:
  47         /// @cond OFF
  48         // constructors
  49         DDF();
  50         DDF(const char* n);
  51         DDF(const char* n, const char* val, bool safe=true);
  52         DDF(const char* n, long val);
  53         DDF(const char* n, double val);
  54         DDF(const char* n, void* val);
  55
  56         DDF& destroy();         // deep destructor
  57         DDF copy() const;       // deep copy routine
  58
  59         // property accessors
  60         const char* name() const;           DDF& name(const char* n);
  61
  62         // basic type checking
  63         bool isnull() const;
  64         bool isempty() const;
  65         bool isstring() const;
  66         bool isint() const;
  67         bool isfloat() const;
  68         bool isstruct() const;
  69         bool islist() const;
  70         bool ispointer() const;
  71
  72         // type conversion and value extraction
  73         const char* string() const;     // legal for str
  74         long        integer() const;    // legal for all types
  75         double      floating() const;   // legal for float
  76         void*       pointer() const;    // legal for pointer
  77
  78         // string helper methods
  79         size_t strlen() const;
  80         bool operator==(const char* s) const;
  81
  82         // destructive node conversion methods
  83         DDF& empty();
  84         DDF& string(char* val, bool copyit=true, bool safe=true);
  85         DDF& string(const char* val);
  86         DDF& unsafe_string(const char* val);
  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;
 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=nullptr, 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__