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