chromeos/dbus/ibus/ibus_object.h

   1 // Copyright (c) 2012 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 #ifndef CHROMEOS_DBUS_IBUS_IBUS_OBJECT_H_
   6 #define CHROMEOS_DBUS_IBUS_IBUS_OBJECT_H_
   7
   8 #include <map>
   9 #include <string>
  10
  11 #include "base/basictypes.h"
  12 #include "base/memory/scoped_ptr.h"
  13 #include "chromeos/chromeos_export.h"
  14 #include "chromeos/dbus/ibus/ibus_property.h"
  15 #include "chromeos/dbus/ibus/ibus_text.h"
  16
  17 namespace base {
  18 class Value;
  19 }  // namespace base
  20
  21 namespace dbus {
  22 class MessageReader;
  23 class MessageWriter;
  24 }  // namespace dbus
  25
  26 namespace chromeos {
  27
  28 // The data structure of IBusObject is represented as variant in "(sav...)"
  29 // signature. The IBusObject is constructed with two sections, header and
  30 // contents. The header section is represent as "sav" which contains type name
  31 // and attachment array. The contents section is corresponding to "..." in
  32 // above signature, which can store arbitrary type values including IBusObject.
  33 //
  34 // DATA STRUCTURE OVERVIEW:
  35 //
  36 // variant  // Handle with top_variant_writer_/top_variant_reader_.
  37 //   struct {  // Handle with contents_writer_/contents_reader_.
  38 //     // Header section
  39 //     string typename  // The type name of object, like "IBusText"
  40 //     array [  // attachment array.
  41 //       dict_entry (
  42 //         string "mozc.candidates"  // The key in the dictionary entry.
  43 //         variant ...  // The value in the dictionary entry.
  44 //       )
  45 //       ...
  46 //     ]
  47 //
  48 //     // Contents section
  49 //     ...  // The contents area.
  50 //   }
  51 //
  52 // EXAMPLE: IBusText
  53 //
  54 // variant  struct {
  55 //      string "IBusText"  // Header of IBusText
  56 //      array[]
  57 //      string "A"  // The 1st value of IBusText
  58 //      variant  struct {  // THe 2nd value of IBusText
  59 //          string "IBusAttrList"  // Header of IBusAttrList
  60 //          array[]
  61 //          array[  // The 1st value of IBusAttrList
  62 //            variant  struct{
  63 //                string "IBusAttribute"  // Header of IBusAttribute
  64 //                array[]
  65 //                uint32 1  // The 1st value of IBusAttribute
  66 //                uint32 1  // The 2nd value of IBusAttribute
  67 //                uint32 0  // The 3rd value of IBusAttribute
  68 //                uint32 1  // The 4th value of IBusAttribute
  69 //              }
  70 //          ]
  71 //        }
  72 //   }
  73 //
  74 // The IBusObjectReader class provides reading IBusObject including attachment
  75 // field from dbus message. This class checks the IBusObject header structure
  76 // and type name before reading contents.
  77 //
  78 // EXAPMLE USAGE:
  79 //   // Creates reader for IBusText
  80 //   IBusObjectReader object_reader("IBusText", &reader);
  81 //
  82 //   // Initialize for reading attachment field.
  83 //   object_reader.Init();
  84 //
  85 //   // Get attachment field.
  86 //   base::Value* value = object_reader.GetAttachment("annotation");
  87 //
  88 //   std::string text;
  89 //   reader.PopString(&text);  // Reading 1st value as string.
  90 //
  91 //   // We can also read nested IBusObject.
  92 //   IBusObjectReader nested_object_reader("IBusAttrList", NULL);
  93 //   reader.PopIBusObject(&nested_object_reader);
  94 class CHROMEOS_EXPORT IBusObjectReader {
  95  public:
  96   // |reader| must be released by caller.
  97   IBusObjectReader(const std::string& type_name,
  98                    dbus::MessageReader* reader);
  99   virtual ~IBusObjectReader();
 100
 101   // Reads IBusObject headers and checks if the type name is valid.
 102   // Returns true on success. Uses InitWitAttachmentReader instead if you want
 103   // to read attachment field.
 104   bool Init();
 105
 106   // Reads IBusOBject with |reader| and checks if the type name is valid.
 107   bool InitWithParentReader(dbus::MessageReader* reader);
 108
 109   // Returns true if the IBusObject is valid.
 110   bool IsValid() const;
 111
 112   // The following functions delegate dbus::MessageReader's functions.
 113   bool PopString(std::string* out);
 114   bool PopUint32(uint32* out);
 115   bool PopArray(dbus::MessageReader* reader);
 116   bool PopBool(bool* out);
 117   bool PopInt32(int32* out);
 118   bool HasMoreData();
 119
 120   // Sets up |reader| for reading an IBusObject entry.
 121   bool PopIBusObject(IBusObjectReader* reader);
 122
 123   // Pops a IBusText.
 124   // Returns true on success.
 125   bool PopIBusText(IBusText* text);
 126
 127   // Pops a IBusText and store it's text field into |text|. Use PopIBusText
 128   // instead in the case of using any attribute entries in IBusText.
 129   // Return true on success.
 130   bool PopStringFromIBusText(std::string* text);
 131
 132   // Pops a IBusProperty.
 133   bool PopIBusProperty(IBusProperty* property);
 134
 135   // Pops a IBusPropertyList.
 136   bool PopIBusPropertyList(IBusPropertyList* property_list);
 137
 138   // Gets attachment entry corresponding to |key|. Do not free returned value.
 139   // Returns NULL if there is no entry.
 140   const base::Value* GetAttachment(const std::string& key);
 141
 142  private:
 143   enum CheckResult {
 144     IBUS_OBJECT_VALID,  // Already checked and valid type.
 145     IBUS_OBJECT_INVALID,  // Already checked but invalid type.
 146     IBUS_OBJECT_NOT_CHECKED,  // Not checked yet.
 147   };
 148
 149   std::string type_name_;
 150   dbus::MessageReader* original_reader_;
 151   scoped_ptr<dbus::MessageReader> top_variant_reader_;
 152   scoped_ptr<dbus::MessageReader> contents_reader_;
 153   CheckResult check_result_;
 154   std::map<std::string, base::Value*> attachments_;
 155
 156   DISALLOW_COPY_AND_ASSIGN(IBusObjectReader);
 157 };
 158
 159 // IBusObjectWriter class provides writing IBusObject to dbus message. This
 160 // class appends header section before appending contents values.
 161 // IBusObjectWriter does not support writing attachment field because writing
 162 // attachment field is not used in Chrome.
 163 //
 164 // EXAMPLE USAGE:
 165 //   // Creates writer for IBusText
 166 //   IBusObjectWriter object_writer("IBusText", "sv", &writer);
 167 //
 168 //   // Add some attachments.
 169 //   base::Value* value = base::Value::CreateStringValue("Noun");
 170 //   object_writer.AddAttachment("annotation", *value);
 171 //
 172 //   // Close header section.
 173 //   object_writer.CloseHeader();
 174 //
 175 //   const std::string text = "Sample Text";
 176 //   writer.AppendString(text);
 177 //
 178 //   // We can also write nested IBusObject.
 179 //   IBusObjectWriter nested_object_writer("IBusAttrList", "av");
 180 //   object_writer.AppendIBusObject(&nested_object_writer);
 181 //   ... appends values
 182 //
 183 //   nested_object_writer.CloseAll();  // To finish up, should call CloseAll.
 184 //   object_writer.CloseAll();
 185 class CHROMEOS_EXPORT IBusObjectWriter {
 186  public:
 187   enum WriterState {
 188     NOT_INITIALZED,  // Created but not initialized.
 189     HEADER_OPEN,  // Ready for writing attachment field.
 190     INITIALIZED  // Ready for writing content values.
 191   };
 192
 193   // |writer| must be released by caller.
 194   IBusObjectWriter(const std::string& type_name,
 195                    const std::string& signature,
 196                    dbus::MessageWriter* writer);
 197   virtual ~IBusObjectWriter();
 198
 199   // Closes header to write content values.
 200   void CloseHeader();
 201
 202   // Appends IBusObject headers with |writer|, should be called once.
 203   void InitWithParentWriter(dbus::MessageWriter* writer);
 204
 205   // Adds an attachment, this function can be called only before CloseHeader
 206   // function call.
 207   bool AddAttachment(const std::string& key, const base::Value& value);
 208
 209   // The following functions delegate dbus::MessageReader's functions.
 210   void AppendString(const std::string& input);
 211   void AppendUint32(uint32 value);
 212   void AppendInt32(int32 value);
 213   void AppendBool(bool value);
 214   void OpenArray(const std::string& signature,
 215                  dbus::MessageWriter* writer);
 216   void CloseContainer(dbus::MessageWriter* writer);
 217
 218   // Sets up |writer| for writing new IBusObject entry.
 219   void AppendIBusObject(IBusObjectWriter* writer);
 220
 221   // Closes all opened containers.
 222   void CloseAll();
 223
 224   // Appends a IBusText.
 225   void AppendIBusText(const IBusText& text);
 226
 227   // Appends a string as IBusText without any attributes. Use AppendIBusText
 228   // instead in the case of using any attribute entries.
 229   void AppendStringAsIBusText(const std::string& text);
 230
 231   // Appends a IBusProperty.
 232   void AppendIBusProperty(const IBusProperty& property);
 233
 234   // Appends a IBusPropertyList.
 235   void AppendIBusPropertyList(const IBusPropertyList& property_list);
 236
 237  private:
 238   // Appends IBusObject headers, should be called once.
 239   void Init();
 240
 241   std::string type_name_;
 242   std::string signature_;
 243   dbus::MessageWriter* original_writer_;
 244   WriterState state_;
 245   scoped_ptr<dbus::MessageWriter> top_variant_writer_;
 246   scoped_ptr<dbus::MessageWriter> contents_writer_;
 247   scoped_ptr<dbus::MessageWriter> attachment_writer_;
 248
 249   DISALLOW_COPY_AND_ASSIGN(IBusObjectWriter);
 250 };
 251
 252 }  // namespace chromeos
 253
 254 #endif  // CHROMEOS_DBUS_IBUS_IBUS_OBJECT_H_