00001 #ifndef PROTON_CODEC_H 00002 #define PROTON_CODEC_H 1 00003 00004 /* 00005 * 00006 * Licensed to the Apache Software Foundation (ASF) under one 00007 * or more contributor license agreements. See the NOTICE file 00008 * distributed with this work for additional information 00009 * regarding copyright ownership. The ASF licenses this file 00010 * to you under the Apache License, Version 2.0 (the 00011 * "License"); you may not use this file except in compliance 00012 * with the License. You may obtain a copy of the License at 00013 * 00014 * http://www.apache.org/licenses/LICENSE-2.0 00015 * 00016 * Unless required by applicable law or agreed to in writing, 00017 * software distributed under the License is distributed on an 00018 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 00019 * KIND, either express or implied. See the License for the 00020 * specific language governing permissions and limitations 00021 * under the License. 00022 * 00023 */ 00024 00025 #include <proton/import_export.h> 00026 #include <proton/object.h> 00027 #include <proton/types.h> 00028 #include <proton/error.h> 00029 #include <proton/type_compat.h> 00030 #include <stdarg.h> 00031 00032 #ifdef __cplusplus 00033 extern "C" { 00034 #endif 00035 00036 /** 00037 * @file 00038 * 00039 * Data API for proton. 00040 * 00041 * @defgroup data Data 00042 * @{ 00043 */ 00044 00045 /** 00046 * Identifies an AMQP type. 00047 */ 00048 typedef enum { 00049 00050 /** 00051 * The NULL AMQP type. 00052 */ 00053 PN_NULL = 1, 00054 00055 /** 00056 * The boolean AMQP type. 00057 */ 00058 PN_BOOL = 2, 00059 00060 /** 00061 * The unsigned byte AMQP type. An 8 bit unsigned integer. 00062 */ 00063 PN_UBYTE = 3, 00064 00065 /** 00066 * The byte AMQP type. An 8 bit signed integer. 00067 */ 00068 PN_BYTE = 4, 00069 00070 /** 00071 * The unsigned short AMQP type. A 16 bit unsigned integer. 00072 */ 00073 PN_USHORT = 5, 00074 00075 /** 00076 * The short AMQP type. A 16 bit signed integer. 00077 */ 00078 PN_SHORT = 6, 00079 00080 /** 00081 * The unsigned int AMQP type. A 32 bit unsigned integer. 00082 */ 00083 PN_UINT = 7, 00084 00085 /** 00086 * The signed int AMQP type. A 32 bit signed integer. 00087 */ 00088 PN_INT = 8, 00089 00090 /** 00091 * The char AMQP type. A 32 bit unicode character. 00092 */ 00093 PN_CHAR = 9, 00094 00095 /** 00096 * The ulong AMQP type. An unsigned 32 bit integer. 00097 */ 00098 PN_ULONG = 10, 00099 00100 /** 00101 * The long AMQP type. A signed 32 bit integer. 00102 */ 00103 PN_LONG = 11, 00104 00105 /** 00106 * The timestamp AMQP type. A signed 64 bit value measuring 00107 * milliseconds since the epoch. 00108 */ 00109 PN_TIMESTAMP = 12, 00110 00111 /** 00112 * The float AMQP type. A 32 bit floating point value. 00113 */ 00114 PN_FLOAT = 13, 00115 00116 /** 00117 * The double AMQP type. A 64 bit floating point value. 00118 */ 00119 PN_DOUBLE = 14, 00120 00121 /** 00122 * The decimal32 AMQP type. A 32 bit decimal floating point value. 00123 */ 00124 PN_DECIMAL32 = 15, 00125 00126 /** 00127 * The decimal64 AMQP type. A 64 bit decimal floating point value. 00128 */ 00129 PN_DECIMAL64 = 16, 00130 00131 /** 00132 * The decimal128 AMQP type. A 128 bit decimal floating point value. 00133 */ 00134 PN_DECIMAL128 = 17, 00135 00136 /** 00137 * The UUID AMQP type. A 16 byte UUID. 00138 */ 00139 PN_UUID = 18, 00140 00141 /** 00142 * The binary AMQP type. A variable length sequence of bytes. 00143 */ 00144 PN_BINARY = 19, 00145 00146 /** 00147 * The string AMQP type. A variable length sequence of unicode 00148 * characters. 00149 */ 00150 PN_STRING = 20, 00151 00152 /** 00153 * The symbol AMQP type. A variable length sequence of unicode 00154 * characters. 00155 */ 00156 PN_SYMBOL = 21, 00157 00158 /** 00159 * A described AMQP type. 00160 */ 00161 PN_DESCRIBED = 22, 00162 00163 /** 00164 * An AMQP array. A monomorphic sequence of other AMQP values. 00165 */ 00166 PN_ARRAY = 23, 00167 00168 /** 00169 * An AMQP list. A polymorphic sequence of other AMQP values. 00170 */ 00171 PN_LIST = 24, 00172 00173 /** 00174 * An AMQP map. A polymorphic container of other AMQP values formed 00175 * into key/value pairs. 00176 */ 00177 PN_MAP = 25, 00178 00179 /** 00180 * A special invalid type value that is returned when no valid type 00181 * is available. 00182 */ 00183 PN_INVALID = -1 00184 } pn_type_t; 00185 00186 /** 00187 * Return a string name for an AMQP type. 00188 * 00189 * @param type an AMQP type 00190 * @return the string name of the given type 00191 */ 00192 PN_EXTERN const char *pn_type_name(pn_type_t type); 00193 00194 /** 00195 * A descriminated union that holds any scalar AMQP value. The type 00196 * field indicates the AMQP type of the value, and the union may be 00197 * used to access the value for a given type. 00198 */ 00199 typedef struct { 00200 /** 00201 * Indicates the type of value the atom is currently pointing to. 00202 * See ::pn_type_t for details on AMQP types. 00203 */ 00204 pn_type_t type; 00205 union { 00206 /** 00207 * Valid when type is ::PN_BOOL. 00208 */ 00209 bool as_bool; 00210 00211 /** 00212 * Valid when type is ::PN_UBYTE. 00213 */ 00214 uint8_t as_ubyte; 00215 00216 /** 00217 * Valid when type is ::PN_BYTE. 00218 */ 00219 int8_t as_byte; 00220 00221 /** 00222 * Valid when type is ::PN_USHORT. 00223 */ 00224 uint16_t as_ushort; 00225 00226 /** 00227 * Valid when type is ::PN_SHORT. 00228 */ 00229 int16_t as_short; 00230 00231 /** 00232 * Valid when type is ::PN_UINT. 00233 */ 00234 uint32_t as_uint; 00235 00236 /** 00237 * Valid when type is ::PN_INT. 00238 */ 00239 int32_t as_int; 00240 00241 /** 00242 * Valid when type is ::PN_CHAR. 00243 */ 00244 pn_char_t as_char; 00245 00246 /** 00247 * Valid when type is ::PN_ULONG. 00248 */ 00249 uint64_t as_ulong; 00250 00251 /** 00252 * Valid when type is ::PN_LONG. 00253 */ 00254 int64_t as_long; 00255 00256 /** 00257 * Valid when type is ::PN_TIMESTAMP. 00258 */ 00259 pn_timestamp_t as_timestamp; 00260 00261 /** 00262 * Valid when type is ::PN_FLOAT. 00263 */ 00264 float as_float; 00265 00266 /** 00267 * Valid when type is ::PN_DOUBLE. 00268 */ 00269 double as_double; 00270 00271 /** 00272 * Valid when type is ::PN_DECIMAL32. 00273 */ 00274 pn_decimal32_t as_decimal32; 00275 00276 /** 00277 * Valid when type is ::PN_DECIMAL64. 00278 */ 00279 pn_decimal64_t as_decimal64; 00280 00281 /** 00282 * Valid when type is ::PN_DECIMAL128. 00283 */ 00284 pn_decimal128_t as_decimal128; 00285 00286 /** 00287 * Valid when type is ::PN_UUID. 00288 */ 00289 pn_uuid_t as_uuid; 00290 00291 /** 00292 * Valid when type is ::PN_BINARY or ::PN_STRING or ::PN_SYMBOL. 00293 * When the type is ::PN_STRING the field will point to utf8 00294 * encoded unicode. When the type is ::PN_SYMBOL, the field will 00295 * point to 7-bit ASCII. In the latter two cases, the bytes 00296 * pointed to are *not* necessarily null terminated. 00297 */ 00298 pn_bytes_t as_bytes; 00299 } u; 00300 } pn_atom_t; 00301 00302 /** 00303 * An AMQP Data object. 00304 * 00305 * A pn_data_t object provides an interface for decoding, extracting, 00306 * creating, and encoding arbitrary AMQP data. A pn_data_t object 00307 * contains a tree of AMQP values. Leaf nodes in this tree correspond 00308 * to scalars in the AMQP type system such as @link ::PN_INT ints 00309 * @endlink or @link ::PN_STRING strings @endlink. Non-leaf nodes in 00310 * this tree correspond to compound values in the AMQP type system 00311 * such as @link ::PN_LIST lists @endlink, @link ::PN_MAP maps 00312 * @endlink, @link ::PN_ARRAY arrays @endlink, or @link ::PN_DESCRIBED 00313 * described @endlink values. The root node of the tree is the 00314 * pn_data_t object itself and can have an arbitrary number of 00315 * children. 00316 * 00317 * A pn_data_t object maintains the notion of the current node and the 00318 * current parent node. Siblings are ordered within their parent. 00319 * Values are accessed and/or added by using the ::pn_data_next(), 00320 * ::pn_data_prev(), ::pn_data_enter(), and ::pn_data_exit() 00321 * operations to navigate to the desired location in the tree and 00322 * using the supplied variety of pn_data_put_* / pn_data_get_* 00323 * operations to access or add a value of the desired type. 00324 * 00325 * The pn_data_put_* operations will always add a value _after_ the 00326 * current node in the tree. If the current node has a next sibling 00327 * the pn_data_put_* operations will overwrite the value on this node. 00328 * If there is no current node or the current node has no next sibling 00329 * then one will be added. The pn_data_put_* operations always set the 00330 * added/modified node to the current node. The pn_data_get_* 00331 * operations read the value of the current node and do not change 00332 * which node is current. 00333 * 00334 * The following types of scalar values are supported: 00335 * 00336 * - ::PN_NULL 00337 * - ::PN_BOOL 00338 * - ::PN_UBYTE 00339 * - ::PN_USHORT 00340 * - ::PN_SHORT 00341 * - ::PN_UINT 00342 * - ::PN_INT 00343 * - ::PN_ULONG 00344 * - ::PN_LONG 00345 * - ::PN_FLOAT 00346 * - ::PN_DOUBLE 00347 * - ::PN_BINARY 00348 * - ::PN_STRING 00349 * - ::PN_SYMBOL 00350 * 00351 * The following types of compound values are supported: 00352 * 00353 * - ::PN_DESCRIBED 00354 * - ::PN_ARRAY 00355 * - ::PN_LIST 00356 * - ::PN_MAP 00357 */ 00358 typedef struct pn_data_t pn_data_t; 00359 00360 /** 00361 * Construct a pn_data_t object with the supplied initial capacity. A 00362 * pn_data_t will grow automatically as needed, so an initial capacity 00363 * of 0 is permitted. 00364 * 00365 * @param capacity the initial capacity 00366 * @return the newly constructed pn_data_t 00367 */ 00368 PN_EXTERN pn_data_t *pn_data(size_t capacity); 00369 00370 /** 00371 * Free a pn_data_t object. 00372 * 00373 * @param data a pn_data_t object or NULL 00374 */ 00375 PN_EXTERN void pn_data_free(pn_data_t *data); 00376 00377 /** 00378 * Access the current error code for a given pn_data_t. 00379 * 00380 * @param data a pn_data_t object 00381 * @return the current error code 00382 */ 00383 PN_EXTERN int pn_data_errno(pn_data_t *data); 00384 00385 /** 00386 * Access the current error for a givn pn_data_t. 00387 * 00388 * Every pn_data_t has an error descriptor that is created with the 00389 * pn_data_t and dies with the pn_data_t. The error descriptor is 00390 * updated whenever an operation fails. The ::pn_data_error() function 00391 * may be used to access a pn_data_t's error descriptor. 00392 * 00393 * @param data a pn_data_t object 00394 * @return a pointer to the pn_data_t's error descriptor 00395 */ 00396 PN_EXTERN pn_error_t *pn_data_error(pn_data_t *data); 00397 00398 PN_EXTERN int pn_data_vfill(pn_data_t *data, const char *fmt, va_list ap); 00399 PN_EXTERN int pn_data_fill(pn_data_t *data, const char *fmt, ...); 00400 PN_EXTERN int pn_data_vscan(pn_data_t *data, const char *fmt, va_list ap); 00401 PN_EXTERN int pn_data_scan(pn_data_t *data, const char *fmt, ...); 00402 00403 /** 00404 * Clears a pn_data_t object. 00405 * 00406 * A cleared pn_data_t object is equivalent to a newly constructed 00407 * one. 00408 * 00409 * @param data the pn_data_t object to clear 00410 */ 00411 PN_EXTERN void pn_data_clear(pn_data_t *data); 00412 00413 /** 00414 * Returns the total number of nodes contained in a pn_data_t object. 00415 * This includes all parents, children, siblings, grandchildren, etc. 00416 * In other words the count of all ancesters and descendents of the 00417 * current node, along with the current node if there is one. 00418 * 00419 * @param data a pn_data_t object 00420 * @return the total number of nodes in the pn_data_t object 00421 */ 00422 PN_EXTERN size_t pn_data_size(pn_data_t *data); 00423 00424 /** 00425 * Clears current node pointer and sets the parent to the root node. 00426 * Clearing the current node sets it _before_ the first node, calling 00427 * ::pn_data_next() will advance to the first node. 00428 */ 00429 PN_EXTERN void pn_data_rewind(pn_data_t *data); 00430 00431 /** 00432 * Advances the current node to its next sibling and returns true. If 00433 * there is no next sibling the current node remains unchanged and 00434 * false is returned. 00435 * 00436 * @param data a pn_data_t object 00437 * @return true iff the current node was changed 00438 */ 00439 PN_EXTERN bool pn_data_next(pn_data_t *data); 00440 00441 /** 00442 * Moves the current node to its previous sibling and returns true. If 00443 * there is no previous sibling the current node remains unchanged and 00444 * false is returned. 00445 * 00446 * @param data a pn_data_t object 00447 * @return true iff the current node was changed 00448 */ 00449 PN_EXTERN bool pn_data_prev(pn_data_t *data); 00450 00451 /** 00452 * Sets the parent node to the current node and clears the current 00453 * node. Clearing the current node sets it _before_ the first child, 00454 * calling ::pn_data_next() advances to the first child. This 00455 * operation will return false if there is no current node or if the 00456 * current node is not a compound type. 00457 * 00458 * @param data a pn_data_object 00459 * @return true iff the pointers to the current/parent nodes are changed 00460 */ 00461 PN_EXTERN bool pn_data_enter(pn_data_t *data); 00462 00463 /** 00464 * Sets the current node to the parent node and the parent node to its 00465 * own parent. This operation will return false if there is no current 00466 * node or parent node. 00467 * 00468 * @param data a pn_data object 00469 * @return true iff the pointers to the current/parent nodes are 00470 * changed 00471 */ 00472 PN_EXTERN bool pn_data_exit(pn_data_t *data); 00473 00474 PN_EXTERN bool pn_data_lookup(pn_data_t *data, const char *name); 00475 00476 /** 00477 * Access the type of the current node. Returns PN_INVALID if there is no 00478 * current node. 00479 * 00480 * @param data a data object 00481 * @return the type of the current node 00482 */ 00483 PN_EXTERN pn_type_t pn_data_type(pn_data_t *data); 00484 00485 /** 00486 * Prints the contents of a pn_data_t object using ::pn_data_format() 00487 * to stdout. 00488 * 00489 * @param data a pn_data_t object 00490 * @return zero on success or an error on failure 00491 */ 00492 PN_EXTERN int pn_data_print(pn_data_t *data); 00493 00494 /** 00495 * Formats the contents of a pn_data_t object in a human readable way 00496 * and writes them to the indicated location. The size pointer must 00497 * hold the amount of free space following the bytes pointer, and upon 00498 * success will be updated to indicate how much space has been used. 00499 * 00500 * @param data a pn_data_t object 00501 * @param bytes a buffer to write the output to 00502 * @param size a pointer to the size of the buffer 00503 * @return zero on succes, or an error on failure 00504 */ 00505 PN_EXTERN int pn_data_format(pn_data_t *data, char *bytes, size_t *size); 00506 00507 /** 00508 * Writes the contents of a data object to the given buffer as an AMQP 00509 * data stream. 00510 * 00511 * @param data the data object to encode 00512 * @param bytes the buffer for encoded data 00513 * @param size the size of the buffer 00514 * 00515 * @return the size of the encoded data on success or an error code on failure 00516 */ 00517 PN_EXTERN ssize_t pn_data_encode(pn_data_t *data, char *bytes, size_t size); 00518 00519 /** 00520 * Returns the number of bytes needed to encode a data object. 00521 * 00522 * @param data the data object 00523 * 00524 * @return the size of the encoded data or an error code if data is invalid. 00525 */ 00526 PN_EXTERN ssize_t pn_data_encoded_size(pn_data_t *data); 00527 00528 /** 00529 * Decodes a single value from the contents of the AMQP data stream 00530 * into the current data object. Note that if the pn_data_t object is 00531 * pointing to a current node, the decoded value will overwrite the 00532 * current one. If the pn_data_t object has no current node then a 00533 * node will be appended to the current parent. If there is no current 00534 * parent then a node will be appended to the pn_data_t itself. 00535 * 00536 * Upon success, this operation returns the number of bytes consumed 00537 * from the AMQP data stream. Upon failure, this operation returns an 00538 * error code. 00539 * 00540 * @param data a pn_data_t object 00541 * @param bytes a pointer to an encoded AMQP data stream 00542 * @param size the size of the encoded AMQP data stream 00543 * @return the number of bytes consumed from the AMQP data stream or an error code 00544 */ 00545 PN_EXTERN ssize_t pn_data_decode(pn_data_t *data, const char *bytes, size_t size); 00546 00547 /** 00548 * Puts an empty list value into a pn_data_t. Elements may be filled 00549 * by entering the list node using ::pn_data_enter() and using 00550 * pn_data_put_* to add the desired contents. Once done, 00551 * ::pn_data_exit() may be used to return to the current level in the 00552 * tree and put more values. 00553 * 00554 * @code 00555 * pn_data_t *data = pn_data(0); 00556 * ... 00557 * pn_data_put_list(data); 00558 * pn_data_enter(data); 00559 * pn_data_put_int(data, 1); 00560 * pn_data_put_int(data, 2); 00561 * pn_data_put_int(data, 3); 00562 * pn_data_exit(data); 00563 * ... 00564 * @endcode 00565 * 00566 * @param data a pn_data_t object 00567 * @return zero on success or an error code on failure 00568 */ 00569 PN_EXTERN int pn_data_put_list(pn_data_t *data); 00570 00571 /** 00572 * Puts an empty map value into a pn_data_t. Elements may be filled by 00573 * entering the map node and putting alternating key value pairs. 00574 * 00575 * @code 00576 * pn_data_t *data = pn_data(0); 00577 * ... 00578 * pn_data_put_map(data); 00579 * pn_data_enter(data); 00580 * pn_data_put_string(data, pn_bytes(3, "key")); 00581 * pn_data_put_string(data, pn_bytes(5, "value")); 00582 * pn_data_exit(data); 00583 * ... 00584 * @endcode 00585 * 00586 * @param data a pn_data_t object 00587 * @return zero on success or an error code on failure 00588 */ 00589 PN_EXTERN int pn_data_put_map(pn_data_t *data); 00590 00591 /** 00592 * Puts an empty array value into a pn_data_t. Elements may be filled 00593 * by entering the array node and putting the element values. The 00594 * values must all be of the specified array element type. If an array 00595 * is described then the first child value of the array is the 00596 * descriptor and may be of any type. 00597 * 00598 * @code 00599 * pn_data_t *data = pn_data(0); 00600 * ... 00601 * pn_data_put_array(data, false, PN_INT); 00602 * pn_data_enter(data); 00603 * pn_data_put_int(data, 1); 00604 * pn_data_put_int(data, 2); 00605 * pn_data_put_int(data, 3); 00606 * pn_data_exit(data); 00607 * ... 00608 * pn_data_put_array(data, True, Data.DOUBLE); 00609 * pn_data_enter(data); 00610 * pn_data_put_symbol(data, "array-descriptor"); 00611 * pn_data_put_double(data, 1.1); 00612 * pn_data_put_double(data, 1.2); 00613 * pn_data_put_double(data, 1.3); 00614 * pn_data_exit(data); 00615 * ... 00616 * @endcode 00617 * 00618 * @param data a pn_data_t object 00619 * @param described specifies whether the array is described 00620 * @param type the type of the array 00621 * 00622 * @return zero on success or an error code on failure 00623 */ 00624 PN_EXTERN int pn_data_put_array(pn_data_t *data, bool described, pn_type_t type); 00625 00626 /** 00627 * Puts a described value into a pn_data_t object. A described node 00628 * has two children, the descriptor and the value. These are specified 00629 * by entering the node and putting the desired values. 00630 * 00631 * @code 00632 * pn_data_t *data = pn_data(0); 00633 * ... 00634 * pn_data_put_described(data); 00635 * pn_data_enter(data); 00636 * pn_data_put_symbol(data, pn_bytes(16, "value-descriptor")); 00637 * pn_data_put_string(data, pn_bytes(9, "the value")); 00638 * pn_data_exit(data); 00639 * ... 00640 * @endcode 00641 * 00642 * @param data a pn_data_t object 00643 * @return zero on success or an error code on failure 00644 */ 00645 PN_EXTERN int pn_data_put_described(pn_data_t *data); 00646 00647 /** 00648 * Puts a ::PN_NULL value. 00649 * 00650 * @param data a pn_data_t object 00651 * @return zero on success or an error code on failure 00652 */ 00653 PN_EXTERN int pn_data_put_null(pn_data_t *data); 00654 00655 /** 00656 * Puts a ::PN_BOOL value. 00657 * 00658 * @param data a pn_data_t object 00659 * @param b the value 00660 * @return zero on success or an error code on failure 00661 */ 00662 PN_EXTERN int pn_data_put_bool(pn_data_t *data, bool b); 00663 00664 /** 00665 * Puts a ::PN_UBYTE value. 00666 * 00667 * @param data a pn_data_t object 00668 * @param ub the value 00669 * @return zero on success or an error code on failure 00670 */ 00671 PN_EXTERN int pn_data_put_ubyte(pn_data_t *data, uint8_t ub); 00672 00673 /** 00674 * Puts a ::PN_BYTE value. 00675 * 00676 * @param data a pn_data_t object 00677 * @param b the value 00678 * @return zero on success or an error code on failure 00679 */ 00680 PN_EXTERN int pn_data_put_byte(pn_data_t *data, int8_t b); 00681 00682 /** 00683 * Puts a ::PN_USHORT value. 00684 * 00685 * @param data a pn_data_t object 00686 * @param us the value 00687 * @return zero on success or an error code on failure 00688 */ 00689 PN_EXTERN int pn_data_put_ushort(pn_data_t *data, uint16_t us); 00690 00691 /** 00692 * Puts a ::PN_SHORT value. 00693 * 00694 * @param data a pn_data_t object 00695 * @param s the value 00696 * @return zero on success or an error code on failure 00697 */ 00698 PN_EXTERN int pn_data_put_short(pn_data_t *data, int16_t s); 00699 00700 /** 00701 * Puts a ::PN_UINT value. 00702 * 00703 * @param data a pn_data_t object 00704 * @param ui the value 00705 * @return zero on success or an error code on failure 00706 */ 00707 PN_EXTERN int pn_data_put_uint(pn_data_t *data, uint32_t ui); 00708 00709 /** 00710 * Puts a ::PN_INT value. 00711 * 00712 * @param data a pn_data_t object 00713 * @param i the value 00714 * @return zero on success or an error code on failure 00715 */ 00716 PN_EXTERN int pn_data_put_int(pn_data_t *data, int32_t i); 00717 00718 /** 00719 * Puts a ::PN_CHAR value. 00720 * 00721 * @param data a pn_data_t object 00722 * @param c the value 00723 * @return zero on success or an error code on failure 00724 */ 00725 PN_EXTERN int pn_data_put_char(pn_data_t *data, pn_char_t c); 00726 00727 /** 00728 * Puts a ::PN_ULONG value. 00729 * 00730 * @param data a pn_data_t object 00731 * @param ul the value 00732 * @return zero on success or an error code on failure 00733 */ 00734 PN_EXTERN int pn_data_put_ulong(pn_data_t *data, uint64_t ul); 00735 00736 /** 00737 * Puts a ::PN_LONG value. 00738 * 00739 * @param data a pn_data_t object 00740 * @param l the value 00741 * @return zero on success or an error code on failure 00742 */ 00743 PN_EXTERN int pn_data_put_long(pn_data_t *data, int64_t l); 00744 00745 /** 00746 * Puts a ::PN_TIMESTAMP value. 00747 * 00748 * @param data a pn_data_t object 00749 * @param t the value 00750 * @return zero on success or an error code on failure 00751 */ 00752 PN_EXTERN int pn_data_put_timestamp(pn_data_t *data, pn_timestamp_t t); 00753 00754 /** 00755 * Puts a ::PN_FLOAT value. 00756 * 00757 * @param data a pn_data_t object 00758 * @param f the value 00759 * @return zero on success or an error code on failure 00760 */ 00761 PN_EXTERN int pn_data_put_float(pn_data_t *data, float f); 00762 00763 /** 00764 * Puts a ::PN_DOUBLE value. 00765 * 00766 * @param data a pn_data_t object 00767 * @param d the value 00768 * @return zero on success or an error code on failure 00769 */ 00770 PN_EXTERN int pn_data_put_double(pn_data_t *data, double d); 00771 00772 /** 00773 * Puts a ::PN_DECIMAL32 value. 00774 * 00775 * @param data a pn_data_t object 00776 * @param d the value 00777 * @return zero on success or an error code on failure 00778 */ 00779 PN_EXTERN int pn_data_put_decimal32(pn_data_t *data, pn_decimal32_t d); 00780 00781 /** 00782 * Puts a ::PN_DECIMAL64 value. 00783 * 00784 * @param data a pn_data_t object 00785 * @param d the value 00786 * @return zero on success or an error code on failure 00787 */ 00788 PN_EXTERN int pn_data_put_decimal64(pn_data_t *data, pn_decimal64_t d); 00789 00790 /** 00791 * Puts a ::PN_DECIMAL128 value. 00792 * 00793 * @param data a pn_data_t object 00794 * @param d the value 00795 * @return zero on success or an error code on failure 00796 */ 00797 PN_EXTERN int pn_data_put_decimal128(pn_data_t *data, pn_decimal128_t d); 00798 00799 /** 00800 * Puts a ::PN_UUID value. 00801 * 00802 * @param data a pn_data_t object 00803 * @param u the value 00804 * @return zero on success or an error code on failure 00805 */ 00806 PN_EXTERN int pn_data_put_uuid(pn_data_t *data, pn_uuid_t u); 00807 00808 /** 00809 * Puts a ::PN_BINARY value. The bytes referenced by the pn_bytes_t 00810 * argument are copied and stored inside the pn_data_t object. 00811 * 00812 * @param data a pn_data_t object 00813 * @param bytes the value 00814 * @return zero on success or an error code on failure 00815 */ 00816 PN_EXTERN int pn_data_put_binary(pn_data_t *data, pn_bytes_t bytes); 00817 00818 /** 00819 * Puts a ::PN_STRING value. The bytes referenced by the pn_bytes_t 00820 * argument are copied and stored inside the pn_data_t object. 00821 * 00822 * @param data a pn_data_t object 00823 * @param string utf8 encoded unicode 00824 * @return zero on success or an error code on failure 00825 */ 00826 PN_EXTERN int pn_data_put_string(pn_data_t *data, pn_bytes_t string); 00827 00828 /** 00829 * Puts a ::PN_SYMBOL value. The bytes referenced by the pn_bytes_t 00830 * argument are copied and stored inside the pn_data_t object. 00831 * 00832 * @param data a pn_data_t object 00833 * @param symbol ascii encoded symbol 00834 * @return zero on success or an error code on failure 00835 */ 00836 PN_EXTERN int pn_data_put_symbol(pn_data_t *data, pn_bytes_t symbol); 00837 00838 /** 00839 * Puts any scalar value value. 00840 * 00841 * @param data a pn_data_t object 00842 * @param atom the value 00843 * @return zero on success or an error code on failure 00844 */ 00845 PN_EXTERN int pn_data_put_atom(pn_data_t *data, pn_atom_t atom); 00846 00847 /** 00848 * If the current node is a list, return the number of elements, 00849 * otherwise return zero. List elements can be accessed by entering 00850 * the list. 00851 * 00852 * @code 00853 * ... 00854 * size_t count = pn_data_get_list(data); 00855 * pn_data_enter(data); 00856 * for (size_t i = 0; i < count; i++) { 00857 * if (pn_data_next(data)) { 00858 * switch (pn_data_type(data)) { 00859 * case PN_STRING: 00860 * ... 00861 * break; 00862 * case PN_INT: 00863 * ... 00864 * break; 00865 * } 00866 * } 00867 * pn_data_exit(data); 00868 * ... 00869 * @endcode 00870 .* 00871 * @param data a pn_data_t object 00872 * @return the size of a list node 00873 */ 00874 PN_EXTERN size_t pn_data_get_list(pn_data_t *data); 00875 00876 /** 00877 * If the current node is a map, return the number of child elements, 00878 * otherwise return zero. Key value pairs can be accessed by entering 00879 * the map. 00880 * 00881 * @code 00882 * ... 00883 * size_t count = pn_data_get_map(data); 00884 * pn_data_enter(data); 00885 * for (size_t i = 0; i < count/2; i++) { 00886 * // read key 00887 * if (pn_data_next(data)) { 00888 * switch (pn_data_type(data)) { 00889 * case PN_STRING: 00890 * ... 00891 * break; 00892 * ... 00893 * } 00894 * } 00895 * ... 00896 * // read value 00897 * if (pn_data_next(data)) { 00898 * switch (pn_data_type(data)) { 00899 * case PN_INT: 00900 * ... 00901 * break; 00902 * ... 00903 * } 00904 * } 00905 * ... 00906 * } 00907 * pn_data_exit(data); 00908 * ... 00909 * @endcode 00910 * 00911 * @param data a pn_data_t object 00912 * @return the number of child elements of a map node 00913 */ 00914 PN_EXTERN size_t pn_data_get_map(pn_data_t *data); 00915 00916 /** 00917 * If the current node is an array, return the number of elements in 00918 * the array, otherwise return 0. Array data can be accessed by 00919 * entering the array. If the array is described, the first child node 00920 * will be the descriptor, and the remaining count child nodes 00921 * will be the elements of the array. 00922 * 00923 * @code 00924 * ... 00925 * size_t count = pn_data_get_array(data); 00926 * bool described = pn_data_is_array_described(data); 00927 * pn_type_t type = pn_data_get_array_type(data); 00928 * 00929 * pn_data_enter(data); 00930 * 00931 * if (described && pn_data_next(data)) { 00932 * // the descriptor could be another type, but let's assume it's a symbol 00933 * pn_bytes_t descriptor = pn_data_get_symbol(data); 00934 * } 00935 * 00936 * for (size_t i = 0; i < count; i++) { 00937 * if (pn_data_next(data)) { 00938 * // all elements will be values of the array type retrieved above 00939 * ... 00940 * } 00941 * } 00942 * pn_data_exit(data); 00943 * ... 00944 * @endcode 00945 * 00946 * @param data a pn_data_t object 00947 * @return the number of elements of an array node 00948 */ 00949 PN_EXTERN size_t pn_data_get_array(pn_data_t *data); 00950 00951 /** 00952 * Returns true if the current node points to a described array. 00953 * 00954 * @param data a pn_data_t object 00955 * @return true if the current node points to a described array 00956 */ 00957 PN_EXTERN bool pn_data_is_array_described(pn_data_t *data); 00958 00959 /** 00960 * Return the array type if the current node points to an array, 00961 * PN_INVALID otherwise. 00962 * 00963 * @param data a pn_data_t object 00964 * @return the element type of an array node 00965 */ 00966 PN_EXTERN pn_type_t pn_data_get_array_type(pn_data_t *data); 00967 00968 /** 00969 * Checks if the current node is a described value. The descriptor and 00970 * value may be accessed by entering the described value node. 00971 * 00972 * @code 00973 * ... 00974 * // read a symbolically described string 00975 * if (pn_data_is_described(data)) { 00976 * pn_data_enter(data); 00977 * pn_data_next(data); 00978 * assert(pn_data_type(data) == PN_SYMBOL); 00979 * pn_bytes_t symbol = pn_data_get_symbol(data); 00980 * pn_data_next(data); 00981 * assert(pn_data_type(data) == PN_STRING); 00982 * pn_bytes_t utf8 = pn_data_get_string(data); 00983 * pn_data_exit(data); 00984 * } 00985 * ... 00986 * @endcode 00987 * 00988 * @param data a pn_data_t object 00989 * @return true if the current node is a described type 00990 */ 00991 PN_EXTERN bool pn_data_is_described(pn_data_t *data); 00992 00993 /** 00994 * Checks if the current node is a ::PN_NULL. 00995 * 00996 * @param data a pn_data_t object 00997 * @return true iff the current node is ::PN_NULL 00998 */ 00999 PN_EXTERN bool pn_data_is_null(pn_data_t *data); 01000 01001 /** 01002 * If the current node is a ::PN_BOOL, returns its value. 01003 * 01004 * @param data a pn_data_t object 01005 */ 01006 PN_EXTERN bool pn_data_get_bool(pn_data_t *data); 01007 01008 /** 01009 * If the current node is a ::PN_UBYTE, return its value, otherwise 01010 * return 0. 01011 * 01012 * @param data a pn_data_t object 01013 */ 01014 PN_EXTERN uint8_t pn_data_get_ubyte(pn_data_t *data); 01015 01016 /** 01017 * If the current node is a signed byte, returns its value, returns 0 01018 * otherwise. 01019 * 01020 * @param data a pn_data_t object 01021 */ 01022 PN_EXTERN int8_t pn_data_get_byte(pn_data_t *data); 01023 01024 /** 01025 * If the current node is an unsigned short, returns its value, 01026 * returns 0 otherwise. 01027 * 01028 * @param data a pn_data_t object 01029 */ 01030 PN_EXTERN uint16_t pn_data_get_ushort(pn_data_t *data); 01031 01032 /** 01033 * If the current node is a signed short, returns its value, returns 0 01034 * otherwise. 01035 * 01036 * @param data a pn_data_t object 01037 */ 01038 PN_EXTERN int16_t pn_data_get_short(pn_data_t *data); 01039 01040 /** 01041 * If the current node is an unsigned int, returns its value, returns 01042 * 0 otherwise. 01043 * 01044 * @param data a pn_data_t object 01045 */ 01046 PN_EXTERN uint32_t pn_data_get_uint(pn_data_t *data); 01047 01048 /** 01049 * If the current node is a signed int, returns its value, returns 0 01050 * otherwise. 01051 * 01052 * @param data a pn_data_t object 01053 */ 01054 PN_EXTERN int32_t pn_data_get_int(pn_data_t *data); 01055 01056 /** 01057 * If the current node is a char, returns its value, returns 0 01058 * otherwise. 01059 * 01060 * @param data a pn_data_t object 01061 */ 01062 PN_EXTERN pn_char_t pn_data_get_char(pn_data_t *data); 01063 01064 /** 01065 * If the current node is an unsigned long, returns its value, returns 01066 * 0 otherwise. 01067 * 01068 * @param data a pn_data_t object 01069 */ 01070 PN_EXTERN uint64_t pn_data_get_ulong(pn_data_t *data); 01071 01072 /** 01073 * If the current node is an signed long, returns its value, returns 0 01074 * otherwise. 01075 * 01076 * @param data a pn_data_t object 01077 */ 01078 PN_EXTERN int64_t pn_data_get_long(pn_data_t *data); 01079 01080 /** 01081 * If the current node is a timestamp, returns its value, returns 0 01082 * otherwise. 01083 * 01084 * @param data a pn_data_t object 01085 */ 01086 PN_EXTERN pn_timestamp_t pn_data_get_timestamp(pn_data_t *data); 01087 01088 /** 01089 * If the current node is a float, returns its value, raises 0 01090 * otherwise. 01091 * 01092 * @param data a pn_data_t object 01093 */ 01094 PN_EXTERN float pn_data_get_float(pn_data_t *data); 01095 01096 /** 01097 * If the current node is a double, returns its value, returns 0 01098 * otherwise. 01099 * 01100 * @param data a pn_data_t object 01101 */ 01102 PN_EXTERN double pn_data_get_double(pn_data_t *data); 01103 01104 /** 01105 * If the current node is a decimal32, returns its value, returns 0 01106 * otherwise. 01107 * 01108 * @param data a pn_data_t object 01109 */ 01110 PN_EXTERN pn_decimal32_t pn_data_get_decimal32(pn_data_t *data); 01111 01112 /** 01113 * If the current node is a decimal64, returns its value, returns 0 01114 * otherwise. 01115 * 01116 * @param data a pn_data_t object 01117 */ 01118 PN_EXTERN pn_decimal64_t pn_data_get_decimal64(pn_data_t *data); 01119 01120 /** 01121 * If the current node is a decimal128, returns its value, returns 0 01122 * otherwise. 01123 * 01124 * @param data a pn_data_t object 01125 */ 01126 PN_EXTERN pn_decimal128_t pn_data_get_decimal128(pn_data_t *data); 01127 01128 /** 01129 * If the current node is a UUID, returns its value, returns None 01130 * otherwise. 01131 * 01132 * @param data a pn_data_t object 01133 * @return a uuid value 01134 */ 01135 PN_EXTERN pn_uuid_t pn_data_get_uuid(pn_data_t *data); 01136 01137 /** 01138 * If the current node is binary, returns its value, returns "" 01139 * otherwise. The pn_bytes_t returned will point to memory held inside 01140 * the pn_data_t. When the pn_data_t is cleared or freed, this memory 01141 * will be reclaimed. 01142 * 01143 * @param data a pn_data_t object 01144 */ 01145 PN_EXTERN pn_bytes_t pn_data_get_binary(pn_data_t *data); 01146 01147 /** 01148 * If the current node is a string, returns its value, returns "" 01149 * otherwise. The pn_bytes_t returned will point to memory held inside 01150 * the pn_data_t. When the pn_data_t is cleared or freed, this memory 01151 * will be reclaimed. 01152 * 01153 * @param data a pn_data_t object 01154 * @return a pn_bytes_t pointing to utf8 01155 */ 01156 PN_EXTERN pn_bytes_t pn_data_get_string(pn_data_t *data); 01157 01158 /** 01159 * If the current node is a symbol, returns its value, returns "" 01160 * otherwise. The pn_bytes_t returned will point to memory held inside 01161 * the pn_data_t. When the pn_data_t is cleared or freed, this memory 01162 * will be reclaimed. 01163 * 01164 * @param data a pn_data_t object 01165 * @return a pn_bytes_t pointing to ascii 01166 */ 01167 PN_EXTERN pn_bytes_t pn_data_get_symbol(pn_data_t *data); 01168 01169 /** 01170 * If the current node is a symbol, string, or binary, return the 01171 * bytes representing its value. The pn_bytes_t returned will point to 01172 * memory held inside the pn_data_t. When the pn_data_t is cleared or 01173 * freed, this memory will be reclaimed. 01174 * 01175 * @param data a pn_data_t object 01176 * @return a pn_bytes_t pointing to the node's value 01177 */ 01178 PN_EXTERN pn_bytes_t pn_data_get_bytes(pn_data_t *data); 01179 01180 /** 01181 * If the current node is a scalar value, return it as a pn_atom_t. 01182 * 01183 * @param data a pn_data_t object 01184 * @return the value of the current node as pn_atom_t 01185 */ 01186 PN_EXTERN pn_atom_t pn_data_get_atom(pn_data_t *data); 01187 01188 /** 01189 * Copy the contents of another pn_data_t object. Any values in the 01190 * data object will be lost. 01191 * 01192 * @param data a pn_data_t object 01193 * @param src the sourc pn_data_t to copy from 01194 * @return zero on success or an error code on failure 01195 */ 01196 PN_EXTERN int pn_data_copy(pn_data_t *data, pn_data_t *src); 01197 01198 /** 01199 * Append the contents of another pn_data_t object. 01200 * 01201 * @param data a pn_data_t object 01202 * @param src the sourc pn_data_t to append from 01203 * @return zero on success or an error code on failure 01204 */ 01205 PN_EXTERN int pn_data_append(pn_data_t *data, pn_data_t *src); 01206 01207 /** 01208 * Append up to _n_ values from the contents of another pn_data_t 01209 * object. 01210 * 01211 * @param data a pn_data_t object 01212 * @param src the sourc pn_data_t to append from 01213 * @param limit the maximum number of values to append 01214 * @return zero on success or an error code on failure 01215 */ 01216 PN_EXTERN int pn_data_appendn(pn_data_t *data, pn_data_t *src, int limit); 01217 01218 /** 01219 * Modify a pn_data_t object to behave as if the current node is the 01220 * root node of the tree. This impacts the behaviour of 01221 * ::pn_data_rewind(), ::pn_data_next(), ::pn_data_prev(), and 01222 * anything else that depends on the navigational state of the 01223 * pn_data_t object. Use ::pn_data_widen() to reverse the effect of 01224 * this operation. 01225 * 01226 * @param data a pn_data_t object 01227 */ 01228 PN_EXTERN void pn_data_narrow(pn_data_t *data); 01229 01230 /** 01231 * Reverse the effect of ::pn_data_narrow(). 01232 * 01233 * @param data a pn_data_t object 01234 */ 01235 PN_EXTERN void pn_data_widen(pn_data_t *data); 01236 01237 /** 01238 * Returns a handle for the current navigational state of a pn_data_t 01239 * so that it can be later restored using ::pn_data_restore(). 01240 * 01241 * @param data a pn_data_t object 01242 * @return a handle for the current navigational state 01243 */ 01244 PN_EXTERN pn_handle_t pn_data_point(pn_data_t *data); 01245 01246 /** 01247 * Restores a prior navigational state that was saved using 01248 * ::pn_data_point(). If the data object has been modified in such a 01249 * way that the prior navigational state cannot be restored, then this 01250 * will return false and the navigational state will remain unchanged, 01251 * otherwise it will return true. 01252 * 01253 * @param data a pn_data_t object 01254 * @param point a handle referencing the saved navigational state 01255 * @return true iff the prior navigational state was restored 01256 */ 01257 PN_EXTERN bool pn_data_restore(pn_data_t *data, pn_handle_t point); 01258 01259 /** 01260 * Dumps a debug representation of the internal state of the pn_data_t 01261 * object that includes its navigational state to stdout for debugging 01262 * purposes. 01263 * 01264 * @param data a pn_data_t object that is behaving in a confusing way 01265 */ 01266 PN_EXTERN void pn_data_dump(pn_data_t *data); 01267 01268 /** @} 01269 */ 01270 01271 #ifdef __cplusplus 01272 } 01273 #endif 01274 01275 #endif /* codec.h */