1 // Copyright (c) 2012 Marshall A. Greenblatt. All rights reserved.
3 // Redistribution and use in source and binary forms, with or without
4 // modification, are permitted provided that the following conditions are
7 // * Redistributions of source code must retain the above copyright
8 // notice, this list of conditions and the following disclaimer.
9 // * Redistributions in binary form must reproduce the above
10 // copyright notice, this list of conditions and the following disclaimer
11 // in the documentation and/or other materials provided with the
13 // * Neither the name of Google Inc. nor the name Chromium Embedded
14 // Framework nor the names of its contributors may be used to endorse
15 // or promote products derived from this software without specific prior
16 // written permission.
18 // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
19 // "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
20 // LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
21 // A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
22 // OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
23 // SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
24 // LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
25 // DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
26 // THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
27 // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
28 // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
30 // ---------------------------------------------------------------------------
32 // The contents of this file must follow a specific format in order to
33 // support the CEF translator tool. See the translator.README.txt file in the
34 // tools directory for more information.
37 #ifndef CEF_INCLUDE_CEF_VALUES_H_
38 #define CEF_INCLUDE_CEF_VALUES_H_
42 #include "include/cef_base.h"
45 class CefDictionaryValue;
48 typedef cef_value_type_t CefValueType;
51 // Class that wraps other data value types. Complex types (binary, dictionary
52 // and list) will be referenced but not owned by this object. Can be used on any
53 // process and thread.
55 /*--cef(source=library)--*/
56 class CefValue : public virtual CefBase {
59 // Creates a new object.
62 static CefRefPtr<CefValue> Create();
65 // Returns true if the underlying data is valid. This will always be true for
66 // simple types. For complex types (binary, dictionary and list) the
67 // underlying data may become invalid if owned by another object (e.g. list or
68 // dictionary) and that other object is then modified or destroyed. This value
69 // object can be re-used by calling Set*() even if the underlying data is
73 virtual bool IsValid() =0;
76 // Returns true if the underlying data is owned by another object.
79 virtual bool IsOwned() =0;
82 // Returns true if the underlying data is read-only. Some APIs may expose
86 virtual bool IsReadOnly() =0;
89 // Returns true if this object and |that| object have the same underlying
90 // data. If true modifications to this object will also affect |that| object
94 virtual bool IsSame(CefRefPtr<CefValue> that) =0;
97 // Returns true if this object and |that| object have an equivalent underlying
98 // value but are not necessarily the same object.
101 virtual bool IsEqual(CefRefPtr<CefValue> that) =0;
104 // Returns a copy of this object. The underlying data will also be copied.
107 virtual CefRefPtr<CefValue> Copy() =0;
110 // Returns the underlying value type.
112 /*--cef(default_retval=VTYPE_INVALID)--*/
113 virtual CefValueType GetType() =0;
116 // Returns the underlying value as type bool.
119 virtual bool GetBool() =0;
122 // Returns the underlying value as type int.
125 virtual int GetInt() =0;
128 // Returns the underlying value as type double.
131 virtual double GetDouble() =0;
134 // Returns the underlying value as type string.
137 virtual CefString GetString() =0;
140 // Returns the underlying value as type binary. The returned reference may
141 // become invalid if the value is owned by another object or if ownership is
142 // transferred to another object in the future. To maintain a reference to
143 // the value after assigning ownership to a dictionary or list pass this
144 // object to the SetValue() method instead of passing the returned reference
148 virtual CefRefPtr<CefBinaryValue> GetBinary() =0;
151 // Returns the underlying value as type dictionary. The returned reference may
152 // become invalid if the value is owned by another object or if ownership is
153 // transferred to another object in the future. To maintain a reference to
154 // the value after assigning ownership to a dictionary or list pass this
155 // object to the SetValue() method instead of passing the returned reference
156 // to SetDictionary().
159 virtual CefRefPtr<CefDictionaryValue> GetDictionary() =0;
162 // Returns the underlying value as type list. The returned reference may
163 // become invalid if the value is owned by another object or if ownership is
164 // transferred to another object in the future. To maintain a reference to
165 // the value after assigning ownership to a dictionary or list pass this
166 // object to the SetValue() method instead of passing the returned reference
170 virtual CefRefPtr<CefListValue> GetList() =0;
173 // Sets the underlying value as type null. Returns true if the value was set
177 virtual bool SetNull() =0;
180 // Sets the underlying value as type bool. Returns true if the value was set
184 virtual bool SetBool(bool value) =0;
187 // Sets the underlying value as type int. Returns true if the value was set
191 virtual bool SetInt(int value) =0;
194 // Sets the underlying value as type double. Returns true if the value was set
198 virtual bool SetDouble(double value) =0;
201 // Sets the underlying value as type string. Returns true if the value was set
204 /*--cef(optional_param=value)--*/
205 virtual bool SetString(const CefString& value) =0;
208 // Sets the underlying value as type binary. Returns true if the value was set
209 // successfully. This object keeps a reference to |value| and ownership of the
210 // underlying data remains unchanged.
213 virtual bool SetBinary(CefRefPtr<CefBinaryValue> value) =0;
216 // Sets the underlying value as type dict. Returns true if the value was set
217 // successfully. This object keeps a reference to |value| and ownership of the
218 // underlying data remains unchanged.
221 virtual bool SetDictionary(CefRefPtr<CefDictionaryValue> value) =0;
224 // Sets the underlying value as type list. Returns true if the value was set
225 // successfully. This object keeps a reference to |value| and ownership of the
226 // underlying data remains unchanged.
229 virtual bool SetList(CefRefPtr<CefListValue> value) =0;
234 // Class representing a binary value. Can be used on any process and thread.
236 /*--cef(source=library)--*/
237 class CefBinaryValue : public virtual CefBase {
240 // Creates a new object that is not owned by any other object. The specified
241 // |data| will be copied.
244 static CefRefPtr<CefBinaryValue> Create(const void* data,
248 // Returns true if this object is valid. This object may become invalid if
249 // the underlying data is owned by another object (e.g. list or dictionary)
250 // and that other object is then modified or destroyed. Do not call any other
251 // methods if this method returns false.
254 virtual bool IsValid() =0;
257 // Returns true if this object is currently owned by another object.
260 virtual bool IsOwned() =0;
263 // Returns true if this object and |that| object have the same underlying
267 virtual bool IsSame(CefRefPtr<CefBinaryValue> that) =0;
270 // Returns true if this object and |that| object have an equivalent underlying
271 // value but are not necessarily the same object.
274 virtual bool IsEqual(CefRefPtr<CefBinaryValue> that) =0;
277 // Returns a copy of this object. The data in this object will also be copied.
280 virtual CefRefPtr<CefBinaryValue> Copy() =0;
283 // Returns the data size.
286 virtual size_t GetSize() =0;
289 // Read up to |buffer_size| number of bytes into |buffer|. Reading begins at
290 // the specified byte |data_offset|. Returns the number of bytes read.
293 virtual size_t GetData(void* buffer,
295 size_t data_offset) =0;
300 // Class representing a dictionary value. Can be used on any process and thread.
302 /*--cef(source=library)--*/
303 class CefDictionaryValue : public virtual CefBase {
305 typedef std::vector<CefString> KeyList;
308 // Creates a new object that is not owned by any other object.
311 static CefRefPtr<CefDictionaryValue> Create();
314 // Returns true if this object is valid. This object may become invalid if
315 // the underlying data is owned by another object (e.g. list or dictionary)
316 // and that other object is then modified or destroyed. Do not call any other
317 // methods if this method returns false.
320 virtual bool IsValid() =0;
323 // Returns true if this object is currently owned by another object.
326 virtual bool IsOwned() =0;
329 // Returns true if the values of this object are read-only. Some APIs may
330 // expose read-only objects.
333 virtual bool IsReadOnly() =0;
336 // Returns true if this object and |that| object have the same underlying
337 // data. If true modifications to this object will also affect |that| object
341 virtual bool IsSame(CefRefPtr<CefDictionaryValue> that) =0;
344 // Returns true if this object and |that| object have an equivalent underlying
345 // value but are not necessarily the same object.
348 virtual bool IsEqual(CefRefPtr<CefDictionaryValue> that) =0;
351 // Returns a writable copy of this object. If |exclude_empty_children| is true
352 // any empty dictionaries or lists will be excluded from the copy.
355 virtual CefRefPtr<CefDictionaryValue> Copy(bool exclude_empty_children) =0;
358 // Returns the number of values.
361 virtual size_t GetSize() =0;
364 // Removes all values. Returns true on success.
367 virtual bool Clear() =0;
370 // Returns true if the current dictionary has a value for the given key.
373 virtual bool HasKey(const CefString& key) =0;
376 // Reads all keys for this dictionary into the specified vector.
379 virtual bool GetKeys(KeyList& keys) =0;
382 // Removes the value at the specified key. Returns true is the value was
383 // removed successfully.
386 virtual bool Remove(const CefString& key) =0;
389 // Returns the value type for the specified key.
391 /*--cef(default_retval=VTYPE_INVALID)--*/
392 virtual CefValueType GetType(const CefString& key) =0;
395 // Returns the value at the specified key. For simple types the returned
396 // value will copy existing data and modifications to the value will not
397 // modify this object. For complex types (binary, dictionary and list) the
398 // returned value will reference existing data and modifications to the value
399 // will modify this object.
402 virtual CefRefPtr<CefValue> GetValue(const CefString& key) =0;
405 // Returns the value at the specified key as type bool.
408 virtual bool GetBool(const CefString& key) =0;
411 // Returns the value at the specified key as type int.
414 virtual int GetInt(const CefString& key) =0;
417 // Returns the value at the specified key as type double.
420 virtual double GetDouble(const CefString& key) =0;
423 // Returns the value at the specified key as type string.
426 virtual CefString GetString(const CefString& key) =0;
429 // Returns the value at the specified key as type binary. The returned
430 // value will reference existing data.
433 virtual CefRefPtr<CefBinaryValue> GetBinary(const CefString& key) =0;
436 // Returns the value at the specified key as type dictionary. The returned
437 // value will reference existing data and modifications to the value will
438 // modify this object.
441 virtual CefRefPtr<CefDictionaryValue> GetDictionary(const CefString& key) =0;
444 // Returns the value at the specified key as type list. The returned value
445 // will reference existing data and modifications to the value will modify
449 virtual CefRefPtr<CefListValue> GetList(const CefString& key) =0;
452 // Sets the value at the specified key. Returns true if the value was set
453 // successfully. If |value| represents simple data then the underlying data
454 // will be copied and modifications to |value| will not modify this object. If
455 // |value| represents complex data (binary, dictionary or list) then the
456 // underlying data will be referenced and modifications to |value| will modify
460 virtual bool SetValue(const CefString& key, CefRefPtr<CefValue> value) =0;
463 // Sets the value at the specified key as type null. Returns true if the
464 // value was set successfully.
467 virtual bool SetNull(const CefString& key) =0;
470 // Sets the value at the specified key as type bool. Returns true if the
471 // value was set successfully.
474 virtual bool SetBool(const CefString& key, bool value) =0;
477 // Sets the value at the specified key as type int. Returns true if the
478 // value was set successfully.
481 virtual bool SetInt(const CefString& key, int value) =0;
484 // Sets the value at the specified key as type double. Returns true if the
485 // value was set successfully.
488 virtual bool SetDouble(const CefString& key, double value) =0;
491 // Sets the value at the specified key as type string. Returns true if the
492 // value was set successfully.
494 /*--cef(optional_param=value)--*/
495 virtual bool SetString(const CefString& key, const CefString& value) =0;
498 // Sets the value at the specified key as type binary. Returns true if the
499 // value was set successfully. If |value| is currently owned by another object
500 // then the value will be copied and the |value| reference will not change.
501 // Otherwise, ownership will be transferred to this object and the |value|
502 // reference will be invalidated.
505 virtual bool SetBinary(const CefString& key,
506 CefRefPtr<CefBinaryValue> value) =0;
509 // Sets the value at the specified key as type dict. Returns true if the
510 // value was set successfully. If |value| is currently owned by another object
511 // then the value will be copied and the |value| reference will not change.
512 // Otherwise, ownership will be transferred to this object and the |value|
513 // reference will be invalidated.
516 virtual bool SetDictionary(const CefString& key,
517 CefRefPtr<CefDictionaryValue> value) =0;
520 // Sets the value at the specified key as type list. Returns true if the
521 // value was set successfully. If |value| is currently owned by another object
522 // then the value will be copied and the |value| reference will not change.
523 // Otherwise, ownership will be transferred to this object and the |value|
524 // reference will be invalidated.
527 virtual bool SetList(const CefString& key,
528 CefRefPtr<CefListValue> value) =0;
533 // Class representing a list value. Can be used on any process and thread.
535 /*--cef(source=library)--*/
536 class CefListValue : public virtual CefBase {
539 // Creates a new object that is not owned by any other object.
542 static CefRefPtr<CefListValue> Create();
545 // Returns true if this object is valid. This object may become invalid if
546 // the underlying data is owned by another object (e.g. list or dictionary)
547 // and that other object is then modified or destroyed. Do not call any other
548 // methods if this method returns false.
551 virtual bool IsValid() =0;
554 // Returns true if this object is currently owned by another object.
557 virtual bool IsOwned() =0;
560 // Returns true if the values of this object are read-only. Some APIs may
561 // expose read-only objects.
564 virtual bool IsReadOnly() =0;
567 // Returns true if this object and |that| object have the same underlying
568 // data. If true modifications to this object will also affect |that| object
572 virtual bool IsSame(CefRefPtr<CefListValue> that) =0;
575 // Returns true if this object and |that| object have an equivalent underlying
576 // value but are not necessarily the same object.
579 virtual bool IsEqual(CefRefPtr<CefListValue> that) =0;
582 // Returns a writable copy of this object.
585 virtual CefRefPtr<CefListValue> Copy() =0;
588 // Sets the number of values. If the number of values is expanded all
589 // new value slots will default to type null. Returns true on success.
592 virtual bool SetSize(size_t size) =0;
595 // Returns the number of values.
598 virtual size_t GetSize() =0;
601 // Removes all values. Returns true on success.
604 virtual bool Clear() =0;
607 // Removes the value at the specified index.
609 /*--cef(index_param=index)--*/
610 virtual bool Remove(int index) =0;
613 // Returns the value type at the specified index.
615 /*--cef(default_retval=VTYPE_INVALID,index_param=index)--*/
616 virtual CefValueType GetType(int index) =0;
619 // Returns the value at the specified index. For simple types the returned
620 // value will copy existing data and modifications to the value will not
621 // modify this object. For complex types (binary, dictionary and list) the
622 // returned value will reference existing data and modifications to the value
623 // will modify this object.
625 /*--cef(index_param=index)--*/
626 virtual CefRefPtr<CefValue> GetValue(int index) =0;
629 // Returns the value at the specified index as type bool.
631 /*--cef(index_param=index)--*/
632 virtual bool GetBool(int index) =0;
635 // Returns the value at the specified index as type int.
637 /*--cef(index_param=index)--*/
638 virtual int GetInt(int index) =0;
641 // Returns the value at the specified index as type double.
643 /*--cef(index_param=index)--*/
644 virtual double GetDouble(int index) =0;
647 // Returns the value at the specified index as type string.
649 /*--cef(index_param=index)--*/
650 virtual CefString GetString(int index) =0;
653 // Returns the value at the specified index as type binary. The returned
654 // value will reference existing data.
656 /*--cef(index_param=index)--*/
657 virtual CefRefPtr<CefBinaryValue> GetBinary(int index) =0;
660 // Returns the value at the specified index as type dictionary. The returned
661 // value will reference existing data and modifications to the value will
662 // modify this object.
664 /*--cef(index_param=index)--*/
665 virtual CefRefPtr<CefDictionaryValue> GetDictionary(int index) =0;
668 // Returns the value at the specified index as type list. The returned
669 // value will reference existing data and modifications to the value will
670 // modify this object.
672 /*--cef(index_param=index)--*/
673 virtual CefRefPtr<CefListValue> GetList(int index) =0;
676 // Sets the value at the specified index. Returns true if the value was set
677 // successfully. If |value| represents simple data then the underlying data
678 // will be copied and modifications to |value| will not modify this object. If
679 // |value| represents complex data (binary, dictionary or list) then the
680 // underlying data will be referenced and modifications to |value| will modify
683 /*--cef(index_param=index)--*/
684 virtual bool SetValue(int index, CefRefPtr<CefValue> value) =0;
687 // Sets the value at the specified index as type null. Returns true if the
688 // value was set successfully.
690 /*--cef(index_param=index)--*/
691 virtual bool SetNull(int index) =0;
694 // Sets the value at the specified index as type bool. Returns true if the
695 // value was set successfully.
697 /*--cef(index_param=index)--*/
698 virtual bool SetBool(int index, bool value) =0;
701 // Sets the value at the specified index as type int. Returns true if the
702 // value was set successfully.
704 /*--cef(index_param=index)--*/
705 virtual bool SetInt(int index, int value) =0;
708 // Sets the value at the specified index as type double. Returns true if the
709 // value was set successfully.
711 /*--cef(index_param=index)--*/
712 virtual bool SetDouble(int index, double value) =0;
715 // Sets the value at the specified index as type string. Returns true if the
716 // value was set successfully.
718 /*--cef(optional_param=value,index_param=index)--*/
719 virtual bool SetString(int index, const CefString& value) =0;
722 // Sets the value at the specified index as type binary. Returns true if the
723 // value was set successfully. If |value| is currently owned by another object
724 // then the value will be copied and the |value| reference will not change.
725 // Otherwise, ownership will be transferred to this object and the |value|
726 // reference will be invalidated.
728 /*--cef(index_param=index)--*/
729 virtual bool SetBinary(int index, CefRefPtr<CefBinaryValue> value) =0;
732 // Sets the value at the specified index as type dict. Returns true if the
733 // value was set successfully. If |value| is currently owned by another object
734 // then the value will be copied and the |value| reference will not change.
735 // Otherwise, ownership will be transferred to this object and the |value|
736 // reference will be invalidated.
738 /*--cef(index_param=index)--*/
739 virtual bool SetDictionary(int index, CefRefPtr<CefDictionaryValue> value) =0;
742 // Sets the value at the specified index as type list. Returns true if the
743 // value was set successfully. If |value| is currently owned by another object
744 // then the value will be copied and the |value| reference will not change.
745 // Otherwise, ownership will be transferred to this object and the |value|
746 // reference will be invalidated.
748 /*--cef(index_param=index)--*/
749 virtual bool SetList(int index, CefRefPtr<CefListValue> value) =0;
752 #endif // CEF_INCLUDE_CEF_VALUES_H_