1 /* 2 Copyright (c) DataStax, Inc. 3 4 Licensed under the Apache License, Version 2.0 (the "License"); 5 you may not use this file except in compliance with the License. 6 You may obtain a copy of the License at 7 8 http://www.apache.org/licenses/LICENSE-2.0 9 10 Unless required by applicable law or agreed to in writing, software 11 distributed under the License is distributed on an "AS IS" BASIS, 12 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 See the License for the specific language governing permissions and 14 limitations under the License. 15 */ 16 17 #ifndef __CASSANDRA_H_INCLUDED__ 18 #define __CASSANDRA_H_INCLUDED__ 19 20 #include <stddef.h> 21 #include <stdint.h> 22 23 #if !defined(CASS_STATIC) 24 # if (defined(WIN32) || defined(_WIN32)) 25 # if defined(CASS_BUILDING) 26 # define CASS_EXPORT __declspec(dllexport) 27 # else 28 # define CASS_EXPORT __declspec(dllimport) 29 # endif 30 # elif (defined(__SUNPRO_C) || defined(__SUNPRO_CC)) && !defined(CASS_STATIC) 31 # define CASS_EXPORT __global 32 # elif (defined(__GNUC__) && __GNUC__ >= 4) || defined(__INTEL_COMPILER) 33 # define CASS_EXPORT __attribute__ ((visibility("default"))) 34 # endif 35 #else 36 #define CASS_EXPORT 37 #endif 38 39 #if defined(_MSC_VER) 40 # define CASS_DEPRECATED(func) __declspec(deprecated) func 41 #elif defined(__GNUC__) || defined(__INTEL_COMPILER) 42 # define CASS_DEPRECATED(func) func __attribute__((deprecated)) 43 #else 44 # define CASS_DEPRECATED(func) func 45 #endif 46 47 /** 48 * @file include/cassandra.h 49 * 50 * C/C++ driver for Apache Cassandra. Uses the Cassandra Query Language versions 3 51 * over the Cassandra Binary Protocol (versions 1, 2, or 3). 52 */ 53 54 #define CASS_VERSION_MAJOR 2 55 #define CASS_VERSION_MINOR 16 56 #define CASS_VERSION_PATCH 0 57 #define CASS_VERSION_SUFFIX "" 58 59 #ifdef __cplusplus 60 extern "C" { 61 #endif 62 63 typedef enum { cass_false = 0, cass_true = 1 } cass_bool_t; 64 65 typedef float cass_float_t; 66 typedef double cass_double_t; 67 68 typedef int8_t cass_int8_t; 69 typedef uint8_t cass_uint8_t; 70 71 typedef int16_t cass_int16_t; 72 typedef uint16_t cass_uint16_t; 73 74 typedef int32_t cass_int32_t; 75 typedef uint32_t cass_uint32_t; 76 77 typedef int64_t cass_int64_t; 78 typedef uint64_t cass_uint64_t; 79 80 #define CASS_UINT64_MAX 18446744073709551615ULL 81 82 typedef cass_uint8_t cass_byte_t; 83 typedef cass_uint64_t cass_duration_t; 84 85 /** 86 * The size of an IPv4 address 87 */ 88 #define CASS_INET_V4_LENGTH 4 89 90 /** 91 * The size of an IPv6 address 92 */ 93 #define CASS_INET_V6_LENGTH 16 94 95 /** 96 * The size of an inet string including a null terminator. 97 */ 98 #define CASS_INET_STRING_LENGTH 46 99 100 /** 101 * IP address for either IPv4 or IPv6. 102 * 103 * @struct CassInet 104 */ 105 typedef struct CassInet_ { 106 /** 107 * Big-endian, binary representation of a IPv4 or IPv6 address 108 */ 109 cass_uint8_t address[CASS_INET_V6_LENGTH]; 110 /** 111 * Number of address bytes. 4 bytes for IPv4 and 16 bytes for IPv6. 112 */ 113 cass_uint8_t address_length; 114 } CassInet; 115 116 /** 117 * The size of a hexadecimal UUID string including a null terminator. 118 */ 119 #define CASS_UUID_STRING_LENGTH 37 120 121 /** 122 * Version 1 (time-based) or version 4 (random) UUID. 123 * 124 * @struct CassUuid 125 */ 126 typedef struct CassUuid_ { 127 /** 128 * Represents the time and version part of a UUID. The most significant 129 * 4 bits represent the version and the bottom 60 bits representing the 130 * time part. For version 1 the time part represents the number of 131 * 100 nanosecond periods since 00:00:00 UTC, January 1, 1970 (the Epoch). 132 * For version 4 the time part is randomly generated. 133 */ 134 cass_uint64_t time_and_version; 135 /** 136 * Represents the clock sequence and the node part of a UUID. The most 137 * significant 16 bits represent the clock sequence (except for the most 138 * significant bit which is always set) and the bottom 48 bits represent 139 * the node part. For version 1 (time-based) the clock sequence part is randomly 140 * generated and the node part can be explicitly set, otherwise, it's generated 141 * from node unique information. For version 4 both the clock sequence and the node 142 * parts are randomly generated. 143 */ 144 cass_uint64_t clock_seq_and_node; 145 } CassUuid; 146 147 /** 148 * A cluster object describes the configuration of the Cassandra cluster and is used 149 * to construct a session instance. Unlike other DataStax drivers the cluster object 150 * does not maintain the control connection. 151 * 152 * @struct CassCluster 153 */ 154 typedef struct CassCluster_ CassCluster; 155 156 /** 157 * A session object is used to execute queries and maintains cluster state through 158 * the control connection. The control connection is used to auto-discover nodes and 159 * monitor cluster changes (topology and schema). Each session also maintains multiple 160 * pools of connections to cluster nodes which are used to query the cluster. 161 * 162 * Instances of the session object are thread-safe to execute queries. 163 * 164 * @struct CassSession 165 */ 166 typedef struct CassSession_ CassSession; 167 168 /** 169 * A statement object is an executable query. It represents either a regular 170 * (adhoc) statement or a prepared statement. It maintains the queries' parameter 171 * values along with query options (consistency level, paging state, etc.) 172 * 173 * <b>Note:</b> Parameters for regular queries are not supported by the binary protocol 174 * version 1. 175 * 176 * @struct CassStatement 177 */ 178 typedef struct CassStatement_ CassStatement; 179 180 /** 181 * A group of statements that are executed as a single batch. 182 * 183 * <b>Note:</b> Batches are not supported by the binary protocol version 1. 184 * 185 * @cassandra{2.0+} 186 * 187 * @struct CassBatch 188 */ 189 typedef struct CassBatch_ CassBatch; 190 191 /** 192 * The future result of an operation. 193 * 194 * It can represent a result if the operation completed successfully or an 195 * error if the operation failed. It can be waited on, polled or a callback 196 * can be attached. 197 * 198 * @struct CassFuture 199 */ 200 typedef struct CassFuture_ CassFuture; 201 202 /** 203 * A statement that has been prepared cluster-side (It has been pre-parsed 204 * and cached). 205 * 206 * A prepared statement is read-only and it is thread-safe to concurrently 207 * bind new statements. 208 * 209 * @struct CassPrepared 210 */ 211 typedef struct CassPrepared_ CassPrepared; 212 213 /** 214 * The result of a query. 215 * 216 * A result object is read-only and is thread-safe to read or iterate over 217 * concurrently. 218 * 219 * @struct CassResult 220 */ 221 typedef struct CassResult_ CassResult; 222 223 /** 224 * A error result of a request 225 * 226 * @struct CassErrorResult 227 */ 228 typedef struct CassErrorResult_ CassErrorResult; 229 230 231 /** 232 * An object that represents a cluster node. 233 * 234 * @struct CassNode 235 */ 236 typedef struct CassNode_ CassNode; 237 238 /** 239 * An object used to iterate over a group of rows, columns or collection values. 240 * 241 * @struct CassIterator 242 */ 243 typedef struct CassIterator_ CassIterator; 244 245 /** 246 * A collection of column values. 247 * 248 * @struct CassRow 249 */ 250 typedef struct CassRow_ CassRow; 251 252 /** 253 * A single primitive value or a collection of values. 254 * 255 * @struct CassValue 256 */ 257 typedef struct CassValue_ CassValue; 258 259 /** 260 * A data type used to describe a value, collection or 261 * user defined type. 262 * 263 * @struct CassDataType 264 */ 265 typedef struct CassDataType_ CassDataType; 266 267 /** 268 * @struct CassFunctionMeta 269 * 270 * @cassandra{2.2+} 271 */ 272 typedef struct CassFunctionMeta_ CassFunctionMeta; 273 274 /** 275 * @struct CassAggregateMeta 276 * 277 * @cassandra{2.2+} 278 */ 279 typedef struct CassAggregateMeta_ CassAggregateMeta; 280 281 /** 282 * A collection of values. 283 * 284 * @struct CassCollection 285 */ 286 typedef struct CassCollection_ CassCollection; 287 288 /** 289 * A tuple of values. 290 * 291 * @struct CassTuple 292 * 293 * @cassandra{2.1+} 294 */ 295 typedef struct CassTuple_ CassTuple; 296 297 /** 298 * A user defined type. 299 * 300 * @struct CassUserType 301 * 302 * @cassandra{2.1+} 303 */ 304 typedef struct CassUserType_ CassUserType; 305 306 /** 307 * Describes the SSL configuration of a cluster. 308 * 309 * @struct CassSsl 310 */ 311 typedef struct CassSsl_ CassSsl; 312 313 /** 314 * Describes the version of the connected Cassandra cluster. 315 * 316 * @struct CassVersion 317 */ 318 319 typedef struct CassVersion_ { 320 int major_version; 321 int minor_version; 322 int patch_version; 323 } CassVersion; 324 325 /** 326 * A snapshot of the schema's metadata. 327 * 328 * @struct CassSchemaMeta 329 */ 330 typedef struct CassSchemaMeta_ CassSchemaMeta; 331 332 /** 333 * Keyspace metadata 334 * 335 * @struct CassKeyspaceMeta 336 */ 337 typedef struct CassKeyspaceMeta_ CassKeyspaceMeta; 338 339 /** 340 * Table metadata 341 * 342 * @struct CassTableMeta 343 */ 344 typedef struct CassTableMeta_ CassTableMeta; 345 346 /** 347 * MaterializedView metadata 348 * 349 * @struct CassMaterializedViewMeta 350 * 351 * @cassandra{3.0+} 352 */ 353 typedef struct CassMaterializedViewMeta_ CassMaterializedViewMeta; 354 355 /** 356 * Column metadata 357 * 358 * @struct CassColumnMeta 359 */ 360 typedef struct CassColumnMeta_ CassColumnMeta; 361 362 /** 363 * Index metadata 364 * 365 * @struct CassIndexMeta 366 */ 367 typedef struct CassIndexMeta_ CassIndexMeta; 368 369 /** 370 * A UUID generator object. 371 * 372 * Instances of the UUID generator object are thread-safe to generate UUIDs. 373 * 374 * @struct CassUuidGen 375 */ 376 typedef struct CassUuidGen_ CassUuidGen; 377 378 /** 379 * Policies that defined the behavior of a request when a server-side 380 * read/write timeout or unavailable error occurs. 381 * 382 * Generators of client-side, microsecond-precision timestamps. 383 * 384 * @struct CassTimestampGen 385 * 386 * @cassandra{2.1+} 387 */ 388 typedef struct CassTimestampGen_ CassTimestampGen; 389 390 /** 391 * @struct CassRetryPolicy 392 */ 393 typedef struct CassRetryPolicy_ CassRetryPolicy; 394 395 /** 396 * @struct CassCustomPayload 397 * 398 * @cassandra{2.2+} 399 */ 400 typedef struct CassCustomPayload_ CassCustomPayload; 401 402 /** 403 * A snapshot of the session's performance/diagnostic metrics. 404 * 405 * @struct CassMetrics 406 */ 407 typedef struct CassMetrics_ { 408 struct { 409 cass_uint64_t min; /**< Minimum in microseconds */ 410 cass_uint64_t max; /**< Maximum in microseconds */ 411 cass_uint64_t mean; /**< Mean in microseconds */ 412 cass_uint64_t stddev; /**< Standard deviation in microseconds */ 413 cass_uint64_t median; /**< Median in microseconds */ 414 cass_uint64_t percentile_75th; /**< 75th percentile in microseconds */ 415 cass_uint64_t percentile_95th; /**< 95th percentile in microseconds */ 416 cass_uint64_t percentile_98th; /**< 98th percentile in microseconds */ 417 cass_uint64_t percentile_99th; /**< 99the percentile in microseconds */ 418 cass_uint64_t percentile_999th; /**< 99.9th percentile in microseconds */ 419 cass_double_t mean_rate; /**< Mean rate in requests per second */ 420 cass_double_t one_minute_rate; /**< 1 minute rate in requests per second */ 421 cass_double_t five_minute_rate; /**< 5 minute rate in requests per second */ 422 cass_double_t fifteen_minute_rate; /**< 15 minute rate in requests per second */ 423 } requests; /**< Performance request metrics */ 424 425 struct { 426 cass_uint64_t total_connections; /**< The total number of connections */ 427 cass_uint64_t available_connections; /**< Deprecated */ 428 cass_uint64_t exceeded_pending_requests_water_mark; /**< Deprecated */ 429 cass_uint64_t exceeded_write_bytes_water_mark; /**< Deprecated */ 430 } stats; /**< Diagnostic metrics */ 431 432 struct { 433 cass_uint64_t connection_timeouts; /**< Occurrences of a connection timeout */ 434 cass_uint64_t pending_request_timeouts; /**< Deprecated */ 435 cass_uint64_t request_timeouts; /**< Occurrences of requests that timed out waiting for a request to finish */ 436 } errors; /**< Error metrics */ 437 } CassMetrics; 438 439 typedef struct CassSpeculativeExecutionMetrics_ { 440 cass_uint64_t min; /**< Minimum in microseconds */ 441 cass_uint64_t max; /**< Maximum in microseconds */ 442 cass_uint64_t mean; /**< Mean in microseconds */ 443 cass_uint64_t stddev; /**< Standard deviation in microseconds */ 444 cass_uint64_t median; /**< Median in microseconds */ 445 cass_uint64_t percentile_75th; /**< 75th percentile in microseconds */ 446 cass_uint64_t percentile_95th; /**< 95th percentile in microseconds */ 447 cass_uint64_t percentile_98th; /**< 98th percentile in microseconds */ 448 cass_uint64_t percentile_99th; /**< 99the percentile in microseconds */ 449 cass_uint64_t percentile_999th; /**< 99.9th percentile in microseconds */ 450 cass_uint64_t count; /**< The number of aborted speculative retries */ 451 cass_double_t percentage; /**< Fraction of requests that are aborted speculative retries */ 452 } CassSpeculativeExecutionMetrics; 453 454 typedef enum CassConsistency_ { 455 CASS_CONSISTENCY_UNKNOWN = 0xFFFF, 456 CASS_CONSISTENCY_ANY = 0x0000, 457 CASS_CONSISTENCY_ONE = 0x0001, 458 CASS_CONSISTENCY_TWO = 0x0002, 459 CASS_CONSISTENCY_THREE = 0x0003, 460 CASS_CONSISTENCY_QUORUM = 0x0004, 461 CASS_CONSISTENCY_ALL = 0x0005, 462 CASS_CONSISTENCY_LOCAL_QUORUM = 0x0006, 463 CASS_CONSISTENCY_EACH_QUORUM = 0x0007, 464 CASS_CONSISTENCY_SERIAL = 0x0008, 465 CASS_CONSISTENCY_LOCAL_SERIAL = 0x0009, 466 CASS_CONSISTENCY_LOCAL_ONE = 0x000A 467 } CassConsistency; 468 469 #define CASS_CONSISTENCY_MAPPING(XX) \ 470 XX(CASS_CONSISTENCY_UNKNOWN, "UNKNOWN") \ 471 XX(CASS_CONSISTENCY_ANY, "ANY") \ 472 XX(CASS_CONSISTENCY_ONE, "ONE") \ 473 XX(CASS_CONSISTENCY_TWO, "TWO") \ 474 XX(CASS_CONSISTENCY_THREE, "THREE") \ 475 XX(CASS_CONSISTENCY_QUORUM, "QUORUM") \ 476 XX(CASS_CONSISTENCY_ALL, "ALL") \ 477 XX(CASS_CONSISTENCY_LOCAL_QUORUM, "LOCAL_QUORUM") \ 478 XX(CASS_CONSISTENCY_EACH_QUORUM, "EACH_QUORUM") \ 479 XX(CASS_CONSISTENCY_SERIAL, "SERIAL") \ 480 XX(CASS_CONSISTENCY_LOCAL_SERIAL, "LOCAL_SERIAL") \ 481 XX(CASS_CONSISTENCY_LOCAL_ONE, "LOCAL_ONE") 482 483 /* @cond IGNORE */ 484 #define CASS_CONSISTENCY_MAP CASS_CONSISTENCY_MAPPING /* Deprecated */ 485 /* @endcond */ 486 487 typedef enum CassWriteType_ { 488 CASS_WRITE_TYPE_UNKNOWN, 489 CASS_WRITE_TYPE_SIMPLE, 490 CASS_WRITE_TYPE_BATCH, 491 CASS_WRITE_TYPE_UNLOGGED_BATCH, 492 CASS_WRITE_TYPE_COUNTER, 493 CASS_WRITE_TYPE_BATCH_LOG, 494 CASS_WRITE_TYPE_CAS, 495 CASS_WRITE_TYPE_VIEW, 496 CASS_WRITE_TYPE_CDC 497 } CassWriteType; 498 499 #define CASS_WRITE_TYPE_MAPPING(XX) \ 500 XX(CASS_WRITE_TYPE_SIMPLE, "SIMPLE") \ 501 XX(CASS_WRITE_TYPE_BATCH, "BATCH") \ 502 XX(CASS_WRITE_TYPE_UNLOGGED_BATCH, "UNLOGGED_BATCH") \ 503 XX(CASS_WRITE_TYPE_COUNTER, "COUNTER") \ 504 XX(CASS_WRITE_TYPE_BATCH_LOG, "BATCH_LOG") \ 505 XX(CASS_WRITE_TYPE_CAS, "CAS") \ 506 XX(CASS_WRITE_TYPE_VIEW, "VIEW") \ 507 XX(CASS_WRITE_TYPE_CDC, "CDC") 508 509 /* @cond IGNORE */ 510 #define CASS_WRITE_TYPE_MAP CASS_WRITE_TYPE_MAPPING /* Deprecated */ 511 /* @endcond */ 512 513 typedef enum CassColumnType_ { 514 CASS_COLUMN_TYPE_REGULAR, 515 CASS_COLUMN_TYPE_PARTITION_KEY, 516 CASS_COLUMN_TYPE_CLUSTERING_KEY, 517 CASS_COLUMN_TYPE_STATIC, 518 CASS_COLUMN_TYPE_COMPACT_VALUE 519 } CassColumnType; 520 521 typedef enum CassIndexType_ { 522 CASS_INDEX_TYPE_UNKNOWN, 523 CASS_INDEX_TYPE_KEYS, 524 CASS_INDEX_TYPE_CUSTOM, 525 CASS_INDEX_TYPE_COMPOSITES 526 } CassIndexType; 527 528 #define CASS_VALUE_TYPE_MAPPING(XX) \ 529 XX(CASS_VALUE_TYPE_CUSTOM, 0x0000, "", "") \ 530 XX(CASS_VALUE_TYPE_ASCII, 0x0001, "ascii", "org.apache.cassandra.db.marshal.AsciiType") \ 531 XX(CASS_VALUE_TYPE_BIGINT, 0x0002, "bigint", "org.apache.cassandra.db.marshal.LongType") \ 532 XX(CASS_VALUE_TYPE_BLOB, 0x0003, "blob", "org.apache.cassandra.db.marshal.BytesType") \ 533 XX(CASS_VALUE_TYPE_BOOLEAN, 0x0004, "boolean", "org.apache.cassandra.db.marshal.BooleanType") \ 534 XX(CASS_VALUE_TYPE_COUNTER, 0x0005, "counter", "org.apache.cassandra.db.marshal.CounterColumnType") \ 535 XX(CASS_VALUE_TYPE_DECIMAL, 0x0006, "decimal", "org.apache.cassandra.db.marshal.DecimalType") \ 536 XX(CASS_VALUE_TYPE_DOUBLE, 0x0007, "double", "org.apache.cassandra.db.marshal.DoubleType") \ 537 XX(CASS_VALUE_TYPE_FLOAT, 0x0008, "float", "org.apache.cassandra.db.marshal.FloatType") \ 538 XX(CASS_VALUE_TYPE_INT, 0x0009, "int", "org.apache.cassandra.db.marshal.Int32Type") \ 539 XX(CASS_VALUE_TYPE_TEXT, 0x000A, "text", "org.apache.cassandra.db.marshal.UTF8Type") \ 540 XX(CASS_VALUE_TYPE_TIMESTAMP, 0x000B, "timestamp", "org.apache.cassandra.db.marshal.TimestampType") \ 541 XX(CASS_VALUE_TYPE_UUID, 0x000C, "uuid", "org.apache.cassandra.db.marshal.UUIDType") \ 542 XX(CASS_VALUE_TYPE_VARCHAR, 0x000D, "varchar", "") \ 543 XX(CASS_VALUE_TYPE_VARINT, 0x000E, "varint", "org.apache.cassandra.db.marshal.IntegerType") \ 544 XX(CASS_VALUE_TYPE_TIMEUUID, 0x000F, "timeuuid", "org.apache.cassandra.db.marshal.TimeUUIDType") \ 545 XX(CASS_VALUE_TYPE_INET, 0x0010, "inet", "org.apache.cassandra.db.marshal.InetAddressType") \ 546 XX(CASS_VALUE_TYPE_DATE, 0x0011, "date", "org.apache.cassandra.db.marshal.SimpleDateType") \ 547 XX(CASS_VALUE_TYPE_TIME, 0x0012, "time", "org.apache.cassandra.db.marshal.TimeType") \ 548 XX(CASS_VALUE_TYPE_SMALL_INT, 0x0013, "smallint", "org.apache.cassandra.db.marshal.ShortType") \ 549 XX(CASS_VALUE_TYPE_TINY_INT, 0x0014, "tinyint", "org.apache.cassandra.db.marshal.ByteType") \ 550 XX(CASS_VALUE_TYPE_DURATION, 0x0015, "duration", "org.apache.cassandra.db.marshal.DurationType") \ 551 XX(CASS_VALUE_TYPE_LIST, 0x0020, "list", "org.apache.cassandra.db.marshal.ListType") \ 552 XX(CASS_VALUE_TYPE_MAP, 0x0021, "map", "org.apache.cassandra.db.marshal.MapType") \ 553 XX(CASS_VALUE_TYPE_SET, 0x0022, "set", "org.apache.cassandra.db.marshal.SetType") \ 554 XX(CASS_VALUE_TYPE_UDT, 0x0030, "", "") \ 555 XX(CASS_VALUE_TYPE_TUPLE, 0x0031, "tuple", "org.apache.cassandra.db.marshal.TupleType") 556 557 typedef enum CassValueType_ { 558 CASS_VALUE_TYPE_UNKNOWN = 0xFFFF, 559 #define XX_VALUE_TYPE(name, type, cql, klass) name = type, 560 CASS_VALUE_TYPE_MAPPING(XX_VALUE_TYPE) 561 #undef XX_VALUE_TYPE 562 /* @cond IGNORE */ 563 CASS_VALUE_TYPE_LAST_ENTRY 564 /* @endcond */ 565 } CassValueType; 566 567 typedef enum CassClusteringOrder_ { 568 CASS_CLUSTERING_ORDER_NONE, 569 CASS_CLUSTERING_ORDER_ASC, 570 CASS_CLUSTERING_ORDER_DESC 571 } CassClusteringOrder; 572 573 typedef enum CassCollectionType_ { 574 CASS_COLLECTION_TYPE_LIST = CASS_VALUE_TYPE_LIST, 575 CASS_COLLECTION_TYPE_MAP = CASS_VALUE_TYPE_MAP, 576 CASS_COLLECTION_TYPE_SET = CASS_VALUE_TYPE_SET 577 } CassCollectionType; 578 579 typedef enum CassBatchType_ { 580 CASS_BATCH_TYPE_LOGGED = 0x00, 581 CASS_BATCH_TYPE_UNLOGGED = 0x01, 582 CASS_BATCH_TYPE_COUNTER = 0x02 583 } CassBatchType; 584 585 typedef enum CassIteratorType_ { 586 CASS_ITERATOR_TYPE_RESULT, 587 CASS_ITERATOR_TYPE_ROW, 588 CASS_ITERATOR_TYPE_COLLECTION, 589 CASS_ITERATOR_TYPE_MAP, 590 CASS_ITERATOR_TYPE_TUPLE, 591 CASS_ITERATOR_TYPE_USER_TYPE_FIELD, 592 CASS_ITERATOR_TYPE_META_FIELD, 593 CASS_ITERATOR_TYPE_KEYSPACE_META, 594 CASS_ITERATOR_TYPE_TABLE_META, 595 CASS_ITERATOR_TYPE_TYPE_META, 596 CASS_ITERATOR_TYPE_FUNCTION_META, 597 CASS_ITERATOR_TYPE_AGGREGATE_META, 598 CASS_ITERATOR_TYPE_COLUMN_META, 599 CASS_ITERATOR_TYPE_INDEX_META, 600 CASS_ITERATOR_TYPE_MATERIALIZED_VIEW_META 601 } CassIteratorType; 602 603 #define CASS_LOG_LEVEL_MAPPING(XX) \ 604 XX(CASS_LOG_DISABLED, "") \ 605 XX(CASS_LOG_CRITICAL, "CRITICAL") \ 606 XX(CASS_LOG_ERROR, "ERROR") \ 607 XX(CASS_LOG_WARN, "WARN") \ 608 XX(CASS_LOG_INFO, "INFO") \ 609 XX(CASS_LOG_DEBUG, "DEBUG") \ 610 XX(CASS_LOG_TRACE, "TRACE") 611 612 /* @cond IGNORE */ 613 #define CASS_LOG_LEVEL_MAP CASS_LOG_LEVEL_MAPPING /* Deprecated */ 614 /* @endcond */ 615 616 typedef enum CassLogLevel_ { 617 #define XX_LOG(log_level, _) log_level, 618 CASS_LOG_LEVEL_MAPPING(XX_LOG) 619 #undef XX_LOG 620 /* @cond IGNORE */ 621 CASS_LOG_LAST_ENTRY 622 /* @endcond */ 623 } CassLogLevel; 624 625 typedef enum CassSslVerifyFlags_ { 626 CASS_SSL_VERIFY_NONE = 0x00, 627 CASS_SSL_VERIFY_PEER_CERT = 0x01, 628 CASS_SSL_VERIFY_PEER_IDENTITY = 0x02, 629 CASS_SSL_VERIFY_PEER_IDENTITY_DNS = 0x04 630 } CassSslVerifyFlags; 631 632 typedef enum CassProtocolVersion_ { 633 CASS_PROTOCOL_VERSION_V1 = 0x01, /**< Deprecated */ 634 CASS_PROTOCOL_VERSION_V2 = 0x02, /**< Deprecated */ 635 CASS_PROTOCOL_VERSION_V3 = 0x03, 636 CASS_PROTOCOL_VERSION_V4 = 0x04, 637 CASS_PROTOCOL_VERSION_V5 = 0x05, 638 CASS_PROTOCOL_VERSION_DSEV1 = 0x41, /**< Only supported when using the DSE 639 driver with DataStax Enterprise */ 640 CASS_PROTOCOL_VERSION_DSEV2 = 0x42 /**< Only supported when using the DSE 641 driver with DataStax Enterprise */ 642 } CassProtocolVersion; 643 644 typedef enum CassErrorSource_ { 645 CASS_ERROR_SOURCE_NONE, 646 CASS_ERROR_SOURCE_LIB, 647 CASS_ERROR_SOURCE_SERVER, 648 CASS_ERROR_SOURCE_SSL, 649 CASS_ERROR_SOURCE_COMPRESSION 650 } CassErrorSource; 651 652 #define CASS_ERROR_MAPPING(XX) \ 653 XX(CASS_ERROR_SOURCE_LIB, CASS_ERROR_LIB_BAD_PARAMS, 1, "Bad parameters") \ 654 XX(CASS_ERROR_SOURCE_LIB, CASS_ERROR_LIB_NO_STREAMS, 2, "No streams available") \ 655 XX(CASS_ERROR_SOURCE_LIB, CASS_ERROR_LIB_UNABLE_TO_INIT, 3, "Unable to initialize") \ 656 XX(CASS_ERROR_SOURCE_LIB, CASS_ERROR_LIB_MESSAGE_ENCODE, 4, "Unable to encode message") \ 657 XX(CASS_ERROR_SOURCE_LIB, CASS_ERROR_LIB_HOST_RESOLUTION, 5, "Unable to resolve host") \ 658 XX(CASS_ERROR_SOURCE_LIB, CASS_ERROR_LIB_UNEXPECTED_RESPONSE, 6, "Unexpected response from server") \ 659 XX(CASS_ERROR_SOURCE_LIB, CASS_ERROR_LIB_REQUEST_QUEUE_FULL, 7, "The request queue is full") \ 660 XX(CASS_ERROR_SOURCE_LIB, CASS_ERROR_LIB_NO_AVAILABLE_IO_THREAD, 8, "No available IO threads") \ 661 XX(CASS_ERROR_SOURCE_LIB, CASS_ERROR_LIB_WRITE_ERROR, 9, "Write error") \ 662 XX(CASS_ERROR_SOURCE_LIB, CASS_ERROR_LIB_NO_HOSTS_AVAILABLE, 10, "No hosts available") \ 663 XX(CASS_ERROR_SOURCE_LIB, CASS_ERROR_LIB_INDEX_OUT_OF_BOUNDS, 11, "Index out of bounds") \ 664 XX(CASS_ERROR_SOURCE_LIB, CASS_ERROR_LIB_INVALID_ITEM_COUNT, 12, "Invalid item count") \ 665 XX(CASS_ERROR_SOURCE_LIB, CASS_ERROR_LIB_INVALID_VALUE_TYPE, 13, "Invalid value type") \ 666 XX(CASS_ERROR_SOURCE_LIB, CASS_ERROR_LIB_REQUEST_TIMED_OUT, 14, "Request timed out") \ 667 XX(CASS_ERROR_SOURCE_LIB, CASS_ERROR_LIB_UNABLE_TO_SET_KEYSPACE, 15, "Unable to set keyspace") \ 668 XX(CASS_ERROR_SOURCE_LIB, CASS_ERROR_LIB_CALLBACK_ALREADY_SET, 16, "Callback already set") \ 669 XX(CASS_ERROR_SOURCE_LIB, CASS_ERROR_LIB_INVALID_STATEMENT_TYPE, 17, "Invalid statement type") \ 670 XX(CASS_ERROR_SOURCE_LIB, CASS_ERROR_LIB_NAME_DOES_NOT_EXIST, 18, "No value or column for name") \ 671 XX(CASS_ERROR_SOURCE_LIB, CASS_ERROR_LIB_UNABLE_TO_DETERMINE_PROTOCOL, 19, "Unable to find supported protocol version") \ 672 XX(CASS_ERROR_SOURCE_LIB, CASS_ERROR_LIB_NULL_VALUE, 20, "NULL value specified") \ 673 XX(CASS_ERROR_SOURCE_LIB, CASS_ERROR_LIB_NOT_IMPLEMENTED, 21, "Not implemented") \ 674 XX(CASS_ERROR_SOURCE_LIB, CASS_ERROR_LIB_UNABLE_TO_CONNECT, 22, "Unable to connect") \ 675 XX(CASS_ERROR_SOURCE_LIB, CASS_ERROR_LIB_UNABLE_TO_CLOSE, 23, "Unable to close") \ 676 XX(CASS_ERROR_SOURCE_LIB, CASS_ERROR_LIB_NO_PAGING_STATE, 24, "No paging state") \ 677 XX(CASS_ERROR_SOURCE_LIB, CASS_ERROR_LIB_PARAMETER_UNSET, 25, "Parameter unset") \ 678 XX(CASS_ERROR_SOURCE_LIB, CASS_ERROR_LIB_INVALID_ERROR_RESULT_TYPE, 26, "Invalid error result type") \ 679 XX(CASS_ERROR_SOURCE_LIB, CASS_ERROR_LIB_INVALID_FUTURE_TYPE, 27, "Invalid future type") \ 680 XX(CASS_ERROR_SOURCE_LIB, CASS_ERROR_LIB_INTERNAL_ERROR, 28, "Internal error") \ 681 XX(CASS_ERROR_SOURCE_LIB, CASS_ERROR_LIB_INVALID_CUSTOM_TYPE, 29, "Invalid custom type") \ 682 XX(CASS_ERROR_SOURCE_LIB, CASS_ERROR_LIB_INVALID_DATA, 30, "Invalid data") \ 683 XX(CASS_ERROR_SOURCE_LIB, CASS_ERROR_LIB_NOT_ENOUGH_DATA, 31, "Not enough data") \ 684 XX(CASS_ERROR_SOURCE_LIB, CASS_ERROR_LIB_INVALID_STATE, 32, "Invalid state") \ 685 XX(CASS_ERROR_SOURCE_LIB, CASS_ERROR_LIB_NO_CUSTOM_PAYLOAD, 33, "No custom payload") \ 686 XX(CASS_ERROR_SOURCE_LIB, CASS_ERROR_LIB_EXECUTION_PROFILE_INVALID, 34, "Invalid execution profile specified") \ 687 XX(CASS_ERROR_SOURCE_LIB, CASS_ERROR_LIB_NO_TRACING_ID, 35, "No tracing ID") \ 688 XX(CASS_ERROR_SOURCE_SERVER, CASS_ERROR_SERVER_SERVER_ERROR, 0x0000, "Server error") \ 689 XX(CASS_ERROR_SOURCE_SERVER, CASS_ERROR_SERVER_PROTOCOL_ERROR, 0x000A, "Protocol error") \ 690 XX(CASS_ERROR_SOURCE_SERVER, CASS_ERROR_SERVER_BAD_CREDENTIALS, 0x0100, "Bad credentials") \ 691 XX(CASS_ERROR_SOURCE_SERVER, CASS_ERROR_SERVER_UNAVAILABLE, 0x1000, "Unavailable") \ 692 XX(CASS_ERROR_SOURCE_SERVER, CASS_ERROR_SERVER_OVERLOADED, 0x1001, "Overloaded") \ 693 XX(CASS_ERROR_SOURCE_SERVER, CASS_ERROR_SERVER_IS_BOOTSTRAPPING, 0x1002, "Is bootstrapping") \ 694 XX(CASS_ERROR_SOURCE_SERVER, CASS_ERROR_SERVER_TRUNCATE_ERROR, 0x1003, "Truncate error") \ 695 XX(CASS_ERROR_SOURCE_SERVER, CASS_ERROR_SERVER_WRITE_TIMEOUT, 0x1100, "Write timeout") \ 696 XX(CASS_ERROR_SOURCE_SERVER, CASS_ERROR_SERVER_READ_TIMEOUT, 0x1200, "Read timeout") \ 697 XX(CASS_ERROR_SOURCE_SERVER, CASS_ERROR_SERVER_READ_FAILURE, 0x1300, "Read failure") \ 698 XX(CASS_ERROR_SOURCE_SERVER, CASS_ERROR_SERVER_FUNCTION_FAILURE, 0x1400, "Function failure") \ 699 XX(CASS_ERROR_SOURCE_SERVER, CASS_ERROR_SERVER_WRITE_FAILURE, 0x1500, "Write failure") \ 700 XX(CASS_ERROR_SOURCE_SERVER, CASS_ERROR_SERVER_SYNTAX_ERROR, 0x2000, "Syntax error") \ 701 XX(CASS_ERROR_SOURCE_SERVER, CASS_ERROR_SERVER_UNAUTHORIZED, 0x2100, "Unauthorized") \ 702 XX(CASS_ERROR_SOURCE_SERVER, CASS_ERROR_SERVER_INVALID_QUERY, 0x2200, "Invalid query") \ 703 XX(CASS_ERROR_SOURCE_SERVER, CASS_ERROR_SERVER_CONFIG_ERROR, 0x2300, "Configuration error") \ 704 XX(CASS_ERROR_SOURCE_SERVER, CASS_ERROR_SERVER_ALREADY_EXISTS, 0x2400, "Already exists") \ 705 XX(CASS_ERROR_SOURCE_SERVER, CASS_ERROR_SERVER_UNPREPARED, 0x2500, "Unprepared") \ 706 XX(CASS_ERROR_SOURCE_SSL, CASS_ERROR_SSL_INVALID_CERT, 1, "Unable to load certificate") \ 707 XX(CASS_ERROR_SOURCE_SSL, CASS_ERROR_SSL_INVALID_PRIVATE_KEY, 2, "Unable to load private key") \ 708 XX(CASS_ERROR_SOURCE_SSL, CASS_ERROR_SSL_NO_PEER_CERT, 3, "No peer certificate") \ 709 XX(CASS_ERROR_SOURCE_SSL, CASS_ERROR_SSL_INVALID_PEER_CERT, 4, "Invalid peer certificate") \ 710 XX(CASS_ERROR_SOURCE_SSL, CASS_ERROR_SSL_IDENTITY_MISMATCH, 5, "Certificate does not match host or IP address") \ 711 XX(CASS_ERROR_SOURCE_SSL, CASS_ERROR_SSL_PROTOCOL_ERROR, 6, "Protocol error") \ 712 XX(CASS_ERROR_SOURCE_SSL, CASS_ERROR_SSL_CLOSED, 7, "Connection closed") 713 714 /* @cond IGNORE */ 715 #define CASS_ERROR_MAP CASS_ERROR_MAPPING /* Deprecated */ 716 /* @endcond*/ 717 718 #define CASS_ERROR(source, code) ((source << 24) | code) 719 720 typedef enum CassError_ { 721 CASS_OK = 0, 722 #define XX_ERROR(source, name, code, _) name = CASS_ERROR(source, code), 723 CASS_ERROR_MAPPING(XX_ERROR) 724 #undef XX_ERROR 725 /* @cond IGNORE */ 726 CASS_ERROR_LAST_ENTRY 727 /* @endcond*/ 728 } CassError; 729 730 /** 731 * A callback that's notified when the future is set. 732 * 733 * @param[in] message 734 * @param[in] data user defined data provided when the callback 735 * was registered. 736 * 737 * @see cass_future_set_callback() 738 */ 739 typedef void (*CassFutureCallback)(CassFuture* future, 740 void* data); 741 742 /** 743 * Maximum size of a log message 744 */ 745 #define CASS_LOG_MAX_MESSAGE_SIZE 1024 746 747 /** 748 * A log message. 749 */ 750 typedef struct CassLogMessage_ { 751 /** 752 * The millisecond timestamp (since the Epoch) when the message was logged 753 */ 754 cass_uint64_t time_ms; 755 CassLogLevel severity; /**< The severity of the log message */ 756 const char* file; /**< The file where the message was logged */ 757 int line; /**< The line in the file where the message was logged */ 758 const char* function; /**< The function where the message was logged */ 759 char message[CASS_LOG_MAX_MESSAGE_SIZE]; /**< The message */ 760 } CassLogMessage; 761 762 /** 763 * A callback that's used to handle logging. 764 * 765 * @param[in] message 766 * @param[in] data user defined data provided when the callback 767 * was registered. 768 * 769 * @see cass_log_set_callback() 770 */ 771 typedef void (*CassLogCallback)(const CassLogMessage* message, 772 void* data); 773 774 /** 775 * A custom malloc function. This function should allocate "size" bytes and 776 * return a pointer to that memory 777 * 778 * @param[in] size The size of the memory to allocate 779 * 780 * @see CassFreeFunction 781 * @see cass_alloc_set_functions() 782 */ 783 typedef void* (*CassMallocFunction)(size_t size); 784 785 /** 786 * A custom realloc function. This function attempts to change the size of the 787 * memory pointed to by "ptr". If the memory cannot be resized then new memory 788 * should be allocated and contain the contents of the original memory at "ptr". 789 * 790 * @param[in] ptr A pointer to the original memory. If NULL it should behave the 791 * same as "CassMallocFunction" 792 * @param[in] size The size of the memory to allocate/resize. 793 * 794 * @see CassMallocFunction 795 * @see CassFreeFunction 796 * @see cass_alloc_set_functions() 797 */ 798 typedef void* (*CassReallocFunction)(void* ptr, size_t size); 799 800 /** 801 * A custom free function. This function deallocates the memory pointed to by 802 * "ptr" that was previously allocated by a "CassMallocFunction" or 803 * "CassReallocFunction" function. 804 * 805 * @param[in] ptr A pointer to memory that should be deallocated. If NULL then 806 * this will perform no operation. 807 * 808 * @see CassMallocFunction 809 * @see CassReallocFunction 810 * @see cass_alloc_set_functions() 811 */ 812 typedef void (*CassFreeFunction)(void* ptr); 813 814 /** 815 * An authenticator. 816 * 817 * @struct CassAuthenticator 818 */ 819 typedef struct CassAuthenticator_ CassAuthenticator; 820 821 /** 822 * A callback used to initiate an authentication exchange. 823 * 824 * Use cass_authenticator_set_response() to set the response token. 825 * 826 * Use cass_authenticator_set_error() if an error occurred during 827 * initialization. 828 * 829 * @param[in] auth 830 * @param[in] data 831 */ 832 typedef void (*CassAuthenticatorInitialCallback)(CassAuthenticator* auth, 833 void* data); 834 835 /** 836 * A callback used when an authentication challenge initiated 837 * by the server. 838 * 839 * Use cass_authenticator_set_response() to set the response token. 840 * 841 * Use cass_authenticator_set_error() if an error occurred during the 842 * challenge. 843 * 844 * @param[in] auth 845 * @param[in] data 846 * @param[in] token 847 * @param[in] token_size 848 */ 849 typedef void (*CassAuthenticatorChallengeCallback)(CassAuthenticator* auth, 850 void* data, 851 const char* token, 852 size_t token_size); 853 /** 854 * A callback used to indicate the success of the authentication 855 * exchange. 856 * 857 * Use cass_authenticator_set_error() if an error occurred while evaluating 858 * the success token. 859 * 860 * @param[in] auth 861 * @param[in] data 862 * @param[in] token 863 * @param[in] token_size 864 */ 865 typedef void (*CassAuthenticatorSuccessCallback)(CassAuthenticator* auth, 866 void* data, 867 const char* token, 868 size_t token_size); 869 /** 870 * A callback used to cleanup resources that were acquired during 871 * the process of the authentication exchange. This is called after 872 * the termination of the exchange regardless of the outcome. 873 * 874 * @param[in] auth 875 * @param[in] data 876 */ 877 typedef void (*CassAuthenticatorCleanupCallback)(CassAuthenticator* auth, 878 void* data); 879 880 /** 881 * A callback used to cleanup resources. 882 * 883 * @param[in] data 884 */ 885 typedef void (*CassAuthenticatorDataCleanupCallback)(void* data); 886 887 /** 888 * Authenticator callbacks 889 */ 890 typedef struct CassAuthenticatorCallbacks_ { 891 CassAuthenticatorInitialCallback initial_callback; 892 CassAuthenticatorChallengeCallback challenge_callback; 893 CassAuthenticatorSuccessCallback success_callback; 894 CassAuthenticatorCleanupCallback cleanup_callback; 895 } CassAuthenticatorCallbacks; 896 897 typedef enum CassHostListenerEvent_ { 898 CASS_HOST_LISTENER_EVENT_UP, 899 CASS_HOST_LISTENER_EVENT_DOWN, 900 CASS_HOST_LISTENER_EVENT_ADD, 901 CASS_HOST_LISTENER_EVENT_REMOVE 902 } CassHostListenerEvent; 903 904 /** 905 * A callback used to indicate the host state for a node in the cluster. 906 * 907 * @param[in] event 908 * @param[in] address 909 * @param[in] data 910 * @see cass_cluster_set_host_listener_callback() 911 */ 912 typedef void(*CassHostListenerCallback)(CassHostListenerEvent event, 913 const CassInet address, 914 void* data); 915 916 /*********************************************************************************** 917 * 918 * Execution Profile 919 * 920 ***********************************************************************************/ 921 922 /** 923 * An execution profile object provides a mechanism to group together a set of 924 * configuration options and reuse them across different statement executions. 925 * This feature is useful when dealing with different query workloads. 926 * 927 * @struct CassExecProfile 928 */ 929 typedef struct CassExecProfile_ CassExecProfile; 930 931 /** 932 * Creates a new execution profile. 933 * 934 * @public @memberof CassExecProfile 935 * 936 * @return Returns a execution profile that must be freed. 937 * 938 * @see cass_execution_profile_free() 939 */ 940 CASS_EXPORT CassExecProfile* 941 cass_execution_profile_new(); 942 943 /** 944 * Frees a execution profile instance. 945 * 946 * @public @memberof CassExecProfile 947 * 948 * @param[in] profile 949 */ 950 CASS_EXPORT void 951 cass_execution_profile_free(CassExecProfile* profile); 952 953 /** 954 * Sets the timeout waiting for a response from a node. 955 * 956 * <b>Default:</b> Disabled (uses the cluster request timeout) 957 * 958 * @public @memberof CassExecProfile 959 * 960 * @param[in] profile 961 * @param[in] timeout_ms Request timeout in milliseconds. Use 0 for no timeout 962 * or CASS_UINT64_MAX to disable. 963 * @return CASS_OK if successful, otherwise an error occurred. 964 * 965 * @see cass_statement_set_request_timeout() 966 */ 967 CASS_EXPORT CassError 968 cass_execution_profile_set_request_timeout(CassExecProfile* profile, 969 cass_uint64_t timeout_ms); 970 971 /** 972 * Sets the consistency level. 973 * 974 * <b>Default:</b> Disabled (uses the default consistency) 975 * 976 * @public @memberof CassExecProfile 977 * 978 * @param[in] profile 979 * @param[in] consistency 980 * @return CASS_OK if successful, otherwise an error occurred. 981 * 982 * @see cass_statement_set_consistency() 983 */ 984 CASS_EXPORT CassError 985 cass_execution_profile_set_consistency(CassExecProfile* profile, 986 CassConsistency consistency); 987 988 /** 989 * Sets the serial consistency level. 990 * 991 * <b>Default:</b> Disabled (uses the default serial consistency) 992 * 993 * @public @memberof CassExecProfile 994 * 995 * @param[in] profile 996 * @param[in] serial_consistency 997 * @return CASS_OK if successful, otherwise an error occurred. 998 * 999 * @see cass_statement_set_serial_consistency() 1000 */ 1001 CASS_EXPORT CassError 1002 cass_execution_profile_set_serial_consistency(CassExecProfile* profile, 1003 CassConsistency serial_consistency); 1004 1005 /** 1006 * Configures the execution profile to use round-robin load balancing. 1007 * 1008 * The driver discovers all nodes in a cluster and cycles through 1009 * them per request. All are considered 'local'. 1010 * 1011 * <b>Note:</b> Profile-based load balancing policy is disabled by default; 1012 * cluster load balancing policy is used when profile does not contain a policy. 1013 * 1014 * @public @memberof CassExecProfile 1015 * 1016 * @param[in] profile 1017 * @return CASS_OK if successful, otherwise an error occurred. 1018 * 1019 * @see cass_cluster_set_load_balance_round_robin() 1020 */ 1021 CASS_EXPORT CassError 1022 cass_execution_profile_set_load_balance_round_robin(CassExecProfile* profile); 1023 1024 /** 1025 * Configures the execution profile to use DC-aware load balancing. 1026 * For each query, all live nodes in a primary 'local' DC are tried first, 1027 * followed by any node from other DCs. 1028 * 1029 * <b>Note:</b> Profile-based load balancing policy is disabled by default; 1030 * cluster load balancing policy is used when profile does not contain a policy. 1031 * 1032 * @deprecated The remote DC settings for DC-aware are not suitable for most 1033 * scenarios that require DC failover. There is also unhandled gap between 1034 * replication factor number of nodes failing and the full cluster failing. Only 1035 * the remote DC settings are being deprecated. 1036 * 1037 * @public @memberof CassExecProfile 1038 * 1039 * @param[in] profile 1040 * @param[in] local_dc The primary data center to try first 1041 * @param[in] used_hosts_per_remote_dc The number of hosts used in each remote 1042 * DC if no hosts are available in the local dc (<b>deprecated</b>) 1043 * @param[in] allow_remote_dcs_for_local_cl Allows remote hosts to be used if no 1044 * local dc hosts are available and the consistency level is LOCAL_ONE or 1045 * LOCAL_QUORUM (<b>deprecated</b>) 1046 * @return CASS_OK if successful, otherwise an error occurred. 1047 * 1048 * @see cass_cluster_set_load_balance_dc_aware() 1049 */ 1050 CASS_EXPORT CassError 1051 cass_execution_profile_set_load_balance_dc_aware(CassExecProfile* profile, 1052 const char* local_dc, 1053 unsigned used_hosts_per_remote_dc, 1054 cass_bool_t allow_remote_dcs_for_local_cl); 1055 1056 /** 1057 * Same as cass_execution_profile_set_load_balance_dc_aware(), but with lengths 1058 * for string parameters. 1059 * 1060 * @deprecated The remote DC settings for DC-aware are not suitable for most 1061 * scenarios that require DC failover. There is also unhandled gap between 1062 * replication factor number of nodes failing and the full cluster failing. Only 1063 * the remote DC settings are being deprecated. 1064 * 1065 * @public @memberof CassExecProfile 1066 * 1067 * @param[in] profile 1068 * @param[in] local_dc 1069 * @param[in] local_dc_length 1070 * @param[in] used_hosts_per_remote_dc (<b>deprecated</b>) 1071 * @param[in] allow_remote_dcs_for_local_cl (<b>deprecated</b>) 1072 * @return same as cass_execution_profile_set_load_balance_dc_aware() 1073 * 1074 * @see cass_execution_profile_set_load_balance_dc_aware() 1075 * @see cass_cluster_set_load_balance_dc_aware_n() 1076 */ 1077 CASS_EXPORT CassError 1078 cass_execution_profile_set_load_balance_dc_aware_n(CassExecProfile* profile, 1079 const char* local_dc, 1080 size_t local_dc_length, 1081 unsigned used_hosts_per_remote_dc, 1082 cass_bool_t allow_remote_dcs_for_local_cl); 1083 1084 /** 1085 * Configures the execution profile to use token-aware request routing or not. 1086 * 1087 * <b>Important:</b> Token-aware routing depends on keyspace metadata. 1088 * For this reason enabling token-aware routing will also enable retrieving 1089 * and updating keyspace schema metadata. 1090 * 1091 * <b>Default:</b> cass_true (enabled). 1092 * 1093 * This routing policy composes the base routing policy, routing 1094 * requests first to replicas on nodes considered 'local' by 1095 * the base load balancing policy. 1096 * 1097 * <b>Note:</b> Execution profiles use the cluster-level load balancing policy 1098 * unless enabled. This setting is not applicable unless a load balancing policy 1099 * is enabled on the execution profile. 1100 * 1101 * @public @memberof CassExecProfile 1102 * 1103 * @param[in] profile 1104 * @param[in] enabled 1105 * @return CASS_OK if successful, otherwise an error occurred. 1106 * 1107 * @see cass_cluster_set_token_aware_routing() 1108 */ 1109 CASS_EXPORT CassError 1110 cass_execution_profile_set_token_aware_routing(CassExecProfile* profile, 1111 cass_bool_t enabled); 1112 1113 /** 1114 * Configures the execution profile's token-aware routing to randomly shuffle 1115 * replicas. This can reduce the effectiveness of server-side caching, but it 1116 * can better distribute load over replicas for a given partition key. 1117 * 1118 * <b>Note:</b> Token-aware routing must be enabled and a load balancing policy 1119 * must be enabled on the execution profile for the setting to be applicable. 1120 * 1121 * <b>Default:</b> cass_true (enabled). 1122 * 1123 * @public @memberof CassExecProfile 1124 * 1125 * @param[in] profile 1126 * @param[in] enabled 1127 * @return CASS_OK if successful, otherwise an error occurred. 1128 * 1129 * @see cass_cluster_set_token_aware_routing_shuffle_replicas() 1130 */ 1131 CASS_EXPORT CassError 1132 cass_execution_profile_set_token_aware_routing_shuffle_replicas(CassExecProfile* profile, 1133 cass_bool_t enabled); 1134 1135 /** 1136 * Configures the execution profile to use latency-aware request routing or not. 1137 * 1138 * <b>Note:</b> Execution profiles use the cluster-level load balancing policy 1139 * unless enabled. This setting is not applicable unless a load balancing policy 1140 * is enabled on the execution profile. 1141 * 1142 * <b>Default:</b> cass_false (disabled). 1143 * 1144 * This routing policy is a top-level routing policy. It uses the 1145 * base routing policy to determine locality (dc-aware) and/or 1146 * placement (token-aware) before considering the latency. 1147 * 1148 * @public @memberof CassExecProfile 1149 * 1150 * @param[in] profile 1151 * @param[in] enabled 1152 * @return CASS_OK if successful, otherwise an error occurred. 1153 * 1154 * @see cass_cluster_set_latency_aware_routing() 1155 */ 1156 CASS_EXPORT CassError 1157 cass_execution_profile_set_latency_aware_routing(CassExecProfile* profile, 1158 cass_bool_t enabled); 1159 1160 /** 1161 * Configures the execution profile's settings for latency-aware request 1162 * routing. 1163 * 1164 * <b>Note:</b> Execution profiles use the cluster-level load balancing policy 1165 * unless enabled. This setting is not applicable unless a load balancing policy 1166 * is enabled on the execution profile. 1167 * 1168 * <b>Defaults:</b> 1169 * 1170 * <ul> 1171 * <li>exclusion_threshold: 2.0</li> 1172 * <li>scale_ms: 100 milliseconds</li> 1173 * <li>retry_period_ms: 10,000 milliseconds (10 seconds)</li> 1174 * <li>update_rate_ms: 100 milliseconds</li> 1175 * <li>min_measured: 50</li> 1176 * </ul> 1177 * 1178 * @public @memberof CassExecProfile 1179 * 1180 * @param[in] profile 1181 * @param[in] exclusion_threshold Controls how much worse the latency must be 1182 * compared to the average latency of the best performing node before it 1183 * penalized. 1184 * @param[in] scale_ms Controls the weight given to older latencies when 1185 * calculating the average latency of a node. A bigger scale will give more 1186 * weight to older latency measurements. 1187 * @param[in] retry_period_ms The amount of time a node is penalized by the 1188 * policy before being given a second chance when the current average latency 1189 * exceeds the calculated threshold 1190 * (exclusion_threshold * best_average_latency). 1191 * @param[in] update_rate_ms The rate at which the best average latency is 1192 * recomputed. 1193 * @param[in] min_measured The minimum number of measurements per-host required 1194 * to be considered by the policy. 1195 * @return CASS_OK if successful, otherwise an error occurred. 1196 * 1197 * @see cass_cluster_set_latency_aware_routing_settings() 1198 */ 1199 CASS_EXPORT CassError 1200 cass_execution_profile_set_latency_aware_routing_settings(CassExecProfile* profile, 1201 cass_double_t exclusion_threshold, 1202 cass_uint64_t scale_ms, 1203 cass_uint64_t retry_period_ms, 1204 cass_uint64_t update_rate_ms, 1205 cass_uint64_t min_measured); 1206 1207 /** 1208 * Sets/Appends whitelist hosts for the execution profile. The first call sets 1209 * the whitelist hosts and any subsequent calls appends additional hosts. 1210 * Passing an empty string will clear and disable the whitelist. White space is 1211 * striped from the hosts. 1212 * 1213 * This policy filters requests to all other policies, only allowing requests 1214 * to the hosts contained in the whitelist. Any host not in the whitelist will 1215 * be ignored and a connection will not be established. This policy is useful 1216 * for ensuring that the driver will only connect to a predefined set of hosts. 1217 * 1218 * Examples: "127.0.0.1" "127.0.0.1,127.0.0.2" 1219 * 1220 * <b>Note:</b> Execution profiles use the cluster-level load balancing policy 1221 * unless enabled. This setting is not applicable unless a load balancing policy 1222 * is enabled on the execution profile. 1223 * 1224 * @public @memberof CassExecProfile 1225 * 1226 * @param[in] profile 1227 * @param[in] hosts A comma delimited list of addresses. An empty string will 1228 * clear the whitelist hosts. The string is copied into the cluster 1229 * configuration; the memory pointed to by this parameter can be freed after 1230 * this call. 1231 * @return CASS_OK if successful, otherwise an error occurred. 1232 * 1233 * @see cass_cluster_set_whitelist_filtering() 1234 */ 1235 CASS_EXPORT CassError 1236 cass_execution_profile_set_whitelist_filtering(CassExecProfile* profile, 1237 const char* hosts); 1238 1239 /** 1240 * Same as cass_execution_profile_set_whitelist_filtering(), but with lengths 1241 * for string parameters. 1242 * 1243 * @public @memberof CassExecProfile 1244 * 1245 * @param[in] profile 1246 * @param[in] hosts 1247 * @param[in] hosts_length 1248 * @return same as cass_execution_profile_set_whitelist_filtering() 1249 * 1250 * @see cass_execution_profile_set_whitelist_filtering() 1251 * @see cass_cluster_set_whitelist_filtering() 1252 */ 1253 CASS_EXPORT CassError 1254 cass_execution_profile_set_whitelist_filtering_n(CassExecProfile* profile, 1255 const char* hosts, 1256 size_t hosts_length); 1257 1258 /** 1259 * Sets/Appends blacklist hosts for the execution profile. The first call sets 1260 * the blacklist hosts and any subsequent calls appends additional hosts. 1261 * Passing an empty string will clear and disable the blacklist. White space is 1262 * striped from the hosts. 1263 * 1264 * This policy filters requests to all other policies, only allowing requests 1265 * to the hosts not contained in the blacklist. Any host in the blacklist will 1266 * be ignored and a connection will not be established. This policy is useful 1267 * for ensuring that the driver will not connect to a predefined set of hosts. 1268 * 1269 * Examples: "127.0.0.1" "127.0.0.1,127.0.0.2" 1270 * 1271 * <b>Note:</b> Execution profiles use the cluster-level load balancing policy 1272 * unless enabled. This setting is not applicable unless a load balancing policy 1273 * is enabled on the execution profile. 1274 * 1275 * @public @memberof CassExecProfile 1276 * 1277 * @param[in] profile 1278 * @param[in] hosts A comma delimited list of addresses. An empty string will 1279 * clear the blacklist hosts. The string is copied into the cluster 1280 * configuration; the memory pointed to by this parameter can be freed after 1281 * this call. 1282 * @return CASS_OK if successful, otherwise an error occurred. 1283 * 1284 * @see cass_cluster_set_blacklist_filtering() 1285 */ 1286 CASS_EXPORT CassError 1287 cass_execution_profile_set_blacklist_filtering(CassExecProfile* profile, 1288 const char* hosts); 1289 1290 /** 1291 * Same as cass_execution_profile_set_blacklist_filtering(), but with lengths 1292 * for string parameters. 1293 * 1294 * @public @memberof CassExecProfile 1295 * 1296 * @param[in] profile 1297 * @param[in] hosts 1298 * @param[in] hosts_length 1299 * @return same as cass_execution_profile_set_blacklist_filtering_hosts() 1300 * 1301 * @see cass_execution_profile_set_blacklist_filtering() 1302 * @see cass_cluster_set_blacklist_filtering() 1303 */ 1304 CASS_EXPORT CassError 1305 cass_execution_profile_set_blacklist_filtering_n(CassExecProfile* profile, 1306 const char* hosts, 1307 size_t hosts_length); 1308 1309 /** 1310 * Same as cass_execution_profile_set_whitelist_filtering(), but whitelist all 1311 * hosts of a dc. 1312 * 1313 * Examples: "dc1", "dc1,dc2" 1314 * 1315 * @public @memberof CassExecProfile 1316 * 1317 * @param[in] profile 1318 * @param[in] dcs A comma delimited list of dcs. An empty string will clear the 1319 * whitelist dcs. The string is copied into the cluster configuration; the 1320 * memory pointed to by this parameter can be freed after this call. 1321 * @return CASS_OK if successful, otherwise an error occurred. 1322 * 1323 * @see cass_cluster_set_whitelist_dc_filtering() 1324 */ 1325 CASS_EXPORT CassError 1326 cass_execution_profile_set_whitelist_dc_filtering(CassExecProfile* profile, 1327 const char* dcs); 1328 1329 /** 1330 * Same as cass_execution_profile_set_whitelist_dc_filtering(), but with lengths 1331 * for string parameters. 1332 * 1333 * @public @memberof CassExecProfile 1334 * 1335 * @param[in] profile 1336 * @param[in] dcs 1337 * @param[in] dcs_length 1338 * @return same as cass_execution_profile_set_whitelist_dc_filtering() 1339 * 1340 * @see cass_execution_profile_set_whitelist_dc_filtering() 1341 * @see cass_cluster_set_whitelist_dc_filtering() 1342 */ 1343 CASS_EXPORT CassError 1344 cass_execution_profile_set_whitelist_dc_filtering_n(CassExecProfile* profile, 1345 const char* dcs, 1346 size_t dcs_length); 1347 1348 /** 1349 * Same as cass_execution_profile_set_blacklist_filtering(), but blacklist all 1350 * hosts of a dc. 1351 * 1352 * Examples: "dc1", "dc1,dc2" 1353 * 1354 * @public @memberof CassExecProfile 1355 * 1356 * @param[in] profile 1357 * @param[in] dcs A comma delimited list of dcs. An empty string will clear the 1358 * blacklist dcs. The string is copied into the cluster configuration; the 1359 * memory pointed to by this parameter can be freed after this call. 1360 * @return CASS_OK if successful, otherwise an error occurred. 1361 * 1362 * @see cass_execution_profile_set_blacklist_filtering() 1363 * @see cass_cluster_set_blacklist_dc_filtering() 1364 */ 1365 CASS_EXPORT CassError 1366 cass_execution_profile_set_blacklist_dc_filtering(CassExecProfile* profile, 1367 const char* dcs); 1368 1369 /** 1370 * Same as cass_execution_profile_set_blacklist_dc_filtering(), but with lengths 1371 * for string parameters. 1372 * 1373 * @public @memberof CassExecProfile 1374 * 1375 * @param[in] profile 1376 * @param[in] dcs 1377 * @param[in] dcs_length 1378 * @return same as cass_execution_profile_set_blacklist_dc_filtering() 1379 * 1380 * @see cass_execution_profile_set_blacklist_dc_filtering() 1381 * @see cass_cluster_set_blacklist_dc_filtering() 1382 */ 1383 CASS_EXPORT CassError 1384 cass_execution_profile_set_blacklist_dc_filtering_n(CassExecProfile* profile, 1385 const char* dcs, 1386 size_t dcs_length); 1387 1388 /** 1389 * Sets the execution profile's retry policy. 1390 * 1391 * <b>Note:</b> Profile-based retry policy is disabled by default; cluster retry 1392 * policy is used when profile does not contain a policy unless the retry policy 1393 * was explicitly set on the batch/statement request. 1394 * 1395 * @public @memberof CassExecProfile 1396 * 1397 * @param[in] profile 1398 * @param[in] retry_policy NULL will clear retry policy from execution profile 1399 * @return CASS_OK if successful, otherwise an error occurred. 1400 * 1401 * @see cass_cluster_set_retry_policy() 1402 */ 1403 CASS_EXPORT CassError 1404 cass_execution_profile_set_retry_policy(CassExecProfile* profile, 1405 CassRetryPolicy* retry_policy); 1406 1407 /** 1408 * Enable constant speculative executions with the supplied settings for the 1409 * execution profile. 1410 * 1411 * <b>Note:</b> Profile-based speculative execution policy is disabled by 1412 * default; cluster speculative execution policy is used when profile does not 1413 * contain a policy. 1414 * 1415 * @public @memberof CassExecProfile 1416 * 1417 * @param[in] profile 1418 * @param[in] constant_delay_ms 1419 * @param[in] max_speculative_executions 1420 * @return CASS_OK if successful, otherwise an error occurred 1421 * 1422 * @see cass_cluster_set_constant_speculative_execution_policy() 1423 */ 1424 CASS_EXPORT CassError 1425 cass_execution_profile_set_constant_speculative_execution_policy(CassExecProfile* profile, 1426 cass_int64_t constant_delay_ms, 1427 int max_speculative_executions); 1428 1429 /** 1430 * Disable speculative executions for the execution profile. 1431 * 1432 * <b>Note:</b> Profile-based speculative execution policy is disabled by 1433 * default; cluster speculative execution policy is used when profile does not 1434 * contain a policy. 1435 * 1436 * @public @memberof CassExecProfile 1437 * 1438 * @param[in] profile 1439 * @return CASS_OK if successful, otherwise an error occurred 1440 * 1441 * @see cass_cluster_set_no_speculative_execution_policy() 1442 */ 1443 CASS_EXPORT CassError 1444 cass_execution_profile_set_no_speculative_execution_policy(CassExecProfile* profile); 1445 1446 /*********************************************************************************** 1447 * 1448 * Cluster 1449 * 1450 ***********************************************************************************/ 1451 1452 /** 1453 * Creates a new cluster. 1454 * 1455 * @public @memberof CassCluster 1456 * 1457 * @return Returns a cluster that must be freed. 1458 * 1459 * @see cass_cluster_free() 1460 */ 1461 CASS_EXPORT CassCluster* 1462 cass_cluster_new(); 1463 1464 /** 1465 * Frees a cluster instance. 1466 * 1467 * @public @memberof CassCluster 1468 * 1469 * @param[in] cluster 1470 */ 1471 CASS_EXPORT void 1472 cass_cluster_free(CassCluster* cluster); 1473 1474 /** 1475 * Sets/Appends contact points. This *MUST* be set. The first call sets 1476 * the contact points and any subsequent calls appends additional contact 1477 * points. Passing an empty string will clear the contact points. White space 1478 * is striped from the contact points. 1479 * 1480 * Examples: "127.0.0.1" "127.0.0.1,127.0.0.2", "server1.domain.com" 1481 * 1482 * @public @memberof CassCluster 1483 * 1484 * @param[in] cluster 1485 * @param[in] contact_points A comma delimited list of addresses or 1486 * names. An empty string will clear the contact points. 1487 * The string is copied into the cluster configuration; the memory pointed 1488 * to by this parameter can be freed after this call. 1489 * @return CASS_OK if successful, otherwise an error occurred. 1490 */ 1491 CASS_EXPORT CassError 1492 cass_cluster_set_contact_points(CassCluster* cluster, 1493 const char* contact_points); 1494 1495 /** 1496 * Same as cass_cluster_set_contact_points(), but with lengths for string 1497 * parameters. 1498 * 1499 * @public @memberof CassCluster 1500 * 1501 * @param[in] cluster 1502 * @param[in] contact_points 1503 * @param[in] contact_points_length 1504 * @return same as cass_cluster_set_contact_points() 1505 * 1506 * @see cass_cluster_set_contact_points() 1507 */ 1508 CASS_EXPORT CassError 1509 cass_cluster_set_contact_points_n(CassCluster* cluster, 1510 const char* contact_points, 1511 size_t contact_points_length); 1512 1513 /** 1514 * Sets the port. 1515 * 1516 * <b>Default:</b> 9042 1517 * 1518 * @public @memberof CassCluster 1519 * 1520 * @param[in] cluster 1521 * @param[in] port 1522 * @return CASS_OK if successful, otherwise an error occurred. 1523 */ 1524 CASS_EXPORT CassError 1525 cass_cluster_set_port(CassCluster* cluster, 1526 int port); 1527 1528 /** 1529 * Sets the local address to bind when connecting to the cluster, 1530 * if desired. 1531 * 1532 * @public @memberof CassCluster 1533 * 1534 * @param[in] cluster 1535 * @param[in] name IP address to bind, or empty string for no binding. 1536 * Only numeric addresses are supported; no resolution is done. 1537 * @return CASS_OK if successful, otherwise an error occurred. 1538 */ 1539 CASS_EXPORT CassError 1540 cass_cluster_set_local_address(CassCluster* cluster, 1541 const char* name); 1542 1543 /** 1544 * Same as cass_cluster_set_local_address(), but with lengths for string 1545 * parameters. 1546 * 1547 * @public @memberof CassCluster 1548 * 1549 * @param[in] cluster 1550 * @param[in] name 1551 * @param[in] name_length 1552 * @return same as cass_cluster_set_local_address() 1553 * 1554 * @see cass_cluster_set_local_address() 1555 */ 1556 CASS_EXPORT CassError 1557 cass_cluster_set_local_address_n(CassCluster* cluster, 1558 const char* name, 1559 size_t name_length); 1560 1561 /** 1562 * Sets the SSL context and enables SSL. 1563 * 1564 * @public @memberof CassCluster 1565 * 1566 * @param[in] cluster 1567 * @param[in] ssl 1568 * 1569 * @see cass_ssl_new() 1570 */ 1571 CASS_EXPORT void 1572 cass_cluster_set_ssl(CassCluster* cluster, 1573 CassSsl* ssl); 1574 1575 /** 1576 * Sets custom authenticator 1577 * 1578 * @public @memberof CassCluster 1579 * 1580 * @param[in] cluster 1581 * @param[in] exchange_callbacks 1582 * @param[in] cleanup_callback 1583 * @param[in] data 1584 * @return CASS_OK if successful, otherwise an error occurred. 1585 */ 1586 CASS_EXPORT CassError 1587 cass_cluster_set_authenticator_callbacks(CassCluster* cluster, 1588 const CassAuthenticatorCallbacks* exchange_callbacks, 1589 CassAuthenticatorDataCleanupCallback cleanup_callback, 1590 void* data); 1591 1592 /** 1593 * Sets the protocol version. The driver will automatically downgrade to the lowest 1594 * supported protocol version. 1595 * 1596 * <b>Default:</b> CASS_PROTOCOL_VERSION_V4 or CASS_PROTOCOL_VERSION_DSEV1 when 1597 * using the DSE driver with DataStax Enterprise. 1598 * 1599 * @public @memberof CassCluster 1600 * 1601 * @param[in] cluster 1602 * @param[in] protocol_version 1603 * @return CASS_OK if successful, otherwise an error occurred. 1604 * 1605 * @see cass_cluster_set_use_beta_protocol_version() 1606 */ 1607 CASS_EXPORT CassError 1608 cass_cluster_set_protocol_version(CassCluster* cluster, 1609 int protocol_version); 1610 1611 /** 1612 * Use the newest beta protocol version. This currently enables the use of 1613 * protocol version v5 (CASS_PROTOCOL_VERSION_V5) or DSEv2 (CASS_PROTOCOL_VERSION_DSEV2) 1614 * when using the DSE driver with DataStax Enterprise. 1615 * 1616 * <b>Default:</b> cass_false 1617 * 1618 * @public @memberof CassCluster 1619 * 1620 * @param[in] cluster 1621 * @param[in] enable if false the highest non-beta protocol version will be used 1622 * @return CASS_OK if successful, otherwise an error occurred. 1623 */ 1624 CASS_EXPORT CassError 1625 cass_cluster_set_use_beta_protocol_version(CassCluster* cluster, 1626 cass_bool_t enable); 1627 1628 /** 1629 * Sets default consistency level of statement. 1630 * 1631 * <b>Default:</b> CASS_CONSISTENCY_LOCAL_ONE 1632 * 1633 * @public @memberof CassCluster 1634 * 1635 * @param[in] cluster 1636 * @param[in] consistency 1637 * @return CASS_OK if successful, otherwise an error occurred. 1638 */ 1639 CASS_EXPORT CassError 1640 cass_cluster_set_consistency(CassCluster* cluster, 1641 CassConsistency consistency); 1642 1643 /** 1644 * Sets default serial consistency level of statement. 1645 * 1646 * <b>Default:</b> CASS_CONSISTENCY_ANY 1647 * 1648 * @public @memberof CassCluster 1649 * 1650 * @param[in] cluster 1651 * @param[in] consistency 1652 * @return CASS_OK if successful, otherwise an error occurred. 1653 */ 1654 CASS_EXPORT CassError 1655 cass_cluster_set_serial_consistency(CassCluster* cluster, 1656 CassConsistency consistency); 1657 1658 /** 1659 * Sets the number of IO threads. This is the number of threads 1660 * that will handle query requests. 1661 * 1662 * <b>Default:</b> 1 1663 * 1664 * @public @memberof CassCluster 1665 * 1666 * @param[in] cluster 1667 * @param[in] num_threads 1668 * @return CASS_OK if successful, otherwise an error occurred. 1669 */ 1670 CASS_EXPORT CassError 1671 cass_cluster_set_num_threads_io(CassCluster* cluster, 1672 unsigned num_threads); 1673 1674 /** 1675 * Sets the size of the fixed size queue that stores 1676 * pending requests. 1677 * 1678 * <b>Default:</b> 8192 1679 * 1680 * @public @memberof CassCluster 1681 * 1682 * @param[in] cluster 1683 * @param[in] queue_size 1684 * @return CASS_OK if successful, otherwise an error occurred. 1685 */ 1686 CASS_EXPORT CassError 1687 cass_cluster_set_queue_size_io(CassCluster* cluster, 1688 unsigned queue_size); 1689 1690 /** 1691 * Sets the size of the fixed size queue that stores 1692 * events. 1693 * 1694 * <b>Default:</b> 8192 1695 * 1696 * @public @memberof CassCluster 1697 * 1698 * @deprecated This is no longer useful and does nothing. Expect this to be 1699 * removed in a future release. 1700 * 1701 * @param[in] cluster 1702 * @param[in] queue_size 1703 * @return CASS_OK if successful, otherwise an error occurred. 1704 */ 1705 CASS_EXPORT CASS_DEPRECATED(CassError 1706 cass_cluster_set_queue_size_event(CassCluster* cluster, 1707 unsigned queue_size)); 1708 1709 /** 1710 * Sets the number of connections made to each server in each 1711 * IO thread. 1712 * 1713 * <b>Default:</b> 1 1714 * 1715 * @public @memberof CassCluster 1716 * 1717 * @param[in] cluster 1718 * @param[in] num_connections 1719 * @return CASS_OK if successful, otherwise an error occurred. 1720 */ 1721 CASS_EXPORT CassError 1722 cass_cluster_set_core_connections_per_host(CassCluster* cluster, 1723 unsigned num_connections); 1724 1725 /** 1726 * Sets the maximum number of connections made to each server in each 1727 * IO thread. 1728 * 1729 * <b>Default:</b> 2 1730 * 1731 * @public @memberof CassCluster 1732 * 1733 * @deprecated This is no longer useful and does nothing. Expect this to be 1734 * removed in a future release. 1735 * 1736 * @param[in] cluster 1737 * @param[in] num_connections 1738 * @return CASS_OK if successful, otherwise an error occurred. 1739 */ 1740 CASS_EXPORT CASS_DEPRECATED(CassError 1741 cass_cluster_set_max_connections_per_host(CassCluster* cluster, 1742 unsigned num_connections)); 1743 1744 /** 1745 * Sets the amount of time to wait before attempting to reconnect. 1746 * 1747 * @public @memberof CassCluster 1748 * 1749 * @deprecated This is being replaced with cass_cluster_set_constant_reconnect(). 1750 * Expect this to be removed in a future release. 1751 * 1752 * @param[in] cluster 1753 * @param[in] wait_time 1754 */ 1755 CASS_EXPORT CASS_DEPRECATED(void 1756 cass_cluster_set_reconnect_wait_time(CassCluster* cluster, 1757 unsigned wait_time)); 1758 1759 /** 1760 * Configures the cluster to use a reconnection policy that waits a constant 1761 * time between each reconnection attempt. 1762 * 1763 * @public @memberof CassCluster 1764 * 1765 * @param[in] cluster 1766 * @param[in] delay_ms Time in milliseconds to delay attempting a reconnection; 1767 * 0 to perform a reconnection immediately. 1768 */ 1769 CASS_EXPORT void 1770 cass_cluster_set_constant_reconnect(CassCluster* cluster, 1771 cass_uint64_t delay_ms); 1772 1773 /** 1774 * Configures the cluster to use a reconnection policy that waits exponentially 1775 * longer between each reconnection attempt; however will maintain a constant 1776 * delay once the maximum delay is reached. 1777 * 1778 * <b>Default:</b> 1779 * <ul> 1780 * <li>2000 milliseconds base delay</li> 1781 * <li>60000 milliseconds max delay</li> 1782 * </ul> 1783 * 1784 * <p> 1785 * <b>Note:</b> A random amount of jitter (+/- 15%) will be added to the pure 1786 * exponential delay value. This helps to prevent situations where multiple 1787 * connections are in the reconnection process at exactly the same time. The 1788 * jitter will never cause the delay to be less than the base delay, or more 1789 * than the max delay. 1790 * </p> 1791 * 1792 * @public @memberof CassCluster 1793 * 1794 * @param[in] cluster 1795 * @param[in] base_delay_ms The base delay (in milliseconds) to use for 1796 * scheduling reconnection attempts. 1797 * @param[in] max_delay_ms The maximum delay to wait between two reconnection 1798 * attempts. 1799 * @return CASS_OK if successful, otherwise error occurred. 1800 */ 1801 CASS_EXPORT CassError 1802 cass_cluster_set_exponential_reconnect(CassCluster* cluster, 1803 cass_uint64_t base_delay_ms, 1804 cass_uint64_t max_delay_ms); 1805 1806 /** 1807 * Sets the amount of time, in microseconds, to wait for new requests to 1808 * coalesce into a single system call. This should be set to a value around 1809 * the latency SLA of your application's requests while also considering the 1810 * request's roundtrip time. Larger values should be used for throughput 1811 * bound workloads and lower values should be used for latency bound 1812 * workloads. 1813 * 1814 * <b>Default:</b> 200 us 1815 * 1816 * @public @memberof CassCluster 1817 * 1818 * @param[in] cluster 1819 * @param[in] delay_us 1820 * @return CASS_OK if successful, otherwise an error occurred. 1821 */ 1822 CASS_EXPORT CassError 1823 cass_cluster_set_coalesce_delay(CassCluster* cluster, 1824 cass_int64_t delay_us); 1825 1826 /** 1827 * Sets the ratio of time spent processing new requests versus handling the I/O 1828 * and processing of outstanding requests. The range of this setting is 1 to 100, 1829 * where larger values allocate more time to processing new requests and smaller 1830 * values allocate more time to processing outstanding requests. 1831 * 1832 * <b>Default:</b> 50 1833 * 1834 * @public @memberof CassCluster 1835 * 1836 * @param[in] cluster 1837 * @param[in] ratio 1838 * @return CASS_OK if successful, otherwise an error occurred. 1839 */ 1840 CASS_EXPORT CassError 1841 cass_cluster_set_new_request_ratio(CassCluster* cluster, 1842 cass_int32_t ratio); 1843 1844 /** 1845 * Sets the maximum number of connections that will be created concurrently. 1846 * Connections are created when the current connections are unable to keep up with 1847 * request throughput. 1848 * 1849 * <b>Default:</b> 1 1850 * 1851 * @public @memberof CassCluster 1852 * 1853 * @deprecated This is no longer useful and does nothing. Expect this to be 1854 * removed in a future release. 1855 * 1856 * @param[in] cluster 1857 * @param[in] num_connections 1858 * @return CASS_OK if successful, otherwise an error occurred. 1859 */ 1860 CASS_EXPORT CASS_DEPRECATED(CassError 1861 cass_cluster_set_max_concurrent_creation(CassCluster* cluster, 1862 unsigned num_connections)); 1863 1864 /** 1865 * Sets the threshold for the maximum number of concurrent requests in-flight 1866 * on a connection before creating a new connection. The number of new connections 1867 * created will not exceed max_connections_per_host. 1868 * 1869 * <b>Default:</b> 100 1870 * 1871 * @public @memberof CassCluster 1872 * 1873 * @deprecated This is no longer useful and does nothing. Expect this to be 1874 * removed in a future release. 1875 * 1876 * @param[in] cluster 1877 * @param[in] num_requests 1878 * @return CASS_OK if successful, otherwise an error occurred. 1879 */ 1880 CASS_EXPORT CASS_DEPRECATED(CassError 1881 cass_cluster_set_max_concurrent_requests_threshold(CassCluster* cluster, 1882 unsigned num_requests)); 1883 1884 /** 1885 * Sets the maximum number of requests processed by an IO worker 1886 * per flush. 1887 * 1888 * <b>Default:</b> 128 1889 * 1890 * @public @memberof CassCluster 1891 * 1892 * @deprecated This is no longer useful and does nothing. Expect this to be 1893 * removed in a future release. 1894 * 1895 * @param[in] cluster 1896 * @param[in] num_requests 1897 * @return CASS_OK if successful, otherwise an error occurred. 1898 */ 1899 CASS_EXPORT CASS_DEPRECATED(CassError 1900 cass_cluster_set_max_requests_per_flush(CassCluster* cluster, 1901 unsigned num_requests)); 1902 1903 /** 1904 * Sets the high water mark for the number of bytes outstanding 1905 * on a connection. Disables writes to a connection if the number 1906 * of bytes queued exceed this value. 1907 * 1908 * <b>Default:</b> 64 KB 1909 * 1910 * @public @memberof CassCluster 1911 * 1912 * @deprecated This is no longer useful and does nothing. Expect this to be 1913 * removed in a future release. 1914 * 1915 * @param[in] cluster 1916 * @param[in] num_bytes 1917 * @return CASS_OK if successful, otherwise an error occurred. 1918 */ 1919 CASS_EXPORT CASS_DEPRECATED(CassError 1920 cass_cluster_set_write_bytes_high_water_mark(CassCluster* cluster, 1921 unsigned num_bytes)); 1922 1923 /** 1924 * Sets the low water mark for number of bytes outstanding on a 1925 * connection. After exceeding high water mark bytes, writes will 1926 * only resume once the number of bytes fall below this value. 1927 * 1928 * <b>Default:</b> 32 KB 1929 * 1930 * @public @memberof CassCluster 1931 * 1932 * @deprecated This is no longer useful and does nothing. Expect this to be 1933 * removed in a future release. 1934 * 1935 * @param[in] cluster 1936 * @param[in] num_bytes 1937 * @return CASS_OK if successful, otherwise an error occurred. 1938 */ 1939 CASS_EXPORT CASS_DEPRECATED(CassError 1940 cass_cluster_set_write_bytes_low_water_mark(CassCluster* cluster, 1941 unsigned num_bytes)); 1942 1943 /** 1944 * Sets the high water mark for the number of requests queued waiting 1945 * for a connection in a connection pool. Disables writes to a 1946 * host on an IO worker if the number of requests queued exceed this 1947 * value. 1948 * 1949 * <b>Default:</b> 256 1950 * 1951 * @public @memberof CassCluster 1952 * 1953 * @deprecated This is no longer useful and does nothing. Expect this to be 1954 * removed in a future release. 1955 * 1956 * @param[in] cluster 1957 * @param[in] num_requests 1958 * @return CASS_OK if successful, otherwise an error occurred. 1959 */ 1960 CASS_EXPORT CASS_DEPRECATED(CassError 1961 cass_cluster_set_pending_requests_high_water_mark(CassCluster* cluster, 1962 unsigned num_requests)); 1963 1964 /** 1965 * Sets the low water mark for the number of requests queued waiting 1966 * for a connection in a connection pool. After exceeding high water mark 1967 * requests, writes to a host will only resume once the number of requests 1968 * fall below this value. 1969 * 1970 * <b>Default:</b> 128 1971 * 1972 * @public @memberof CassCluster 1973 * 1974 * @deprecated This is no longer useful and does nothing. Expect this to be 1975 * removed in a future release. 1976 * 1977 * @param[in] cluster 1978 * @param[in] num_requests 1979 * @return CASS_OK if successful, otherwise an error occurred. 1980 */ 1981 CASS_EXPORT CASS_DEPRECATED(CassError 1982 cass_cluster_set_pending_requests_low_water_mark(CassCluster* cluster, 1983 unsigned num_requests)); 1984 1985 /** 1986 * Sets the timeout for connecting to a node. 1987 * 1988 * <b>Default:</b> 5000 milliseconds 1989 * 1990 * @public @memberof CassCluster 1991 * 1992 * @param[in] cluster 1993 * @param[in] timeout_ms Connect timeout in milliseconds 1994 */ 1995 CASS_EXPORT void 1996 cass_cluster_set_connect_timeout(CassCluster* cluster, 1997 unsigned timeout_ms); 1998 1999 /** 2000 * Sets the timeout for waiting for a response from a node. 2001 * 2002 * <b>Default:</b> 12000 milliseconds 2003 * 2004 * @public @memberof CassCluster 2005 * 2006 * @param[in] cluster 2007 * @param[in] timeout_ms Request timeout in milliseconds. Use 0 for no timeout. 2008 */ 2009 CASS_EXPORT void 2010 cass_cluster_set_request_timeout(CassCluster* cluster, 2011 unsigned timeout_ms); 2012 2013 /** 2014 * Sets the timeout for waiting for DNS name resolution. 2015 * 2016 * <b>Default:</b> 2000 milliseconds 2017 * 2018 * @public @memberof CassCluster 2019 * 2020 * @param[in] cluster 2021 * @param[in] timeout_ms Request timeout in milliseconds 2022 */ 2023 CASS_EXPORT void 2024 cass_cluster_set_resolve_timeout(CassCluster* cluster, 2025 unsigned timeout_ms); 2026 2027 /** 2028 * Sets the maximum time to wait for schema agreement after a schema change 2029 * is made (e.g. creating, altering, dropping a table/keyspace/view/index etc). 2030 * 2031 * <b>Default:</b> 10000 milliseconds 2032 * 2033 * @public @memberof CassCluster 2034 * 2035 * @param[in] cluster 2036 * @param[in] wait_time_ms Wait time in milliseconds 2037 */ 2038 CASS_EXPORT void 2039 cass_cluster_set_max_schema_wait_time(CassCluster* cluster, 2040 unsigned wait_time_ms); 2041 2042 2043 /** 2044 * Sets the maximum time to wait for tracing data to become available. 2045 * 2046 * <b>Default:</b> 15 milliseconds 2047 * 2048 * @param[in] cluster 2049 * @param[in] max_wait_time_ms 2050 */ 2051 CASS_EXPORT void 2052 cass_cluster_set_tracing_max_wait_time(CassCluster* cluster, 2053 unsigned max_wait_time_ms); 2054 2055 /** 2056 * Sets the amount of time to wait between attempts to check to see if tracing is 2057 * available. 2058 * 2059 * <b>Default:</b> 3 milliseconds 2060 * 2061 * @param[in] cluster 2062 * @param[in] retry_wait_time_ms 2063 */ 2064 CASS_EXPORT void 2065 cass_cluster_set_tracing_retry_wait_time(CassCluster* cluster, 2066 unsigned retry_wait_time_ms); 2067 2068 /** 2069 * Sets the consistency level to use for checking to see if tracing data is 2070 * available. 2071 * 2072 * <b>Default:</b> CASS_CONSISTENCY_ONE 2073 * 2074 * @param[in] cluster 2075 * @param[in] consistency 2076 */ 2077 CASS_EXPORT void 2078 cass_cluster_set_tracing_consistency(CassCluster* cluster, 2079 CassConsistency consistency); 2080 2081 2082 /** 2083 * Sets credentials for plain text authentication. 2084 * 2085 * @public @memberof CassCluster 2086 * 2087 * @param[in] cluster 2088 * @param[in] username 2089 * @param[in] password 2090 */ 2091 CASS_EXPORT void 2092 cass_cluster_set_credentials(CassCluster* cluster, 2093 const char* username, 2094 const char* password); 2095 2096 /** 2097 * Same as cass_cluster_set_credentials(), but with lengths for string 2098 * parameters. 2099 * 2100 * @public @memberof CassCluster 2101 * 2102 * @param[in] cluster 2103 * @param[in] username 2104 * @param[in] username_length 2105 * @param[in] password 2106 * @param[in] password_length 2107 * @return same as cass_cluster_set_credentials() 2108 * 2109 * @see cass_cluster_set_credentials(); 2110 */ 2111 CASS_EXPORT void 2112 cass_cluster_set_credentials_n(CassCluster* cluster, 2113 const char* username, 2114 size_t username_length, 2115 const char* password, 2116 size_t password_length); 2117 2118 /** 2119 * Configures the cluster to use round-robin load balancing. 2120 * 2121 * The driver discovers all nodes in a cluster and cycles through 2122 * them per request. All are considered 'local'. 2123 * 2124 * @public @memberof CassCluster 2125 * 2126 * @param[in] cluster 2127 */ 2128 CASS_EXPORT void 2129 cass_cluster_set_load_balance_round_robin(CassCluster* cluster); 2130 2131 /** 2132 * Configures the cluster to use DC-aware load balancing. 2133 * For each query, all live nodes in a primary 'local' DC are tried first, 2134 * followed by any node from other DCs. 2135 * 2136 * <b>Note:</b> This is the default, and does not need to be called unless 2137 * switching an existing from another policy or changing settings. 2138 * Without further configuration, a default local_dc is chosen from the 2139 * first connected contact point, and no remote hosts are considered in 2140 * query plans. If relying on this mechanism, be sure to use only contact 2141 * points from the local DC. 2142 * 2143 * @deprecated The remote DC settings for DC-aware are not suitable for most 2144 * scenarios that require DC failover. There is also unhandled gap between 2145 * replication factor number of nodes failing and the full cluster failing. Only 2146 * the remote DC settings are being deprecated. 2147 * 2148 * @public @memberof CassCluster 2149 * 2150 * @param[in] cluster 2151 * @param[in] local_dc The primary data center to try first 2152 * @param[in] used_hosts_per_remote_dc The number of hosts used in each remote 2153 * DC if no hosts are available in the local dc (<b>deprecated</b>) 2154 * @param[in] allow_remote_dcs_for_local_cl Allows remote hosts to be used if no 2155 * local dc hosts are available and the consistency level is LOCAL_ONE or 2156 * LOCAL_QUORUM (<b>deprecated</b>) 2157 * @return CASS_OK if successful, otherwise an error occurred 2158 */ 2159 CASS_EXPORT CassError 2160 cass_cluster_set_load_balance_dc_aware(CassCluster* cluster, 2161 const char* local_dc, 2162 unsigned used_hosts_per_remote_dc, 2163 cass_bool_t allow_remote_dcs_for_local_cl); 2164 2165 2166 /** 2167 * Same as cass_cluster_set_load_balance_dc_aware(), but with lengths for string 2168 * parameters. 2169 * 2170 * @deprecated The remote DC settings for DC-aware are not suitable for most 2171 * scenarios that require DC failover. There is also unhandled gap between 2172 * replication factor number of nodes failing and the full cluster failing. Only 2173 * the remote DC settings are being deprecated. 2174 * 2175 * @public @memberof CassCluster 2176 * 2177 * @param[in] cluster 2178 * @param[in] local_dc 2179 * @param[in] local_dc_length 2180 * @param[in] used_hosts_per_remote_dc (<b>deprecated</b>) 2181 * @param[in] allow_remote_dcs_for_local_cl (<b>deprecated</b>) 2182 * @return same as cass_cluster_set_load_balance_dc_aware() 2183 * 2184 * @see cass_cluster_set_load_balance_dc_aware() 2185 */ 2186 CASS_EXPORT CassError 2187 cass_cluster_set_load_balance_dc_aware_n(CassCluster* cluster, 2188 const char* local_dc, 2189 size_t local_dc_length, 2190 unsigned used_hosts_per_remote_dc, 2191 cass_bool_t allow_remote_dcs_for_local_cl); 2192 2193 /** 2194 * Configures the cluster to use token-aware request routing or not. 2195 * 2196 * <b>Important:</b> Token-aware routing depends on keyspace metadata. 2197 * For this reason enabling token-aware routing will also enable retrieving 2198 * and updating keyspace schema metadata. 2199 * 2200 * <b>Default:</b> cass_true (enabled). 2201 * 2202 * This routing policy composes the base routing policy, routing 2203 * requests first to replicas on nodes considered 'local' by 2204 * the base load balancing policy. 2205 * 2206 * @public @memberof CassCluster 2207 * 2208 * @param[in] cluster 2209 * @param[in] enabled 2210 */ 2211 CASS_EXPORT void 2212 cass_cluster_set_token_aware_routing(CassCluster* cluster, 2213 cass_bool_t enabled); 2214 2215 2216 /** 2217 * Configures token-aware routing to randomly shuffle replicas. This can reduce 2218 * the effectiveness of server-side caching, but it can better distribute load over 2219 * replicas for a given partition key. 2220 * 2221 * <b>Note:</b> Token-aware routing must be enabled for the setting to 2222 * be applicable. 2223 * 2224 * <b>Default:</b> cass_true (enabled). 2225 * 2226 * @public @memberof CassCluster 2227 * 2228 * @param[in] cluster 2229 * @param[in] enabled 2230 */ 2231 CASS_EXPORT void 2232 cass_cluster_set_token_aware_routing_shuffle_replicas(CassCluster* cluster, 2233 cass_bool_t enabled); 2234 2235 /** 2236 * Configures the cluster to use latency-aware request routing or not. 2237 * 2238 * <b>Default:</b> cass_false (disabled). 2239 * 2240 * This routing policy is a top-level routing policy. It uses the 2241 * base routing policy to determine locality (dc-aware) and/or 2242 * placement (token-aware) before considering the latency. 2243 * 2244 * @public @memberof CassCluster 2245 * 2246 * @param[in] cluster 2247 * @param[in] enabled 2248 */ 2249 CASS_EXPORT void 2250 cass_cluster_set_latency_aware_routing(CassCluster* cluster, 2251 cass_bool_t enabled); 2252 2253 /** 2254 * Configures the settings for latency-aware request routing. 2255 * 2256 * <b>Defaults:</b> 2257 * 2258 * <ul> 2259 * <li>exclusion_threshold: 2.0</li> 2260 * <li>scale_ms: 100 milliseconds</li> 2261 * <li>retry_period_ms: 10,000 milliseconds (10 seconds)</li> 2262 * <li>update_rate_ms: 100 milliseconds</li> 2263 * <li>min_measured: 50</li> 2264 * </ul> 2265 * 2266 * @public @memberof CassCluster 2267 * 2268 * @param[in] cluster 2269 * @param[in] exclusion_threshold Controls how much worse the latency must be compared to the 2270 * average latency of the best performing node before it penalized. 2271 * @param[in] scale_ms Controls the weight given to older latencies when calculating the average 2272 * latency of a node. A bigger scale will give more weight to older latency measurements. 2273 * @param[in] retry_period_ms The amount of time a node is penalized by the policy before 2274 * being given a second chance when the current average latency exceeds the calculated 2275 * threshold (exclusion_threshold * best_average_latency). 2276 * @param[in] update_rate_ms The rate at which the best average latency is recomputed. 2277 * @param[in] min_measured The minimum number of measurements per-host required to 2278 * be considered by the policy. 2279 */ 2280 CASS_EXPORT void 2281 cass_cluster_set_latency_aware_routing_settings(CassCluster* cluster, 2282 cass_double_t exclusion_threshold, 2283 cass_uint64_t scale_ms, 2284 cass_uint64_t retry_period_ms, 2285 cass_uint64_t update_rate_ms, 2286 cass_uint64_t min_measured); 2287 2288 /** 2289 * Sets/Appends whitelist hosts. The first call sets the whitelist hosts and 2290 * any subsequent calls appends additional hosts. Passing an empty string will 2291 * clear and disable the whitelist. White space is striped from the hosts. 2292 * 2293 * This policy filters requests to all other policies, only allowing requests 2294 * to the hosts contained in the whitelist. Any host not in the whitelist will 2295 * be ignored and a connection will not be established. This policy is useful 2296 * for ensuring that the driver will only connect to a predefined set of hosts. 2297 * 2298 * Examples: "127.0.0.1" "127.0.0.1,127.0.0.2" 2299 * 2300 * @public @memberof CassCluster 2301 * 2302 * @param[in] cluster 2303 * @param[in] hosts A comma delimited list of addresses. An empty string will 2304 * clear the whitelist hosts. The string is copied into the cluster 2305 * configuration; the memory pointed to by this parameter can be freed after 2306 * this call. 2307 */ 2308 CASS_EXPORT void 2309 cass_cluster_set_whitelist_filtering(CassCluster* cluster, 2310 const char* hosts); 2311 2312 /** 2313 * Same as cass_cluster_set_whitelist_filtering(), but with lengths for 2314 * string parameters. 2315 * 2316 * @public @memberof CassCluster 2317 * 2318 * @param[in] cluster 2319 * @param[in] hosts 2320 * @param[in] hosts_length 2321 * @return same as cass_cluster_set_whitelist_filtering() 2322 * 2323 * @see cass_cluster_set_whitelist_filtering() 2324 */ 2325 CASS_EXPORT void 2326 cass_cluster_set_whitelist_filtering_n(CassCluster* cluster, 2327 const char* hosts, 2328 size_t hosts_length); 2329 2330 /** 2331 * Sets/Appends blacklist hosts. The first call sets the blacklist hosts and 2332 * any subsequent calls appends additional hosts. Passing an empty string will 2333 * clear and disable the blacklist. White space is striped from the hosts. 2334 * 2335 * This policy filters requests to all other policies, only allowing requests 2336 * to the hosts not contained in the blacklist. Any host in the blacklist will 2337 * be ignored and a connection will not be established. This policy is useful 2338 * for ensuring that the driver will not connect to a predefined set of hosts. 2339 * 2340 * Examples: "127.0.0.1" "127.0.0.1,127.0.0.2" 2341 * 2342 * @public @memberof CassCluster 2343 * 2344 * @param[in] cluster 2345 * @param[in] hosts A comma delimited list of addresses. An empty string will 2346 * clear the blacklist hosts. The string is copied into the cluster 2347 * configuration; the memory pointed to by this parameter can be freed after 2348 * this call. 2349 */ 2350 CASS_EXPORT void 2351 cass_cluster_set_blacklist_filtering(CassCluster* cluster, 2352 const char* hosts); 2353 2354 /** 2355 * Same as cass_cluster_set_blacklist_filtering_hosts(), but with lengths for 2356 * string parameters. 2357 * 2358 * @public @memberof CassCluster 2359 * 2360 * @param[in] cluster 2361 * @param[in] hosts 2362 * @param[in] hosts_length 2363 * @return same as cass_cluster_set_blacklist_filtering() 2364 * 2365 * @see cass_cluster_set_blacklist_filtering() 2366 */ 2367 CASS_EXPORT void 2368 cass_cluster_set_blacklist_filtering_n(CassCluster* cluster, 2369 const char* hosts, 2370 size_t hosts_length); 2371 2372 /** 2373 * Same as cass_cluster_set_whitelist_filtering(), but whitelist all hosts of a dc 2374 * 2375 * Examples: "dc1", "dc1,dc2" 2376 * 2377 * @public @memberof CassCluster 2378 * 2379 * @param[in] cluster 2380 * @param[in] dcs A comma delimited list of dcs. An empty string will clear the 2381 * whitelist dcs. The string is copied into the cluster configuration; the 2382 * memory pointed to by this parameter can be freed after this call. 2383 */ 2384 CASS_EXPORT void 2385 cass_cluster_set_whitelist_dc_filtering(CassCluster* cluster, 2386 const char* dcs); 2387 2388 /** 2389 * Same as cass_cluster_set_whitelist_dc_filtering(), but with lengths for 2390 * string parameters. 2391 * 2392 * @public @memberof CassCluster 2393 * 2394 * @param[in] cluster 2395 * @param[in] dcs 2396 * @param[in] dcs_length 2397 * @return same as cass_cluster_set_whitelist_dc_filtering() 2398 * 2399 * @see cass_cluster_set_whitelist_dc_filtering() 2400 */ 2401 CASS_EXPORT void 2402 cass_cluster_set_whitelist_dc_filtering_n(CassCluster* cluster, 2403 const char* dcs, 2404 size_t dcs_length); 2405 2406 /** 2407 * Same as cass_cluster_set_blacklist_filtering(), but blacklist all hosts of a dc 2408 * 2409 * Examples: "dc1", "dc1,dc2" 2410 * 2411 * @public @memberof CassCluster 2412 * 2413 * @param[in] cluster 2414 * @param[in] dcs A comma delimited list of dcs. An empty string will clear the 2415 * blacklist dcs. The string is copied into the cluster configuration; the 2416 * memory pointed to by this parameter can be freed after this call. 2417 */ 2418 CASS_EXPORT void 2419 cass_cluster_set_blacklist_dc_filtering(CassCluster* cluster, 2420 const char* dcs); 2421 2422 /** 2423 * Same as cass_cluster_set_blacklist_dc_filtering(), but with lengths for 2424 * string parameters. 2425 * 2426 * @public @memberof CassCluster 2427 * 2428 * @param[in] cluster 2429 * @param[in] dcs 2430 * @param[in] dcs_length 2431 * @return same as cass_cluster_set_blacklist_dc_filtering() 2432 * 2433 * @see cass_cluster_set_blacklist_dc_filtering() 2434 */ 2435 CASS_EXPORT void 2436 cass_cluster_set_blacklist_dc_filtering_n(CassCluster* cluster, 2437 const char* dcs, 2438 size_t dcs_length); 2439 2440 /** 2441 * Enable/Disable Nagle's algorithm on connections. 2442 * 2443 * <b>Default:</b> cass_true (disables Nagle's algorithm). 2444 * 2445 * @public @memberof CassCluster 2446 * 2447 * @param[in] cluster 2448 * @param[in] enabled 2449 */ 2450 CASS_EXPORT void 2451 cass_cluster_set_tcp_nodelay(CassCluster* cluster, 2452 cass_bool_t enabled); 2453 2454 /** 2455 * Enable/Disable TCP keep-alive 2456 * 2457 * <b>Default:</b> cass_false (disabled). 2458 * 2459 * @public @memberof CassCluster 2460 * 2461 * @param[in] cluster 2462 * @param[in] enabled 2463 * @param[in] delay_secs The initial delay in seconds, ignored when 2464 * `enabled` is false. 2465 */ 2466 CASS_EXPORT void 2467 cass_cluster_set_tcp_keepalive(CassCluster* cluster, 2468 cass_bool_t enabled, 2469 unsigned delay_secs); 2470 /** 2471 * Sets the timestamp generator used to assign timestamps to all requests 2472 * unless overridden by setting the timestamp on a statement or a batch. 2473 * 2474 * <b>Default:</b> Monotonically increasing, client-side timestamp generator. 2475 * 2476 * @cassandra{2.1+} 2477 * 2478 * @public @memberof CassCluster 2479 * 2480 * @param[in] cluster 2481 * @param[in] timestamp_gen 2482 * 2483 * @see cass_statement_set_timestamp() 2484 * @see cass_batch_set_timestamp() 2485 */ 2486 CASS_EXPORT void 2487 cass_cluster_set_timestamp_gen(CassCluster* cluster, 2488 CassTimestampGen* timestamp_gen); 2489 2490 /** 2491 * Sets the amount of time between heartbeat messages and controls the amount 2492 * of time the connection must be idle before sending heartbeat messages. This 2493 * is useful for preventing intermediate network devices from dropping 2494 * connections. 2495 * 2496 * <b>Default:</b> 30 seconds 2497 * 2498 * @public @memberof CassCluster 2499 * 2500 * @param[in] cluster 2501 * @param[in] interval_secs Use 0 to disable heartbeat messages 2502 */ 2503 CASS_EXPORT void 2504 cass_cluster_set_connection_heartbeat_interval(CassCluster* cluster, 2505 unsigned interval_secs); 2506 2507 /** 2508 * Sets the amount of time a connection is allowed to be without a successful 2509 * heartbeat response before being terminated and scheduled for reconnection. 2510 * 2511 * <b>Default:</b> 60 seconds 2512 * 2513 * @public @memberof CassCluster 2514 * 2515 * @param[in] cluster 2516 * @param[in] timeout_secs 2517 */ 2518 CASS_EXPORT void 2519 cass_cluster_set_connection_idle_timeout(CassCluster* cluster, 2520 unsigned timeout_secs); 2521 2522 /** 2523 * Sets the retry policy used for all requests unless overridden by setting 2524 * a retry policy on a statement or a batch. 2525 * 2526 * <b>Default:</b> The same policy as would be created by the function: 2527 * cass_retry_policy_default_new(). This policy will retry on a read timeout 2528 * if there was enough replicas, but no data present, on a write timeout if a 2529 * logged batch request failed to write the batch log, and on a unavailable 2530 * error it retries using a new host. In all other cases the default policy 2531 * will return an error. 2532 * 2533 * @public @memberof CassCluster 2534 * 2535 * @param[in] cluster 2536 * @param[in] retry_policy 2537 * 2538 * @see cass_retry_policy_default_new() 2539 * @see cass_statement_set_retry_policy() 2540 * @see cass_batch_set_retry_policy() 2541 */ 2542 CASS_EXPORT void 2543 cass_cluster_set_retry_policy(CassCluster* cluster, 2544 CassRetryPolicy* retry_policy); 2545 2546 /** 2547 * Enable/Disable retrieving and updating schema metadata. If disabled 2548 * this is allows the driver to skip over retrieving and updating schema 2549 * metadata and cass_session_get_schema_meta() will always return an empty object. 2550 * This can be useful for reducing the startup overhead of short-lived sessions. 2551 * 2552 * <b>Default:</b> cass_true (enabled). 2553 * 2554 * @public @memberof CassCluster 2555 * 2556 * @param[in] cluster 2557 * @param[in] enabled 2558 * 2559 * @see cass_session_get_schema_meta() 2560 */ 2561 CASS_EXPORT void 2562 cass_cluster_set_use_schema(CassCluster* cluster, 2563 cass_bool_t enabled); 2564 2565 /** 2566 * Enable/Disable retrieving hostnames for IP addresses using reverse IP lookup. 2567 * 2568 * This is useful for authentication (Kerberos) or encryption (SSL) services 2569 * that require a valid hostname for verification. 2570 * 2571 * <b>Default:</b> cass_false (disabled). 2572 * 2573 * @public @memberof CassCluster 2574 * 2575 * @param[in] cluster 2576 * @param[in] enabled 2577 * @return CASS_OK if successful, otherwise an error occurred 2578 * 2579 * @see cass_cluster_set_resolve_timeout() 2580 */ 2581 CASS_EXPORT CassError 2582 cass_cluster_set_use_hostname_resolution(CassCluster* cluster, 2583 cass_bool_t enabled); 2584 2585 /** 2586 * Enable/Disable the randomization of the contact points list. 2587 * 2588 * <b>Default:</b> cass_true (enabled). 2589 * 2590 * <b>Important:</b> This setting should only be disabled for debugging or 2591 * tests. 2592 * 2593 * @public @memberof CassCluster 2594 * 2595 * @param[in] cluster 2596 * @param[in] enabled 2597 * @return CASS_OK if successful, otherwise an error occurred 2598 */ 2599 CASS_EXPORT CassError 2600 cass_cluster_set_use_randomized_contact_points(CassCluster* cluster, 2601 cass_bool_t enabled); 2602 2603 /** 2604 * Enable constant speculative executions with the supplied settings. 2605 * 2606 * @public @memberof CassCluster 2607 * 2608 * @param[in] cluster 2609 * @param[in] constant_delay_ms 2610 * @param[in] max_speculative_executions 2611 * @return CASS_OK if successful, otherwise an error occurred 2612 */ 2613 CASS_EXPORT CassError 2614 cass_cluster_set_constant_speculative_execution_policy(CassCluster* cluster, 2615 cass_int64_t constant_delay_ms, 2616 int max_speculative_executions); 2617 2618 /** 2619 * Disable speculative executions 2620 * 2621 * <b>Default:</b> This is the default speculative execution policy. 2622 * 2623 * @public @memberof CassCluster 2624 * 2625 * @param[in] cluster 2626 * @return CASS_OK if successful, otherwise an error occurred 2627 */ 2628 CASS_EXPORT CassError 2629 cass_cluster_set_no_speculative_execution_policy(CassCluster* cluster); 2630 2631 /** 2632 * Sets the maximum number of "pending write" objects that will be 2633 * saved for re-use for marshalling new requests. These objects may 2634 * hold on to a significant amount of memory and reducing the 2635 * number of these objects may reduce memory usage of the application. 2636 * 2637 * The cost of reducing the value of this setting is potentially slower 2638 * marshalling of requests prior to sending. 2639 * 2640 * <b>Default:</b> Max unsigned integer value 2641 * 2642 * @public @memberof CassCluster 2643 * 2644 * @param[in] cluster 2645 * @param[in] num_objects 2646 * @return CASS_OK if successful, otherwise an error occurred. 2647 */ 2648 CASS_EXPORT CassError 2649 cass_cluster_set_max_reusable_write_objects(CassCluster* cluster, 2650 unsigned num_objects); 2651 2652 /** 2653 * Associates a named execution profile which can be utilized during execution. 2654 * 2655 * <b>Note:</b> Once the execution profile is added to a cluster, it is 2656 * immutable and any changes made to the execution profile must be re-assigned 2657 * to the cluster before a session connection is established in order for those 2658 * settings to be utilized during query execution. 2659 * 2660 * @public @memberof CassCluster 2661 * 2662 * @param[in] cluster 2663 * @param[in] name 2664 * @param[in] profile 2665 * @return CASS_OK if successful, otherwise an error occurred 2666 * 2667 * @see cass_batch_set_execution_profile() 2668 * @see cass_statement_set_execution_profile() 2669 */ 2670 CASS_EXPORT CassError 2671 cass_cluster_set_execution_profile(CassCluster* cluster, 2672 const char* name, 2673 CassExecProfile* profile); 2674 2675 /** 2676 * Same as cass_cluster_add_execution_profile(), but with lengths for string 2677 * parameters. 2678 * 2679 * @public @memberof CassCluster 2680 * 2681 * @param[in] cluster 2682 * @param[in] name 2683 * @param[in] name_length 2684 * @param[in] profile 2685 * @return same as cass_cluster_set_execution_profile() 2686 * 2687 * @see cass_batch_set_execution_profile() 2688 * @see cass_statement_set_execution_profile() 2689 */ 2690 CASS_EXPORT CassError 2691 cass_cluster_set_execution_profile_n(CassCluster* cluster, 2692 const char* name, 2693 size_t name_length, 2694 CassExecProfile* profile); 2695 2696 /** 2697 * Prepare statements on all available hosts. 2698 * 2699 * <b>Default:</b> cass_true 2700 * 2701 * @public @memberof CassCluster 2702 * 2703 * @param cluster 2704 * @param enabled 2705 * @return CASS_OK if successful, otherwise an error occurred 2706 */ 2707 CASS_EXPORT CassError 2708 cass_cluster_set_prepare_on_all_hosts(CassCluster* cluster, 2709 cass_bool_t enabled); 2710 2711 /** 2712 * Enable pre-preparing cached prepared statements when existing hosts become 2713 * available again or when new hosts are added to the cluster. 2714 * 2715 * This can help mitigate request latency when executing prepared statements 2716 * by avoiding an extra round trip in cases where the statement is 2717 * unprepared on a freshly started server. The main tradeoff is extra background 2718 * network traffic is required to prepare the statements on hosts as they become 2719 * available. 2720 * 2721 * <b>Default:</b> cass_true 2722 * 2723 * @param cluster 2724 * @param enabled 2725 * @return CASS_OK if successful, otherwise an error occurred 2726 */ 2727 CASS_EXPORT CassError 2728 cass_cluster_set_prepare_on_up_or_add_host(CassCluster* cluster, 2729 cass_bool_t enabled); 2730 2731 /** 2732 * Enable the <b>NO_COMPACT</b> startup option. 2733 * 2734 * This can help facilitate uninterrupted cluster upgrades where tables using 2735 * <b>COMPACT_STORAGE</b> will operate in "compatibility mode" for 2736 * <b>BATCH</b>, <b>DELETE</b>, <b>SELECT</b>, and <b>UPDATE</b> CQL operations. 2737 * 2738 * <b>Default:</b> cass_false 2739 * 2740 * @cassandra{3.0.16+} 2741 * @cassandra{3.11.2+} 2742 * @cassandra{4.0+} 2743 * 2744 * @public @memberof CassCluster 2745 * 2746 * @param[in] cluster 2747 * @param[in] enabled 2748 */ 2749 CASS_EXPORT CassError 2750 cass_cluster_set_no_compact(CassCluster* cluster, 2751 cass_bool_t enabled); 2752 2753 /** 2754 * Sets a callback for handling host state changes in the cluster. 2755 * 2756 * <b>Note:</b> The callback is invoked only when state changes in the cluster 2757 * are applicable to the configured load balancing policy(s). 2758 * 2759 * @public @memberof CassCluster 2760 * 2761 * @param[in] cluster 2762 * @param[in] callback 2763 * @param[in] data 2764 * @return CASS_OK if successful, otherwise and error occurred 2765 */ 2766 CASS_EXPORT CassError 2767 cass_cluster_set_host_listener_callback(CassCluster* cluster, 2768 CassHostListenerCallback callback, 2769 void* data); 2770 2771 /** 2772 * Sets the secure connection bundle path for processing DBaaS credentials. 2773 * 2774 * This will pre-configure a cluster using the credentials format provided by 2775 * the DBaaS cloud provider. 2776 * 2777 * @param[in] cluster 2778 * @param[in] path Absolute path to DBaaS credentials file. 2779 * @return CASS_OK if successful, otherwise error occured. 2780 */ 2781 CASS_EXPORT CassError 2782 cass_cluster_set_cloud_secure_connection_bundle(CassCluster* cluster, 2783 const char* path); 2784 2785 /** 2786 * Same as cass_cluster_set_cloud_secure_connection_bundle(), but with lengths 2787 * for string parameters. 2788 * 2789 * @see cass_cluster_set_cloud_secure_connection_bundle() 2790 * 2791 * @param[in] cluster 2792 * @param[in] path Absolute path to DBaaS credentials file. 2793 * @param[in] path_length Length of path variable. 2794 * @return CASS_OK if successful, otherwise error occured. 2795 */ 2796 CASS_EXPORT CassError 2797 cass_cluster_set_cloud_secure_connection_bundle_n(CassCluster* cluster, 2798 const char* path, 2799 size_t path_length); 2800 2801 /** 2802 * Same as cass_cluster_set_cloud_secure_connection_bundle(), but it does not 2803 * initialize the underlying SSL library implementation. The SSL library still 2804 * needs to be initialized, but it's up to the client application to handle 2805 * initialization. This is similar to the function cass_ssl_new_no_lib_init(), 2806 * and its documentation should be used as a reference to properly initialize 2807 * the underlying SSL library. 2808 * 2809 * @see cass_ssl_new_no_lib_init() 2810 * @see cass_cluster_set_cloud_secure_connection_bundle() 2811 * 2812 * @param[in] cluster 2813 * @param[in] path Absolute path to DBaaS credentials file. 2814 * @return CASS_OK if successful, otherwise error occured. 2815 */ 2816 CASS_EXPORT CassError 2817 cass_cluster_set_cloud_secure_connection_bundle_no_ssl_lib_init(CassCluster* cluster, 2818 const char* path); 2819 2820 /** 2821 * Same as cass_cluster_set_cloud_secure_connection_bundle_no_ssl_lib_init(), 2822 * but with lengths for string parameters. 2823 * 2824 * @see cass_cluster_set_cloud_secure_connection_bundle_no_ssl_lib_init() 2825 * 2826 * @param[in] cluster 2827 * @param[in] path Absolute path to DBaaS credentials file. 2828 * @param[in] path_length Length of path variable. 2829 * @return CASS_OK if successful, otherwise error occured. 2830 */ 2831 CASS_EXPORT CassError 2832 cass_cluster_set_cloud_secure_connection_bundle_no_ssl_lib_init_n(CassCluster* cluster, 2833 const char* path, 2834 size_t path_length); 2835 2836 /** 2837 * Set the application name. 2838 * 2839 * This is optional; however it provides the server with the application name 2840 * that can aid in debugging issues with larger clusters where there are a lot 2841 * of client (or application) connections. 2842 * 2843 * @public @memberof CassCluster 2844 * 2845 * @param[in] cluster 2846 * @param[in] application_name 2847 */ 2848 CASS_EXPORT void 2849 cass_cluster_set_application_name(CassCluster* cluster, 2850 const char* application_name); 2851 2852 /** 2853 * Same as cass_cluster_set_application_name(), but with lengths for string 2854 * parameters. 2855 * 2856 * @public @memberof CassCluster 2857 * 2858 * @param[in] cluster 2859 * @param[in] application_name 2860 * @param[in] application_name_length 2861 */ 2862 CASS_EXPORT void 2863 cass_cluster_set_application_name_n(CassCluster* cluster, 2864 const char* application_name, 2865 size_t application_name_length); 2866 2867 /** 2868 * Set the application version. 2869 * 2870 * This is optional; however it provides the server with the application 2871 * version that can aid in debugging issues with large clusters where there are 2872 * a lot of client (or application) connections that may have different 2873 * versions in use. 2874 * 2875 * @public @memberof CassCluster 2876 * 2877 * @param[in] cluster 2878 * @param[in] application_version 2879 */ 2880 2881 CASS_EXPORT void 2882 cass_cluster_set_application_version(CassCluster* cluster, 2883 const char* application_version); 2884 2885 /** 2886 * Same as cass_cluster_set_application_version(), but with lengths for string 2887 * parameters. 2888 * 2889 * @public @memberof CassCluster 2890 * 2891 * @param[in] cluster 2892 * @param[in] application_version 2893 * @param[in] application_version_length 2894 */ 2895 CASS_EXPORT void 2896 cass_cluster_set_application_version_n(CassCluster* cluster, 2897 const char* application_version, 2898 size_t application_version_length); 2899 2900 /** 2901 * Set the client id. 2902 * 2903 * This is optional; however it provides the server with the client ID that can 2904 * aid in debugging issues with large clusters where there are a lot of client 2905 * connections. 2906 * 2907 * Default: UUID v4 generated (@see cass_session_get_client_id()) 2908 * 2909 * @public @memberof CassCluster 2910 * 2911 * @param[in] cluster 2912 * @param[in] client_id 2913 */ 2914 CASS_EXPORT void 2915 cass_cluster_set_client_id(CassCluster* cluster, CassUuid client_id); 2916 2917 /** 2918 * Sets the amount of time between monitor reporting event messages. 2919 * 2920 * <b>Default:</b> 300 seconds. 2921 * 2922 * @public @memberof CassCluster 2923 * 2924 * @param[in] cluster 2925 * @param[in] interval_secs Use 0 to disable monitor reporting event messages. 2926 */ 2927 CASS_EXPORT void 2928 cass_cluster_set_monitor_reporting_interval(CassCluster* cluster, 2929 unsigned interval_secs); 2930 2931 /*********************************************************************************** 2932 * 2933 * Session 2934 * 2935 ***********************************************************************************/ 2936 2937 /** 2938 * Creates a new session. 2939 * 2940 * @public @memberof CassSession 2941 * 2942 * @return Returns a session that must be freed. 2943 * 2944 * @see cass_session_free() 2945 */ 2946 CASS_EXPORT CassSession* 2947 cass_session_new(); 2948 2949 /** 2950 * Frees a session instance. If the session is still connected it will be synchronously 2951 * closed before being deallocated. 2952 * 2953 * Important: Do not free a session in a future callback. Freeing a session in a future 2954 * callback will cause a deadlock. 2955 * 2956 * @public @memberof CassSession 2957 * 2958 * @param[in] session 2959 */ 2960 CASS_EXPORT void 2961 cass_session_free(CassSession* session); 2962 2963 /** 2964 * Connects a session. 2965 * 2966 * @public @memberof CassSession 2967 * 2968 * @param[in] session 2969 * @param[in] cluster The cluster configuration is copied into the session and 2970 * is immutable after connection. 2971 * @return A future that must be freed. 2972 * 2973 * @see cass_session_close() 2974 */ 2975 CASS_EXPORT CassFuture* 2976 cass_session_connect(CassSession* session, 2977 const CassCluster* cluster); 2978 2979 /** 2980 * Connects a session and sets the keyspace. 2981 * 2982 * @public @memberof CassSession 2983 * 2984 * @param[in] session 2985 * @param[in] cluster The cluster configuration is copied into the session and 2986 * is immutable after connection. 2987 * @param[in] keyspace 2988 * @return A future that must be freed. 2989 * 2990 * @see cass_session_close() 2991 */ 2992 CASS_EXPORT CassFuture* 2993 cass_session_connect_keyspace(CassSession* session, 2994 const CassCluster* cluster, 2995 const char* keyspace); 2996 2997 /** 2998 * Same as cass_session_connect_keyspace(), but with lengths for string 2999 * parameters. 3000 * 3001 * @public @memberof CassSession 3002 * 3003 * @param[in] session 3004 * @param[in] cluster 3005 * @param[in] keyspace 3006 * @param[in] keyspace_length 3007 * @return same as cass_session_connect_keyspace() 3008 * 3009 * @see cass_session_connect_keyspace() 3010 */ 3011 CASS_EXPORT CassFuture* 3012 cass_session_connect_keyspace_n(CassSession* session, 3013 const CassCluster* cluster, 3014 const char* keyspace, 3015 size_t keyspace_length); 3016 3017 /** 3018 * Closes the session instance, outputs a close future which can 3019 * be used to determine when the session has been terminated. This allows 3020 * in-flight requests to finish. 3021 * 3022 * @public @memberof CassSession 3023 * 3024 * @param[in] session 3025 * @return A future that must be freed. 3026 */ 3027 CASS_EXPORT CassFuture* 3028 cass_session_close(CassSession* session); 3029 3030 /** 3031 * Create a prepared statement. 3032 * 3033 * @public @memberof CassSession 3034 * 3035 * @param[in] session 3036 * @param[in] query The query is copied into the statement object; the 3037 * memory pointed to by this parameter can be freed after this call. 3038 * @return A future that must be freed. 3039 * 3040 * @see cass_future_get_prepared() 3041 */ 3042 CASS_EXPORT CassFuture* 3043 cass_session_prepare(CassSession* session, 3044 const char* query); 3045 3046 /** 3047 * Same as cass_session_prepare(), but with lengths for string 3048 * parameters. 3049 * 3050 * @public @memberof CassSession 3051 * 3052 * @param[in] session 3053 * @param[in] query 3054 * @param[in] query_length 3055 * @return same as cass_session_prepare() 3056 * 3057 * @see cass_session_prepare() 3058 */ 3059 CASS_EXPORT CassFuture* 3060 cass_session_prepare_n(CassSession* session, 3061 const char* query, 3062 size_t query_length); 3063 3064 /** 3065 * Create a prepared statement from an existing statement. 3066 * 3067 * <b>Note:</b> Bound statements will inherit the keyspace, consistency, 3068 * serial consistency, request timeout and retry policy of the existing 3069 * statement. 3070 * 3071 * @public @memberof CassSession 3072 * 3073 * @param[in] session 3074 * @param[in] statement 3075 * @return A future that must be freed. 3076 * 3077 * @see cass_future_get_prepared() 3078 */ 3079 CASS_EXPORT CassFuture* 3080 cass_session_prepare_from_existing(CassSession* session, 3081 CassStatement* statement); 3082 3083 /** 3084 * Execute a query or bound statement. 3085 * 3086 * @public @memberof CassSession 3087 * 3088 * @param[in] session 3089 * @param[in] statement 3090 * @return A future that must be freed. 3091 * 3092 * @see cass_future_get_result() 3093 */ 3094 CASS_EXPORT CassFuture* 3095 cass_session_execute(CassSession* session, 3096 const CassStatement* statement); 3097 3098 /** 3099 * Execute a batch statement. 3100 * 3101 * @cassandra{2.0+} 3102 * 3103 * @public @memberof CassSession 3104 * 3105 * @param[in] session 3106 * @param[in] batch 3107 * @return A future that must be freed. 3108 * 3109 * @see cass_future_get_result() 3110 */ 3111 CASS_EXPORT CassFuture* 3112 cass_session_execute_batch(CassSession* session, 3113 const CassBatch* batch); 3114 3115 /** 3116 * Gets a snapshot of this session's schema metadata. The returned 3117 * snapshot of the schema metadata is not updated. This function 3118 * must be called again to retrieve any schema changes since the 3119 * previous call. 3120 * 3121 * @public @memberof CassSession 3122 * 3123 * @param[in] session 3124 * @return A schema instance that must be freed. 3125 * 3126 * @see cass_schema_meta_free() 3127 */ 3128 CASS_EXPORT const CassSchemaMeta* 3129 cass_session_get_schema_meta(const CassSession* session); 3130 3131 /** 3132 * Gets a copy of this session's performance/diagnostic metrics. 3133 * 3134 * @public @memberof CassSession 3135 * 3136 * @param[in] session 3137 * @param[out] output 3138 */ 3139 CASS_EXPORT void 3140 cass_session_get_metrics(const CassSession* session, 3141 CassMetrics* output); 3142 3143 /** 3144 * Gets a copy of this session's speculative execution metrics. 3145 * 3146 * @public @memberof CassSession 3147 * 3148 * @param[in] session 3149 * @param[out] output 3150 */ 3151 CASS_EXPORT void 3152 cass_session_get_speculative_execution_metrics(const CassSession* session, 3153 CassSpeculativeExecutionMetrics* output); 3154 3155 /** 3156 * Get the client id. 3157 * 3158 * @public @memberof CassSession 3159 * 3160 * @param[in] session 3161 * @return Client id. 3162 */ 3163 CASS_EXPORT CassUuid 3164 cass_session_get_client_id(CassSession* session); 3165 3166 /*********************************************************************************** 3167 * 3168 * Schema Metadata 3169 * 3170 ***********************************************************************************/ 3171 3172 /** 3173 * Frees a schema metadata instance. 3174 * 3175 * @public @memberof CassSchemaMeta 3176 * 3177 * @param[in] schema_meta 3178 */ 3179 CASS_EXPORT void 3180 cass_schema_meta_free(const CassSchemaMeta* schema_meta); 3181 3182 /** 3183 * Gets the version of the schema metadata snapshot. 3184 * 3185 * @public @memberof CassSchemaMeta 3186 * 3187 * @param[in] schema_meta 3188 * 3189 * @return The snapshot version. 3190 */ 3191 CASS_EXPORT cass_uint32_t 3192 cass_schema_meta_snapshot_version(const CassSchemaMeta* schema_meta); 3193 3194 /** 3195 * Gets the version of the connected Cassandra cluster. 3196 * 3197 * @public @memberof CassSchemaMeta 3198 * 3199 * @param[in] schema_meta 3200 * 3201 * @return Cassandra's version 3202 */ 3203 CASS_EXPORT CassVersion 3204 cass_schema_meta_version(const CassSchemaMeta* schema_meta); 3205 3206 /** 3207 * Gets the keyspace metadata for the provided keyspace name. 3208 * 3209 * @public @memberof CassSchemaMeta 3210 * 3211 * @param[in] schema_meta 3212 * @param[in] keyspace 3213 * 3214 * @return The metadata for a keyspace. NULL if keyspace does not exist. 3215 */ 3216 CASS_EXPORT const CassKeyspaceMeta* 3217 cass_schema_meta_keyspace_by_name(const CassSchemaMeta* schema_meta, 3218 const char* keyspace); 3219 3220 /** 3221 * Same as cass_schema_meta_keyspace_by_name(), but with lengths for string 3222 * parameters. 3223 * 3224 * @public @memberof CassSchemaMeta 3225 * 3226 * @param[in] schema_meta 3227 * @param[in] keyspace 3228 * @param[in] keyspace_length 3229 * @return same as cass_schema_meta_keyspace_by_name() 3230 * 3231 * @see cass_schema_meta_keyspace_by_name() 3232 */ 3233 CASS_EXPORT const CassKeyspaceMeta* 3234 cass_schema_meta_keyspace_by_name_n(const CassSchemaMeta* schema_meta, 3235 const char* keyspace, 3236 size_t keyspace_length); 3237 3238 /** 3239 * Gets the name of the keyspace. 3240 * 3241 * @public @memberof CassKeyspaceMeta 3242 * 3243 * @param[in] keyspace_meta 3244 * @param[out] name 3245 * @param[out] name_length 3246 */ 3247 CASS_EXPORT void 3248 cass_keyspace_meta_name(const CassKeyspaceMeta* keyspace_meta, 3249 const char** name, 3250 size_t* name_length); 3251 3252 3253 /** 3254 * Determine if the keyspace is a virtual keyspace. 3255 * 3256 * @public @memberof CassKeyspaceMeta 3257 * 3258 * @param[in] keyspace_meta 3259 * @return cass_true is the keyspace is virtual, otherwise cass_false 3260 */ 3261 CASS_EXPORT cass_bool_t 3262 cass_keyspace_meta_is_virtual(const CassKeyspaceMeta* keyspace_meta); 3263 3264 /** 3265 * Gets the table metadata for the provided table name. 3266 * 3267 * @public @memberof CassKeyspaceMeta 3268 * 3269 * @param[in] keyspace_meta 3270 * @param[in] table 3271 * 3272 * @return The metadata for a table. NULL if table does not exist. 3273 */ 3274 CASS_EXPORT const CassTableMeta* 3275 cass_keyspace_meta_table_by_name(const CassKeyspaceMeta* keyspace_meta, 3276 const char* table); 3277 3278 /** 3279 * Same as cass_keyspace_meta_table_by_name(), but with lengths for string 3280 * parameters. 3281 * 3282 * @public @memberof CassKeyspaceMeta 3283 * 3284 * @param[in] keyspace_meta 3285 * @param[in] table 3286 * @param[in] table_length 3287 * @return same as cass_keyspace_meta_table_by_name() 3288 * 3289 * @see cass_keyspace_meta_table_by_name() 3290 */ 3291 CASS_EXPORT const CassTableMeta* 3292 cass_keyspace_meta_table_by_name_n(const CassKeyspaceMeta* keyspace_meta, 3293 const char* table, 3294 size_t table_length); 3295 3296 /** 3297 * Gets the materialized view metadata for the provided view name. 3298 * 3299 * @cassandra{3.0+} 3300 * 3301 * @public @memberof CassKeyspaceMeta 3302 * 3303 * @param[in] keyspace_meta 3304 * @param[in] view 3305 * 3306 * @return The metadata for a view. NULL if view does not exist. 3307 */ 3308 CASS_EXPORT const CassMaterializedViewMeta* 3309 cass_keyspace_meta_materialized_view_by_name(const CassKeyspaceMeta* keyspace_meta, 3310 const char* view); 3311 3312 /** 3313 * Same as cass_keyspace_meta_materialized_view_by_name(), but with lengths for string 3314 * parameters. 3315 * 3316 * @cassandra{3.0+} 3317 * 3318 * @public @memberof CassKeyspaceMeta 3319 * 3320 * @param[in] keyspace_meta 3321 * @param[in] view 3322 * @param[in] view_length 3323 * @return same as cass_keyspace_meta_materialized_view_by_name() 3324 * 3325 * @see cass_keyspace_meta_materialized_view_by_name() 3326 */ 3327 CASS_EXPORT const CassMaterializedViewMeta* 3328 cass_keyspace_meta_materialized_view_by_name_n(const CassKeyspaceMeta* keyspace_meta, 3329 const char* view, 3330 size_t view_length); 3331 3332 /** 3333 * Gets the data type for the provided type name. 3334 * 3335 * @cassandra{2.1+} 3336 * 3337 * @public @memberof CassKeyspaceMeta 3338 * 3339 * @param[in] keyspace_meta 3340 * @param[in] type 3341 * 3342 * @return The data type for a user defined type. NULL if type does not exist. 3343 */ 3344 CASS_EXPORT const CassDataType* 3345 cass_keyspace_meta_user_type_by_name(const CassKeyspaceMeta* keyspace_meta, 3346 const char* type); 3347 3348 /** 3349 * Same as cass_keyspace_meta_type_by_name(), but with lengths for string 3350 * parameters. 3351 * 3352 * @cassandra{2.1+} 3353 * 3354 * @public @memberof CassKeyspaceMeta 3355 * 3356 * @param[in] keyspace_meta 3357 * @param[in] type 3358 * @param[in] type_length 3359 * @return same as cass_keyspace_meta_type_by_name() 3360 * 3361 * @see cass_keyspace_meta_type_by_name() 3362 */ 3363 CASS_EXPORT const CassDataType* 3364 cass_keyspace_meta_user_type_by_name_n(const CassKeyspaceMeta* keyspace_meta, 3365 const char* type, 3366 size_t type_length); 3367 3368 /** 3369 * Gets the function metadata for the provided function name. 3370 * 3371 * @cassandra{2.2+} 3372 * 3373 * @public @memberof CassKeyspaceMeta 3374 * 3375 * @param[in] keyspace_meta 3376 * @param[in] name 3377 * @param[in] arguments A comma delimited list of CQL types (e.g "text,int,...") 3378 * describing the function's signature. 3379 * 3380 * @return The data function for a user defined function. NULL if function does not exist. 3381 */ 3382 CASS_EXPORT const CassFunctionMeta* 3383 cass_keyspace_meta_function_by_name(const CassKeyspaceMeta* keyspace_meta, 3384 const char* name, 3385 const char* arguments); 3386 3387 /** 3388 * Same as cass_keyspace_meta_function_by_name(), but with lengths for string 3389 * parameters. 3390 * 3391 * @cassandra{2.2+} 3392 * 3393 * @public @memberof CassKeyspaceMeta 3394 * 3395 * @param[in] keyspace_meta 3396 * @param[in] name 3397 * @param[in] name_length 3398 * @param[in] arguments 3399 * @param[in] arguments_length 3400 * @return same as cass_keyspace_meta_function_by_name() 3401 * 3402 * @see cass_keyspace_meta_function_by_name() 3403 */ 3404 CASS_EXPORT const CassFunctionMeta* 3405 cass_keyspace_meta_function_by_name_n(const CassKeyspaceMeta* keyspace_meta, 3406 const char* name, 3407 size_t name_length, 3408 const char* arguments, 3409 size_t arguments_length); 3410 3411 /** 3412 * Gets the aggregate metadata for the provided aggregate name. 3413 * 3414 * @cassandra{2.2+} 3415 * 3416 * @public @memberof CassKeyspaceMeta 3417 * 3418 * @param[in] keyspace_meta 3419 * @param[in] name 3420 * @param[in] arguments A comma delimited list of CQL types (e.g "text,int,...") 3421 * describing the aggregate's signature. 3422 * 3423 * @return The data aggregate for a user defined aggregate. NULL if aggregate does not exist. 3424 */ 3425 CASS_EXPORT const CassAggregateMeta* 3426 cass_keyspace_meta_aggregate_by_name(const CassKeyspaceMeta* keyspace_meta, 3427 const char* name, 3428 const char* arguments); 3429 3430 /** 3431 * Same as cass_keyspace_meta_aggregate_by_name(), but with lengths for string 3432 * parameters. 3433 * 3434 * @cassandra{2.2+} 3435 * 3436 * @public @memberof CassKeyspaceMeta 3437 * 3438 * @param[in] keyspace_meta 3439 * @param[in] name 3440 * @param[in] name_length 3441 * @param[in] arguments 3442 * @param[in] arguments_length 3443 * @return same as cass_keyspace_meta_aggregate_by_name() 3444 * 3445 * @see cass_keyspace_meta_aggregate_by_name() 3446 */ 3447 CASS_EXPORT const CassAggregateMeta* 3448 cass_keyspace_meta_aggregate_by_name_n(const CassKeyspaceMeta* keyspace_meta, 3449 const char* name, 3450 size_t name_length, 3451 const char* arguments, 3452 size_t arguments_length); 3453 3454 /** 3455 * Gets a metadata field for the provided name. Metadata fields allow direct 3456 * access to the column data found in the underlying "keyspaces" metadata table. 3457 * 3458 * @public @memberof CassKeyspaceMeta 3459 * 3460 * @param[in] keyspace_meta 3461 * @param[in] name 3462 * @return A metadata field value. NULL if the field does not exist. 3463 */ 3464 CASS_EXPORT const CassValue* 3465 cass_keyspace_meta_field_by_name(const CassKeyspaceMeta* keyspace_meta, 3466 const char* name); 3467 3468 /** 3469 * Same as cass_keyspace_meta_field_by_name(), but with lengths for string 3470 * parameters. 3471 * 3472 * @public @memberof CassKeyspaceMeta 3473 * 3474 * @param[in] keyspace_meta 3475 * @param[in] name 3476 * @param[in] name_length 3477 * @return same as cass_keyspace_meta_field_by_name() 3478 * 3479 * @see cass_keyspace_meta_field_by_name() 3480 */ 3481 CASS_EXPORT const CassValue* 3482 cass_keyspace_meta_field_by_name_n(const CassKeyspaceMeta* keyspace_meta, 3483 const char* name, 3484 size_t name_length); 3485 3486 /** 3487 * Gets the name of the table. 3488 * 3489 * @public @memberof CassTableMeta 3490 * 3491 * @param[in] table_meta 3492 * @param[out] name 3493 * @param[out] name_length 3494 */ 3495 CASS_EXPORT void 3496 cass_table_meta_name(const CassTableMeta* table_meta, 3497 const char** name, 3498 size_t* name_length); 3499 3500 /** 3501 * Determine if the table is a virtual table. 3502 * 3503 * @public @memberof CassTableMeta 3504 * 3505 * @param[in] table_meta 3506 * @return cass_true is the table is virtual, otherwise cass_false 3507 */ 3508 CASS_EXPORT cass_bool_t 3509 cass_table_meta_is_virtual(const CassTableMeta* table_meta); 3510 3511 /** 3512 * Gets the column metadata for the provided column name. 3513 * 3514 * @public @memberof CassTableMeta 3515 * 3516 * @param[in] table_meta 3517 * @param[in] column 3518 * 3519 * @return The metadata for a column. NULL if column does not exist. 3520 */ 3521 CASS_EXPORT const CassColumnMeta* 3522 cass_table_meta_column_by_name(const CassTableMeta* table_meta, 3523 const char* column); 3524 3525 /** 3526 * Same as cass_table_meta_column_by_name(), but with lengths for string 3527 * parameters. 3528 * 3529 * @public @memberof CassTableMeta 3530 * 3531 * @param[in] table_meta 3532 * @param[in] column 3533 * @param[in] column_length 3534 * @return same as cass_table_meta_column_by_name() 3535 * 3536 * @see cass_table_meta_column_by_name() 3537 */ 3538 CASS_EXPORT const CassColumnMeta* 3539 cass_table_meta_column_by_name_n(const CassTableMeta* table_meta, 3540 const char* column, 3541 size_t column_length); 3542 3543 /** 3544 * Gets the total number of columns for the table. 3545 * 3546 * @public @memberof CassTableMeta 3547 * 3548 * @param[in] table_meta 3549 * @return The total column count. 3550 */ 3551 CASS_EXPORT size_t 3552 cass_table_meta_column_count(const CassTableMeta* table_meta); 3553 3554 /** 3555 * Gets the column metadata for the provided index. 3556 * 3557 * @public @memberof CassTableMeta 3558 * 3559 * @param[in] table_meta 3560 * @param[in] index 3561 * @return The metadata for a column. NULL returned if the index is out of range. 3562 */ 3563 CASS_EXPORT const CassColumnMeta* 3564 cass_table_meta_column(const CassTableMeta* table_meta, 3565 size_t index); 3566 3567 /** 3568 * Gets the index metadata for the provided index name. 3569 * 3570 * @public @memberof CassTableMeta 3571 * 3572 * @param[in] table_meta 3573 * @param[in] index 3574 * 3575 * @return The metadata for a index. NULL if index does not exist. 3576 */ 3577 CASS_EXPORT const CassIndexMeta* 3578 cass_table_meta_index_by_name(const CassTableMeta* table_meta, 3579 const char* index); 3580 3581 /** 3582 * Same as cass_table_meta_index_by_name(), but with lengths for string 3583 * parameters. 3584 * 3585 * @public @memberof CassTableMeta 3586 * 3587 * @param[in] table_meta 3588 * @param[in] index 3589 * @param[in] index_length 3590 * @return same as cass_table_meta_index_by_name() 3591 * 3592 * @see cass_table_meta_index_by_name() 3593 */ 3594 CASS_EXPORT const CassIndexMeta* 3595 cass_table_meta_index_by_name_n(const CassTableMeta* table_meta, 3596 const char* index, 3597 size_t index_length); 3598 3599 /** 3600 * Gets the total number of indexes for the table. 3601 * 3602 * @public @memberof CassTableMeta 3603 * 3604 * @param[in] table_meta 3605 * @return The total index count. 3606 */ 3607 CASS_EXPORT size_t 3608 cass_table_meta_index_count(const CassTableMeta* table_meta); 3609 3610 /** 3611 * Gets the index metadata for the provided index. 3612 * 3613 * @public @memberof CassTableMeta 3614 * 3615 * @param[in] table_meta 3616 * @param[in] index 3617 * @return The metadata for a index. NULL returned if the index is out of range. 3618 */ 3619 CASS_EXPORT const CassIndexMeta* 3620 cass_table_meta_index(const CassTableMeta* table_meta, 3621 size_t index); 3622 3623 /** 3624 * Gets the materialized view metadata for the provided view name. 3625 * 3626 * @cassandra{3.0+} 3627 * 3628 * @public @memberof CassTableMeta 3629 * 3630 * @param[in] table_meta 3631 * @param[in] view 3632 * 3633 * @return The metadata for a view. NULL if view does not exist. 3634 */ 3635 CASS_EXPORT const CassMaterializedViewMeta* 3636 cass_table_meta_materialized_view_by_name(const CassTableMeta* table_meta, 3637 const char* view); 3638 3639 /** 3640 * Same as cass_table_meta_materialized_view_by_name(), but with lengths for string 3641 * parameters. 3642 * 3643 * @cassandra{3.0+} 3644 * 3645 * @public @memberof CassTableMeta 3646 * 3647 * @param[in] table_meta 3648 * @param[in] view 3649 * @param[in] view_length 3650 * @return same as cass_table_meta_materialized_view_by_name() 3651 * 3652 * @see cass_table_meta_materialized_view_by_name() 3653 */ 3654 CASS_EXPORT const CassMaterializedViewMeta* 3655 cass_table_meta_materialized_view_by_name_n(const CassTableMeta* table_meta, 3656 const char* view, 3657 size_t view_length); 3658 3659 /** 3660 * Gets the total number of views for the table. 3661 * 3662 * @cassandra{3.0+} 3663 * 3664 * @public @memberof CassTableMeta 3665 * 3666 * @param[in] table_meta 3667 * @return The total view count. 3668 */ 3669 CASS_EXPORT size_t 3670 cass_table_meta_materialized_view_count(const CassTableMeta* table_meta); 3671 3672 /** 3673 * Gets the materialized view metadata for the provided index. 3674 * 3675 * @cassandra{3.0+} 3676 * 3677 * @public @memberof CassTableMeta 3678 * 3679 * @param[in] table_meta 3680 * @param[in] index 3681 * @return The metadata for a view. NULL returned if the index is out of range. 3682 */ 3683 CASS_EXPORT const CassMaterializedViewMeta* 3684 cass_table_meta_materialized_view(const CassTableMeta* table_meta, 3685 size_t index); 3686 3687 /** 3688 * Gets the number of columns for the table's partition key. 3689 * 3690 * @public @memberof CassTableMeta 3691 * 3692 * @param[in] table_meta 3693 * @return The count for the number of columns in the partition key. 3694 */ 3695 CASS_EXPORT size_t 3696 cass_table_meta_partition_key_count(const CassTableMeta* table_meta); 3697 3698 /** 3699 * Gets the partition key column metadata for the provided index. 3700 * 3701 * @public @memberof CassTableMeta 3702 * 3703 * @param[in] table_meta 3704 * @param[in] index 3705 * @return The metadata for a column. NULL returned if the index is out of range. 3706 * 3707 * @see cass_table_meta_partition_key_count() 3708 */ 3709 CASS_EXPORT const CassColumnMeta* 3710 cass_table_meta_partition_key(const CassTableMeta* table_meta, 3711 size_t index); 3712 3713 /** 3714 * Gets the number of columns for the table's clustering key. 3715 * 3716 * @public @memberof CassTableMeta 3717 * 3718 * @param[in] table_meta 3719 * @return The count for the number of columns in the clustering key. 3720 */ 3721 CASS_EXPORT size_t 3722 cass_table_meta_clustering_key_count(const CassTableMeta* table_meta); 3723 3724 /** 3725 * Gets the clustering key column metadata for the provided index. 3726 * 3727 * @public @memberof CassTableMeta 3728 * 3729 * @param[in] table_meta 3730 * @param[in] index 3731 * @return The metadata for a column. NULL returned if the index is out of range. 3732 * 3733 * @see cass_table_meta_clustering_key_count() 3734 */ 3735 CASS_EXPORT const CassColumnMeta* 3736 cass_table_meta_clustering_key(const CassTableMeta* table_meta, 3737 size_t index); 3738 3739 /** 3740 * Gets the clustering order column metadata for the provided index. 3741 * 3742 * @public @memberof CassTableMeta 3743 * 3744 * @param[in] table_meta 3745 * @param[in] index 3746 * @return The clustering order for a column. 3747 * CASS_CLUSTERING_ORDER_NONE returned if the index is out of range. 3748 * 3749 * @see cass_table_meta_clustering_key_count() 3750 */ 3751 CASS_EXPORT CassClusteringOrder 3752 cass_table_meta_clustering_key_order(const CassTableMeta* table_meta, 3753 size_t index); 3754 3755 /** 3756 * Gets a metadata field for the provided name. Metadata fields allow direct 3757 * access to the column data found in the underlying "tables" metadata table. 3758 * 3759 * @public @memberof CassTableMeta 3760 * 3761 * @param[in] table_meta 3762 * @param[in] name 3763 * @return A metadata field value. NULL if the field does not exist. 3764 */ 3765 CASS_EXPORT const CassValue* 3766 cass_table_meta_field_by_name(const CassTableMeta* table_meta, 3767 const char* name); 3768 3769 /** 3770 * Same as cass_table_meta_field_by_name(), but with lengths for string 3771 * parameters. 3772 * 3773 * @public @memberof CassTableMeta 3774 * 3775 * @param[in] table_meta 3776 * @param[in] name 3777 * @param[in] name_length 3778 * @return same as cass_table_meta_field_by_name() 3779 * 3780 * @see cass_table_meta_field_by_name() 3781 */ 3782 CASS_EXPORT const CassValue* 3783 cass_table_meta_field_by_name_n(const CassTableMeta* table_meta, 3784 const char* name, 3785 size_t name_length); 3786 3787 /** 3788 * Gets the column metadata for the provided column name. 3789 * 3790 * @cassandra{3.0+} 3791 * 3792 * @public @memberof CassMaterializedViewMeta 3793 * 3794 * @param[in] view_meta 3795 * @param[in] column 3796 * 3797 * @return The metadata for a column. NULL if column does not exist. 3798 */ 3799 CASS_EXPORT const CassColumnMeta* 3800 cass_materialized_view_meta_column_by_name(const CassMaterializedViewMeta* view_meta, 3801 const char* column); 3802 3803 /** 3804 * Same as cass_materialized_view_meta_column_by_name(), but with lengths for string 3805 * parameters. 3806 * 3807 * @cassandra{3.0+} 3808 * 3809 * @public @memberof CassMaterializedViewMeta 3810 * 3811 * @param[in] view_meta 3812 * @param[in] column 3813 * @param[in] column_length 3814 * @return same as cass_materialized_view_meta_column_by_name() 3815 * 3816 * @see cass_materialized_view_meta_column_by_name() 3817 */ 3818 CASS_EXPORT const CassColumnMeta* 3819 cass_materialized_view_meta_column_by_name_n(const CassMaterializedViewMeta* view_meta, 3820 const char* column, 3821 size_t column_length); 3822 3823 /** 3824 * Gets the name of the view. 3825 * 3826 * @cassandra{3.0+} 3827 * 3828 * @public @memberof CassMaterializedViewMeta 3829 * 3830 * @param[in] view_meta 3831 * @param[out] name 3832 * @param[out] name_length 3833 */ 3834 CASS_EXPORT void 3835 cass_materialized_view_meta_name(const CassMaterializedViewMeta* view_meta, 3836 const char** name, 3837 size_t* name_length); 3838 3839 /** 3840 * Gets the base table of the view. 3841 * 3842 * @cassandra{3.0+} 3843 * 3844 * @public @memberof CassMaterializedViewMeta 3845 * 3846 * @param[in] view_meta 3847 * 3848 * @return The base table for the view. 3849 */ 3850 CASS_EXPORT const CassTableMeta* 3851 cass_materialized_view_meta_base_table(const CassMaterializedViewMeta* view_meta); 3852 3853 /** 3854 * Gets the total number of columns for the view. 3855 * 3856 * @cassandra{3.0+} 3857 * 3858 * @public @memberof CassMaterializedViewMeta 3859 * 3860 * @param[in] view_meta 3861 * @return The total column count. 3862 */ 3863 CASS_EXPORT size_t 3864 cass_materialized_view_meta_column_count(const CassMaterializedViewMeta* view_meta); 3865 3866 /** 3867 * Gets the column metadata for the provided index. 3868 * 3869 * @cassandra{3.0+} 3870 * 3871 * @public @memberof CassMaterializedViewMeta 3872 * 3873 * @param[in] view_meta 3874 * @param[in] index 3875 * @return The metadata for a column. NULL returned if the index is out of range. 3876 */ 3877 CASS_EXPORT const CassColumnMeta* 3878 cass_materialized_view_meta_column(const CassMaterializedViewMeta* view_meta, 3879 size_t index); 3880 3881 /** 3882 * Gets the number of columns for the view's partition key. 3883 * 3884 * @cassandra{3.0+} 3885 * 3886 * @public @memberof CassMaterializedViewMeta 3887 * 3888 * @param[in] view_meta 3889 * @return The count for the number of columns in the partition key. 3890 */ 3891 CASS_EXPORT size_t 3892 cass_materialized_view_meta_partition_key_count(const CassMaterializedViewMeta* view_meta); 3893 3894 /** 3895 * Gets the partition key column metadata for the provided index. 3896 * 3897 * @cassandra{3.0+} 3898 * 3899 * @public @memberof CassMaterializedViewMeta 3900 * 3901 * @param[in] view_meta 3902 * @param[in] index 3903 * @return The metadata for a column. NULL returned if the index is out of range. 3904 */ 3905 CASS_EXPORT const CassColumnMeta* 3906 cass_materialized_view_meta_partition_key(const CassMaterializedViewMeta* view_meta, 3907 size_t index); 3908 3909 /** 3910 * Gets the number of columns for the view's clustering key. 3911 * 3912 * @cassandra{3.0+} 3913 * 3914 * @public @memberof CassMaterializedViewMeta 3915 * 3916 * @param[in] view_meta 3917 * @return The count for the number of columns in the clustering key. 3918 */ 3919 CASS_EXPORT size_t 3920 cass_materialized_view_meta_clustering_key_count(const CassMaterializedViewMeta* view_meta); 3921 3922 /** 3923 * Gets the clustering key column metadata for the provided index. 3924 * 3925 * @cassandra{3.0+} 3926 * 3927 * @public @memberof CassMaterializedViewMeta 3928 * 3929 * @param[in] view_meta 3930 * @param[in] index 3931 * @return The metadata for a column. NULL returned if the index is out of range. 3932 */ 3933 CASS_EXPORT const CassColumnMeta* 3934 cass_materialized_view_meta_clustering_key(const CassMaterializedViewMeta* view_meta, 3935 size_t index); 3936 3937 /** 3938 * Gets the clustering order column metadata for the provided index. 3939 * 3940 * @public @memberof CassMaterializedViewMeta 3941 * 3942 * @param[in] view_meta 3943 * @param[in] index 3944 * @return The clustering order for a column. 3945 * CASS_CLUSTERING_ORDER_NONE returned if the index is out of range. 3946 * 3947 * @see cass_materialized_view_meta_clustering_key_count() 3948 */ 3949 CASS_EXPORT CassClusteringOrder 3950 cass_materialized_view_meta_clustering_key_order(const CassMaterializedViewMeta* view_meta, 3951 size_t index); 3952 3953 /** 3954 * Gets a metadata field for the provided name. Metadata fields allow direct 3955 * access to the column data found in the underlying "views" metadata view. 3956 * 3957 * @cassandra{3.0+} 3958 * 3959 * @public @memberof CassMaterializedViewMeta 3960 * 3961 * @param[in] view_meta 3962 * @param[in] name 3963 * @return A metadata field value. NULL if the field does not exist. 3964 */ 3965 CASS_EXPORT const CassValue* 3966 cass_materialized_view_meta_field_by_name(const CassMaterializedViewMeta* view_meta, 3967 const char* name); 3968 3969 /** 3970 * Same as cass_materialized_view_meta_field_by_name(), but with lengths for string 3971 * parameters. 3972 * 3973 * @cassandra{3.0+} 3974 * 3975 * @public @memberof CassMaterializedViewMeta 3976 * 3977 * @param[in] view_meta 3978 * @param[in] name 3979 * @param[in] name_length 3980 * @return same as cass_materialized_view_meta_field_by_name() 3981 * 3982 * @see cass_materialized_view_meta_field_by_name() 3983 */ 3984 CASS_EXPORT const CassValue* 3985 cass_materialized_view_meta_field_by_name_n(const CassMaterializedViewMeta* view_meta, 3986 const char* name, 3987 size_t name_length); 3988 3989 /** 3990 * Gets the name of the column. 3991 * 3992 * @public @memberof CassColumnMeta 3993 * 3994 * @param[in] column_meta 3995 * @param[out] name 3996 * @param[out] name_length 3997 */ 3998 CASS_EXPORT void 3999 cass_column_meta_name(const CassColumnMeta* column_meta, 4000 const char** name, 4001 size_t* name_length); 4002 4003 /** 4004 * Gets the type of the column. 4005 * 4006 * @public @memberof CassColumnMeta 4007 * 4008 * @param[in] column_meta 4009 * @return The column's type. 4010 */ 4011 CASS_EXPORT CassColumnType 4012 cass_column_meta_type(const CassColumnMeta* column_meta); 4013 4014 /** 4015 * Gets the data type of the column. 4016 * 4017 * @public @memberof CassColumnMeta 4018 * 4019 * @param[in] column_meta 4020 * @return The column's data type. 4021 */ 4022 CASS_EXPORT const CassDataType* 4023 cass_column_meta_data_type(const CassColumnMeta* column_meta); 4024 4025 /** 4026 * Gets a metadata field for the provided name. Metadata fields allow direct 4027 * access to the column data found in the underlying "columns" metadata table. 4028 * 4029 * @public @memberof CassColumnMeta 4030 * 4031 * @param[in] column_meta 4032 * @param[in] name 4033 * @return A metadata field value. NULL if the field does not exist. 4034 */ 4035 CASS_EXPORT const CassValue* 4036 cass_column_meta_field_by_name(const CassColumnMeta* column_meta, 4037 const char* name); 4038 4039 /** 4040 * Same as cass_column_meta_field_by_name(), but with lengths for string 4041 * parameters. 4042 * 4043 * @public @memberof CassColumnMeta 4044 * 4045 * @param[in] column_meta 4046 * @param[in] name 4047 * @param[in] name_length 4048 * @return same as cass_column_meta_field_by_name() 4049 * 4050 * @see cass_column_meta_field_by_name() 4051 */ 4052 CASS_EXPORT const CassValue* 4053 cass_column_meta_field_by_name_n(const CassColumnMeta* column_meta, 4054 const char* name, 4055 size_t name_length); 4056 4057 /** 4058 * Gets the name of the index. 4059 * 4060 * @public @memberof CassIndexMeta 4061 * 4062 * @param[in] index_meta 4063 * @param[out] name 4064 * @param[out] name_length 4065 */ 4066 CASS_EXPORT void 4067 cass_index_meta_name(const CassIndexMeta* index_meta, 4068 const char** name, 4069 size_t* name_length); 4070 4071 /** 4072 * Gets the type of the index. 4073 * 4074 * @public @memberof CassIndexMeta 4075 * 4076 * @param[in] index_meta 4077 * @return The index's type. 4078 */ 4079 CASS_EXPORT CassIndexType 4080 cass_index_meta_type(const CassIndexMeta* index_meta); 4081 4082 /** 4083 * Gets the target of the index. 4084 * 4085 * @public @memberof CassIndexMeta 4086 * 4087 * @param[in] index_meta 4088 * @param[out] target 4089 * @param[out] target_length 4090 */ 4091 CASS_EXPORT void 4092 cass_index_meta_target(const CassIndexMeta* index_meta, 4093 const char** target, 4094 size_t* target_length); 4095 4096 /** 4097 * Gets the options of the index. 4098 * 4099 * @public @memberof CassIndexMeta 4100 * 4101 * @param[in] index_meta 4102 * @return The index's options. 4103 */ 4104 CASS_EXPORT const CassValue* 4105 cass_index_meta_options(const CassIndexMeta* index_meta); 4106 4107 /** 4108 * Gets a metadata field for the provided name. Metadata fields allow direct 4109 * access to the index data found in the underlying "indexes" metadata table. 4110 * 4111 * @public @memberof CassIndexMeta 4112 * 4113 * @param[in] index_meta 4114 * @param[in] name 4115 * @return A metadata field value. NULL if the field does not exist. 4116 */ 4117 CASS_EXPORT const CassValue* 4118 cass_index_meta_field_by_name(const CassIndexMeta* index_meta, 4119 const char* name); 4120 4121 /** 4122 * Same as cass_index_meta_field_by_name(), but with lengths for string 4123 * parameters. 4124 * 4125 * @public @memberof CassIndexMeta 4126 * 4127 * @param[in] index_meta 4128 * @param[in] name 4129 * @param[in] name_length 4130 * @return same as cass_index_meta_field_by_name() 4131 * 4132 * @see cass_index_meta_field_by_name() 4133 */ 4134 CASS_EXPORT const CassValue* 4135 cass_index_meta_field_by_name_n(const CassIndexMeta* index_meta, 4136 const char* name, 4137 size_t name_length); 4138 4139 /** 4140 * Gets the name of the function. 4141 * 4142 * @cassandra{2.2+} 4143 * 4144 * @public @memberof CassFunctionMeta 4145 * 4146 * @param[in] function_meta 4147 * @param[out] name 4148 * @param[out] name_length 4149 */ 4150 CASS_EXPORT void 4151 cass_function_meta_name(const CassFunctionMeta* function_meta, 4152 const char** name, 4153 size_t* name_length); 4154 4155 /** 4156 * Gets the full name of the function. The full name includes the 4157 * function's name and the function's signature: 4158 * "name(type1 type2.. typeN)". 4159 * 4160 * @cassandra{2.2+} 4161 * 4162 * @public @memberof CassFunctionMeta 4163 * 4164 * @param[in] function_meta 4165 * @param[out] full_name 4166 * @param[out] full_name_length 4167 */ 4168 CASS_EXPORT void 4169 cass_function_meta_full_name(const CassFunctionMeta* function_meta, 4170 const char** full_name, 4171 size_t* full_name_length); 4172 4173 /** 4174 * Gets the body of the function. 4175 * 4176 * @cassandra{2.2+} 4177 * 4178 * @public @memberof CassFunctionMeta 4179 * 4180 * @param[in] function_meta 4181 * @param[out] body 4182 * @param[out] body_length 4183 */ 4184 CASS_EXPORT void 4185 cass_function_meta_body(const CassFunctionMeta* function_meta, 4186 const char** body, 4187 size_t* body_length); 4188 4189 /** 4190 * Gets the language of the function. 4191 * 4192 * @cassandra{2.2+} 4193 * 4194 * @public @memberof CassFunctionMeta 4195 * 4196 * @param[in] function_meta 4197 * @param[out] language 4198 * @param[out] language_length 4199 */ 4200 CASS_EXPORT void 4201 cass_function_meta_language(const CassFunctionMeta* function_meta, 4202 const char** language, 4203 size_t* language_length); 4204 4205 /** 4206 * Gets whether a function is called on "null". 4207 * 4208 * @cassandra{2.2+} 4209 * 4210 * @public @memberof CassFunctionMeta 4211 * 4212 * @param[in] function_meta 4213 * @return cass_true if a function is called on null, otherwise cass_false. 4214 */ 4215 CASS_EXPORT cass_bool_t 4216 cass_function_meta_called_on_null_input(const CassFunctionMeta* function_meta); 4217 4218 /** 4219 * Gets the number of arguments this function takes. 4220 * 4221 * @cassandra{2.2+} 4222 * 4223 * @public @memberof CassFunctionMeta 4224 * 4225 * @param[in] function_meta 4226 * @return The number of arguments. 4227 */ 4228 CASS_EXPORT size_t 4229 cass_function_meta_argument_count(const CassFunctionMeta* function_meta); 4230 4231 /** 4232 * Gets the function's argument name and type for the provided index. 4233 * 4234 * @cassandra{2.2+} 4235 * 4236 * @public @memberof CassFunctionMeta 4237 * 4238 * @param[in] function_meta 4239 * @param[in] index 4240 * @param[out] name 4241 * @param[out] name_length 4242 * @param[out] type 4243 * @return CASS_OK if successful, otherwise an error occurred 4244 */ 4245 CASS_EXPORT CassError 4246 cass_function_meta_argument(const CassFunctionMeta* function_meta, 4247 size_t index, 4248 const char** name, 4249 size_t* name_length, 4250 const CassDataType** type); 4251 4252 /** 4253 * Gets the function's argument and type for the provided name. 4254 * 4255 * @cassandra{2.2+} 4256 * 4257 * @public @memberof CassFunctionMeta 4258 * 4259 * @param[in] function_meta 4260 * @param[in] name 4261 * @return A data type. NULL if the argument does not exist. 4262 */ 4263 CASS_EXPORT const CassDataType* 4264 cass_function_meta_argument_type_by_name(const CassFunctionMeta* function_meta, 4265 const char* name); 4266 4267 /** 4268 * Same as cass_function_meta_argument_type_by_name(), but with lengths for string 4269 * parameters. 4270 * 4271 * @cassandra{2.2+} 4272 * 4273 * @public @memberof CassFunctionMeta 4274 * 4275 * @param[in] function_meta 4276 * @param[in] name 4277 * @param[in] name_length 4278 * @return same as cass_function_meta_argument_type_by_name() 4279 * 4280 * @see cass_function_meta_argument_type_by_name() 4281 */ 4282 CASS_EXPORT const CassDataType* 4283 cass_function_meta_argument_type_by_name_n(const CassFunctionMeta* function_meta, 4284 const char* name, 4285 size_t name_length); 4286 4287 /** 4288 * Gets the return type of the function. 4289 * 4290 * @cassandra{2.2+} 4291 * 4292 * @public @memberof CassFunctionMeta 4293 * 4294 * @param[in] function_meta 4295 * @return The data type returned by the function. 4296 */ 4297 CASS_EXPORT const CassDataType* 4298 cass_function_meta_return_type(const CassFunctionMeta* function_meta); 4299 4300 /** 4301 * Gets a metadata field for the provided name. Metadata fields allow direct 4302 * access to the column data found in the underlying "functions" metadata table. 4303 * 4304 * @cassandra{2.2+} 4305 * 4306 * @public @memberof CassFunctionMeta 4307 * 4308 * @param[in] function_meta 4309 * @param[in] name 4310 * @return A metadata field value. NULL if the field does not exist. 4311 */ 4312 CASS_EXPORT const CassValue* 4313 cass_function_meta_field_by_name(const CassFunctionMeta* function_meta, 4314 const char* name); 4315 4316 /** 4317 * Same as cass_function_meta_field_by_name(), but with lengths for string 4318 * parameters. 4319 * 4320 * @cassandra{2.2+} 4321 * 4322 * @public @memberof CassFunctionMeta 4323 * 4324 * @param[in] function_meta 4325 * @param[in] name 4326 * @param[in] name_length 4327 * @return same as cass_function_meta_field_by_name() 4328 * 4329 * @see cass_function_meta_field_by_name() 4330 */ 4331 CASS_EXPORT const CassValue* 4332 cass_function_meta_field_by_name_n(const CassFunctionMeta* function_meta, 4333 const char* name, 4334 size_t name_length); 4335 4336 /** 4337 * Gets the name of the aggregate. 4338 * 4339 * @cassandra{2.2+} 4340 * 4341 * @public @memberof CassAggregateMeta 4342 * 4343 * @param[in] aggregate_meta 4344 * @param[out] name 4345 * @param[out] name_length 4346 */ 4347 CASS_EXPORT void 4348 cass_aggregate_meta_name(const CassAggregateMeta* aggregate_meta, 4349 const char** name, 4350 size_t* name_length); 4351 4352 /** 4353 * Gets the full name of the aggregate. The full name includes the 4354 * aggregate's name and the aggregate's signature: 4355 * "name(type1 type2.. typeN)". 4356 * 4357 * @cassandra{2.2+} 4358 * 4359 * @public @memberof CassAggregateMeta 4360 * 4361 * @param[in] aggregate_meta 4362 * @param[out] full_name 4363 * @param[out] full_name_length 4364 */ 4365 CASS_EXPORT void 4366 cass_aggregate_meta_full_name(const CassAggregateMeta* aggregate_meta, 4367 const char** full_name, 4368 size_t* full_name_length); 4369 4370 /** 4371 * Gets the number of arguments this aggregate takes. 4372 * 4373 * @cassandra{2.2+} 4374 * 4375 * @public @memberof CassAggregateMeta 4376 * 4377 * @param[in] aggregate_meta 4378 * @return The number of arguments. 4379 */ 4380 CASS_EXPORT size_t 4381 cass_aggregate_meta_argument_count(const CassAggregateMeta* aggregate_meta); 4382 4383 /** 4384 * Gets the aggregate's argument type for the provided index. 4385 * 4386 * @cassandra{2.2+} 4387 * 4388 * @public @memberof CassAggregateMeta 4389 * 4390 * @param[in] aggregate_meta 4391 * @param[in] index 4392 * @return The data type for argument. NULL returned if the index is out of range. 4393 */ 4394 CASS_EXPORT const CassDataType* 4395 cass_aggregate_meta_argument_type(const CassAggregateMeta* aggregate_meta, 4396 size_t index); 4397 4398 /** 4399 * Gets the return type of the aggregate. 4400 * 4401 * @cassandra{2.2+} 4402 * 4403 * @public @memberof CassAggregateMeta 4404 * 4405 * @param[in] aggregate_meta 4406 * @return The data type returned by the aggregate. 4407 */ 4408 CASS_EXPORT const CassDataType* 4409 cass_aggregate_meta_return_type(const CassAggregateMeta* aggregate_meta); 4410 4411 /** 4412 * Gets the state type of the aggregate. 4413 * 4414 * @cassandra{2.2+} 4415 * 4416 * @public @memberof CassAggregateMeta 4417 * 4418 * @param[in] aggregate_meta 4419 * @return The data type of the aggregate's state. 4420 */ 4421 CASS_EXPORT const CassDataType* 4422 cass_aggregate_meta_state_type(const CassAggregateMeta* aggregate_meta); 4423 4424 /** 4425 * Gets the function metadata for the aggregate's state function. 4426 * 4427 * @cassandra{2.2+} 4428 * 4429 * @public @memberof CassAggregateMeta 4430 * 4431 * @param[in] aggregate_meta 4432 * @return The function metadata for the state function. 4433 */ 4434 CASS_EXPORT const CassFunctionMeta* 4435 cass_aggregate_meta_state_func(const CassAggregateMeta* aggregate_meta); 4436 4437 /** 4438 * Gets the function metadata for the aggregates's final function. 4439 * 4440 * @cassandra{2.2+} 4441 * 4442 * @public @memberof CassAggregateMeta 4443 * 4444 * @param[in] aggregate_meta 4445 * @return The function metadata for the final function. 4446 */ 4447 CASS_EXPORT const CassFunctionMeta* 4448 cass_aggregate_meta_final_func(const CassAggregateMeta* aggregate_meta); 4449 4450 /** 4451 * Gets the initial condition value for the aggregate. 4452 * 4453 * @cassandra{2.2+} 4454 * 4455 * <b>Note:</b> The value of the initial condition will always be 4456 * a "varchar" type for Cassandra 3.0+. 4457 * 4458 * @public @memberof CassAggregateMeta 4459 * 4460 * @param[in] aggregate_meta 4461 * @return The value of the initial condition. 4462 */ 4463 CASS_EXPORT const CassValue* 4464 cass_aggregate_meta_init_cond(const CassAggregateMeta* aggregate_meta); 4465 4466 /** 4467 * Gets a metadata field for the provided name. Metadata fields allow direct 4468 * access to the column data found in the underlying "aggregates" metadata table. 4469 * 4470 * @cassandra{2.2+} 4471 * 4472 * @public @memberof CassAggregateMeta 4473 * 4474 * @param[in] aggregate_meta 4475 * @param[in] name 4476 * @return A metadata field value. NULL if the field does not exist. 4477 */ 4478 CASS_EXPORT const CassValue* 4479 cass_aggregate_meta_field_by_name(const CassAggregateMeta* aggregate_meta, 4480 const char* name); 4481 4482 /** 4483 * Same as cass_aggregate_meta_field_by_name(), but with lengths for string 4484 * parameters. 4485 * 4486 * @cassandra{2.2+} 4487 * 4488 * @public @memberof CassAggregateMeta 4489 * 4490 * @param[in] aggregate_meta 4491 * @param[in] name 4492 * @param[in] name_length 4493 * @return same as cass_aggregate_meta_field_by_name() 4494 * 4495 * @see cass_aggregate_meta_field_by_name() 4496 */ 4497 CASS_EXPORT const CassValue* 4498 cass_aggregate_meta_field_by_name_n(const CassAggregateMeta* aggregate_meta, 4499 const char* name, 4500 size_t name_length); 4501 4502 /*********************************************************************************** 4503 * 4504 * SSL 4505 * 4506 ************************************************************************************/ 4507 4508 /** 4509 * Creates a new SSL context. 4510 * 4511 * @public @memberof CassSsl 4512 * 4513 * @return Returns a SSL context that must be freed. 4514 * 4515 * @see cass_ssl_free() 4516 */ 4517 CASS_EXPORT CassSsl* 4518 cass_ssl_new(); 4519 4520 /** 4521 * Creates a new SSL context <b>without</b> initializing the underlying library 4522 * implementation. The integrating application is responsible for 4523 * initializing the underlying SSL implementation. The driver uses the SSL 4524 * implmentation from several threads concurrently so it's important that it's 4525 * properly setup for multithreaded use e.g. lock callbacks for OpenSSL. 4526 * 4527 * <b>Important:</b> The SSL library must be initialized before calling this 4528 * function. 4529 * 4530 * When using OpenSSL the following components need to be initialized: 4531 * 4532 * SSL_library_init(); 4533 * SSL_load_error_strings(); 4534 * OpenSSL_add_all_algorithms(); 4535 * 4536 * The following thread-safety callbacks also need to be set: 4537 * 4538 * CRYPTO_set_locking_callback(...); 4539 * CRYPTO_set_id_callback(...); 4540 * 4541 * @public @memberof CassSsl 4542 * 4543 * @return Returns a SSL context that must be freed. 4544 * 4545 * @see cass_ssl_new() 4546 * @see cass_ssl_free() 4547 */ 4548 CASS_EXPORT CassSsl* 4549 cass_ssl_new_no_lib_init(); 4550 4551 /** 4552 * Frees a SSL context instance. 4553 * 4554 * @public @memberof CassSsl 4555 * 4556 * @param[in] ssl 4557 */ 4558 CASS_EXPORT void 4559 cass_ssl_free(CassSsl* ssl); 4560 4561 /** 4562 * Adds a trusted certificate. This is used to verify 4563 * the peer's certificate. 4564 * 4565 * @public @memberof CassSsl 4566 * 4567 * @param[in] ssl 4568 * @param[in] cert PEM formatted certificate string 4569 * @return CASS_OK if successful, otherwise an error occurred 4570 */ 4571 CASS_EXPORT CassError 4572 cass_ssl_add_trusted_cert(CassSsl* ssl, 4573 const char* cert); 4574 4575 /** 4576 * Same as cass_ssl_add_trusted_cert(), but with lengths for string 4577 * parameters. 4578 * 4579 * @public @memberof CassSsl 4580 * 4581 * @param[in] ssl 4582 * @param[in] cert 4583 * @param[in] cert_length 4584 * @return same as cass_ssl_add_trusted_cert() 4585 * 4586 * @see cass_ssl_add_trusted_cert() 4587 */ 4588 CASS_EXPORT CassError 4589 cass_ssl_add_trusted_cert_n(CassSsl* ssl, 4590 const char* cert, 4591 size_t cert_length); 4592 4593 /** 4594 * Sets verification performed on the peer's certificate. 4595 * 4596 * CASS_SSL_VERIFY_NONE - No verification is performed 4597 * CASS_SSL_VERIFY_PEER_CERT - Certificate is present and valid 4598 * CASS_SSL_VERIFY_PEER_IDENTITY - IP address matches the certificate's 4599 * common name or one of its subject alternative names. This implies the 4600 * certificate is also present. 4601 * CASS_SSL_VERIFY_PEER_IDENTITY_DNS - Hostname matches the certificate's 4602 * common name or one of its subject alternative names. This implies the 4603 * certificate is also present. Hostname resolution must also be enabled. 4604 * 4605 * <b>Default:</b> CASS_SSL_VERIFY_PEER_CERT 4606 * 4607 * @public @memberof CassSsl 4608 * 4609 * @param[in] ssl 4610 * @param[in] flags 4611 * @return CASS_OK if successful, otherwise an error occurred 4612 * 4613 * @see cass_cluster_set_use_hostname_resolution() 4614 */ 4615 CASS_EXPORT void 4616 cass_ssl_set_verify_flags(CassSsl* ssl, 4617 int flags); 4618 4619 /** 4620 * Set client-side certificate chain. This is used to authenticate 4621 * the client on the server-side. This should contain the entire 4622 * Certificate chain starting with the certificate itself. 4623 * 4624 * @public @memberof CassSsl 4625 * 4626 * @param[in] ssl 4627 * @param[in] cert PEM formatted certificate string 4628 * @return CASS_OK if successful, otherwise an error occurred 4629 */ 4630 CASS_EXPORT CassError 4631 cass_ssl_set_cert(CassSsl* ssl, 4632 const char* cert); 4633 4634 /** 4635 * Same as cass_ssl_set_cert(), but with lengths for string 4636 * parameters. 4637 * 4638 * @public @memberof CassSsl 4639 * 4640 * @param[in] ssl 4641 * @param[in] cert 4642 * @param[in] cert_length 4643 * @return same as cass_ssl_set_cert() 4644 * 4645 * @see cass_ssl_set_cert() 4646 */ 4647 CASS_EXPORT CassError 4648 cass_ssl_set_cert_n(CassSsl* ssl, 4649 const char* cert, 4650 size_t cert_length); 4651 4652 /** 4653 * Set client-side private key. This is used to authenticate 4654 * the client on the server-side. 4655 * 4656 * @public @memberof CassSsl 4657 * 4658 * @param[in] ssl 4659 * @param[in] key PEM formatted key string 4660 * @param[in] password used to decrypt key 4661 * @return CASS_OK if successful, otherwise an error occurred 4662 */ 4663 CASS_EXPORT CassError 4664 cass_ssl_set_private_key(CassSsl* ssl, 4665 const char* key, 4666 const char* password); 4667 4668 /** 4669 * Same as cass_ssl_set_private_key(), but with lengths for string 4670 * parameters. 4671 * 4672 * @public @memberof CassSsl 4673 * 4674 * @param[in] ssl 4675 * @param[in] key 4676 * @param[in] key_length 4677 * @param[in] password 4678 * @param[in] password_length 4679 * @return same as cass_ssl_set_private_key() 4680 * 4681 * @see cass_ssl_set_private_key() 4682 */ 4683 CASS_EXPORT CassError 4684 cass_ssl_set_private_key_n(CassSsl* ssl, 4685 const char* key, 4686 size_t key_length, 4687 const char* password, 4688 size_t password_length); 4689 4690 /*********************************************************************************** 4691 * 4692 * Authenticator 4693 * 4694 ************************************************************************************/ 4695 4696 /** 4697 * Gets the IP address of the host being authenticated. 4698 * 4699 * @param[in] auth 4700 * @param[out] address 4701 * 4702 * @public @memberof CassAuthenticator 4703 */ 4704 CASS_EXPORT void 4705 cass_authenticator_address(const CassAuthenticator* auth, 4706 CassInet* address); 4707 4708 /** 4709 * Gets the hostname of the host being authenticated. 4710 * 4711 * @public @memberof CassAuthenticator 4712 * 4713 * @param[in] auth 4714 * @param[out] length 4715 * @return A null-terminated string. 4716 */ 4717 CASS_EXPORT const char* 4718 cass_authenticator_hostname(const CassAuthenticator* auth, 4719 size_t* length); 4720 4721 /** 4722 * Gets the class name for the server-side IAuthentication implementation. 4723 * 4724 * @public @memberof CassAuthenticator 4725 * 4726 * @param[in] auth 4727 * @param[out] length 4728 * @return A null-terminated string. 4729 */ 4730 CASS_EXPORT const char* 4731 cass_authenticator_class_name(const CassAuthenticator* auth, 4732 size_t* length); 4733 4734 /** 4735 * Gets the user data created during the authenticator exchange. This 4736 * is set using cass_authenticator_set_exchange_data(). 4737 * 4738 * @public @memberof CassAuthenticator 4739 * 4740 * @param[in] auth 4741 * @return User specified exchange data previously set by 4742 * cass_authenticator_set_exchange_data(). 4743 * 4744 * @see cass_authenticator_set_exchange_data() 4745 */ 4746 CASS_EXPORT void* 4747 cass_authenticator_exchange_data(CassAuthenticator* auth); 4748 4749 /** 4750 * Sets the user data to be used during the authenticator exchange. 4751 * 4752 * @public @memberof CassAuthenticator 4753 * 4754 * @param[in] auth 4755 * @param[in] exchange_data 4756 * 4757 * @see cass_authenticator_exchange_data() 4758 */ 4759 CASS_EXPORT void 4760 cass_authenticator_set_exchange_data(CassAuthenticator* auth, 4761 void* exchange_data); 4762 4763 /** 4764 * Gets a response token buffer of the provided size. 4765 * 4766 * @public @memberof CassAuthenticator 4767 * 4768 * @param[in] auth 4769 * @param[in] size 4770 * @return A buffer to copy the response token. 4771 */ 4772 CASS_EXPORT char* 4773 cass_authenticator_response(CassAuthenticator* auth, 4774 size_t size); 4775 4776 /** 4777 * Sets the response token. 4778 * 4779 * @public @memberof CassAuthenticator 4780 * 4781 * @param[in] auth 4782 * @param[in] response 4783 * @param[in] response_size 4784 */ 4785 CASS_EXPORT void 4786 cass_authenticator_set_response(CassAuthenticator* auth, 4787 const char* response, 4788 size_t response_size); 4789 4790 /** 4791 * Sets an error for the authenticator exchange. 4792 * 4793 * @public @memberof CassAuthenticator 4794 * 4795 * @param[in] auth 4796 * @param[in] message 4797 */ 4798 CASS_EXPORT void 4799 cass_authenticator_set_error(CassAuthenticator* auth, 4800 const char* message); 4801 4802 /** 4803 * Same as cass_authenticator_set_error(), but with lengths for string 4804 * parameters. 4805 * 4806 * @public @memberof CassAuthenticator 4807 * 4808 * @param[in] auth 4809 * @param[in] message 4810 * @param[in] message_length 4811 * 4812 * @see cass_authenticator_set_error() 4813 */ 4814 CASS_EXPORT void 4815 cass_authenticator_set_error_n(CassAuthenticator* auth, 4816 const char* message, 4817 size_t message_length); 4818 4819 /*********************************************************************************** 4820 * 4821 * Future 4822 * 4823 ***********************************************************************************/ 4824 4825 /** 4826 * Frees a future instance. A future can be freed anytime. 4827 * 4828 * @public @memberof CassFuture 4829 */ 4830 CASS_EXPORT void 4831 cass_future_free(CassFuture* future); 4832 4833 /** 4834 * Sets a callback that is called when a future is set 4835 * 4836 * @public @memberof CassFuture 4837 * 4838 * @param[in] future 4839 * @param[in] callback 4840 * @param[in] data 4841 * @return CASS_OK if successful, otherwise an error occurred 4842 */ 4843 CASS_EXPORT CassError 4844 cass_future_set_callback(CassFuture* future, 4845 CassFutureCallback callback, 4846 void* data); 4847 4848 /** 4849 * Gets the set status of the future. 4850 * 4851 * @public @memberof CassFuture 4852 * 4853 * @param[in] future 4854 * @return true if set 4855 */ 4856 CASS_EXPORT cass_bool_t 4857 cass_future_ready(CassFuture* future); 4858 4859 /** 4860 * Wait for the future to be set with either a result or error. 4861 * 4862 * <b>Important:</b> Do not wait in a future callback. Waiting in a future 4863 * callback will cause a deadlock. 4864 * 4865 * @public @memberof CassFuture 4866 * 4867 * @param[in] future 4868 */ 4869 CASS_EXPORT void 4870 cass_future_wait(CassFuture* future); 4871 4872 /** 4873 * Wait for the future to be set or timeout. 4874 * 4875 * @public @memberof CassFuture 4876 * 4877 * @param[in] future 4878 * @param[in] timeout_us wait time in microseconds 4879 * @return false if returned due to timeout 4880 */ 4881 CASS_EXPORT cass_bool_t 4882 cass_future_wait_timed(CassFuture* future, 4883 cass_duration_t timeout_us); 4884 4885 /** 4886 * Gets the result of a successful future. If the future is not ready this method will 4887 * wait for the future to be set. 4888 * 4889 * @public @memberof CassFuture 4890 * 4891 * @param[in] future 4892 * @return CassResult instance if successful, otherwise NULL for error. The return instance 4893 * must be freed using cass_result_free(). 4894 * 4895 * @see cass_session_execute() and cass_session_execute_batch() 4896 */ 4897 CASS_EXPORT const CassResult* 4898 cass_future_get_result(CassFuture* future); 4899 4900 /** 4901 * Gets the error result from a future that failed as a result of a server error. If the 4902 * future is not ready this method will wait for the future to be set. 4903 * 4904 * @public @memberof CassFuture 4905 * 4906 * @param[in] future 4907 * @return CassErrorResult instance if the request failed with a server error, 4908 * otherwise NULL if the request was successful or the failure was not caused by 4909 * a server error. The return instance must be freed using cass_error_result_free(). 4910 * 4911 * @see cass_session_execute() and cass_session_execute_batch() 4912 */ 4913 CASS_EXPORT const CassErrorResult* 4914 cass_future_get_error_result(CassFuture* future); 4915 4916 /** 4917 * Gets the result of a successful future. If the future is not ready this method will 4918 * wait for the future to be set. The first successful call consumes the future, all 4919 * subsequent calls will return NULL. 4920 * 4921 * @public @memberof CassFuture 4922 * 4923 * @param[in] future 4924 * @return CassPrepared instance if successful, otherwise NULL for error. The return instance 4925 * must be freed using cass_prepared_free(). 4926 * 4927 * @see cass_session_prepare() 4928 */ 4929 CASS_EXPORT const CassPrepared* 4930 cass_future_get_prepared(CassFuture* future); 4931 4932 /** 4933 * Gets the error code from future. If the future is not ready this method will 4934 * wait for the future to be set. 4935 * 4936 * @public @memberof CassFuture 4937 * 4938 * @param[in] future 4939 * @return CASS_OK if successful, otherwise an error occurred. 4940 * 4941 * @see cass_error_desc() 4942 */ 4943 CASS_EXPORT CassError 4944 cass_future_error_code(CassFuture* future); 4945 4946 /** 4947 * Gets the error message from future. If the future is not ready this method will 4948 * wait for the future to be set. 4949 * 4950 * @public @memberof CassFuture 4951 * 4952 * @param[in] future 4953 * @param[out] message Empty string returned if successful, otherwise 4954 * a message describing the error is returned. 4955 * @param[out] message_length 4956 */ 4957 CASS_EXPORT void 4958 cass_future_error_message(CassFuture* future, 4959 const char** message, 4960 size_t* message_length); 4961 4962 /** 4963 * Gets the tracing ID associated with the request. 4964 * 4965 * @public @memberof CassFuture 4966 * 4967 * @param[in] future 4968 * @param[out] tracing_id 4969 * @return CASS_OK if successful, otherwise an error occurred. 4970 */ 4971 CASS_EXPORT CassError 4972 cass_future_tracing_id(CassFuture* future, 4973 CassUuid* tracing_id); 4974 4975 /** 4976 * Gets a the number of custom payload items from a response future. If the future is not 4977 * ready this method will wait for the future to be set. 4978 * 4979 * @cassandra{2.2+} 4980 * 4981 * @public @memberof CassFuture 4982 * 4983 * @param[in] future 4984 * @return the number of custom payload items. 4985 */ 4986 CASS_EXPORT size_t 4987 cass_future_custom_payload_item_count(CassFuture* future); 4988 4989 /** 4990 * Gets a custom payload item from a response future at the specified index. If the future is not 4991 * ready this method will wait for the future to be set. 4992 * 4993 * @cassandra{2.2+} 4994 * 4995 * @public @memberof CassFuture 4996 * 4997 * @param[in] future 4998 * @param[in] index 4999 * @param[out] name 5000 * @param[out] name_length 5001 * @param[out] value 5002 * @param[out] value_size 5003 * @return CASS_OK if successful, otherwise an error occurred. 5004 */ 5005 CASS_EXPORT CassError 5006 cass_future_custom_payload_item(CassFuture* future, 5007 size_t index, 5008 const char** name, 5009 size_t* name_length, 5010 const cass_byte_t** value, 5011 size_t* value_size); 5012 5013 /** 5014 * Gets the node that acted as coordinator for this query. If the future is not 5015 * ready this method will wait for the future to be set. 5016 * 5017 * @public @memberof CassFuture 5018 * 5019 * @param future 5020 * @return The coordinator node that handled the query. The lifetime of this 5021 * object is the same as the result object it came from. NULL can be returned 5022 * if the future is not a response future or if an error occurs before a 5023 * coordinator responds. 5024 * 5025 * @see cass_statement_set_node() 5026 */ 5027 CASS_EXPORT const CassNode* 5028 cass_future_coordinator(CassFuture* future); 5029 5030 /*********************************************************************************** 5031 * 5032 * Statement 5033 * 5034 ***********************************************************************************/ 5035 5036 /** 5037 * Creates a new query statement. 5038 * 5039 * @public @memberof CassStatement 5040 * 5041 * @param[in] query The query is copied into the statement object; the 5042 * memory pointed to by this parameter can be freed after this call. 5043 * @param[in] parameter_count The number of bound parameters. 5044 * @return Returns a statement that must be freed. 5045 * 5046 * @see cass_statement_free() 5047 */ 5048 CASS_EXPORT CassStatement* 5049 cass_statement_new(const char* query, 5050 size_t parameter_count); 5051 5052 /** 5053 * Same as cass_statement_new(), but with lengths for string 5054 * parameters. 5055 * 5056 * @public @memberof CassStatement 5057 * 5058 * @param[in] query 5059 * @param[in] query_length 5060 * @param[in] parameter_count 5061 * @return same as cass_statement_new() 5062 * 5063 * @see cass_statement_new() 5064 */ 5065 CASS_EXPORT CassStatement* 5066 cass_statement_new_n(const char* query, 5067 size_t query_length, 5068 size_t parameter_count); 5069 5070 /** 5071 * Clear and/or resize the statement's parameters. 5072 * 5073 * @public @memberof CassStatement 5074 * 5075 * @param[in] statement 5076 * @param[in] count 5077 * @return CASS_OK if successful, otherwise an error occurred. 5078 */ 5079 CASS_EXPORT CassError 5080 cass_statement_reset_parameters(CassStatement* statement, 5081 size_t count); 5082 5083 /** 5084 * Frees a statement instance. Statements can be immediately freed after 5085 * being prepared, executed or added to a batch. 5086 * 5087 * @public @memberof CassStatement 5088 * 5089 * @param[in] statement 5090 */ 5091 CASS_EXPORT void 5092 cass_statement_free(CassStatement* statement); 5093 5094 /** 5095 * Adds a key index specifier to this a statement. 5096 * When using token-aware routing, this can be used to tell the driver which 5097 * parameters within a non-prepared, parameterized statement are part of 5098 * the partition key. 5099 * 5100 * Use consecutive calls for composite partition keys. 5101 * 5102 * This is not necessary for prepared statements, as the key 5103 * parameters are determined in the metadata processed in the prepare phase. 5104 * 5105 * @public @memberof CassStatement 5106 * 5107 * @param[in] statement 5108 * @param[in] index 5109 * @return CASS_OK if successful, otherwise an error occurred. 5110 */ 5111 CASS_EXPORT CassError 5112 cass_statement_add_key_index(CassStatement* statement, 5113 size_t index); 5114 5115 /** 5116 * Sets the statement's keyspace. This is used for token-aware routing and when 5117 * using protocol v5 or greater it also overrides the session's current 5118 * keyspace for the statement. 5119 * 5120 * This is not necessary and will not work for bound statements, as the keyspace 5121 * is determined by the prepared statement metadata. 5122 * 5123 * @public @memberof CassStatement 5124 * 5125 * @param[in] statement 5126 * @param[in] keyspace 5127 * @return CASS_OK if successful, otherwise an error occurred. 5128 */ 5129 CASS_EXPORT CassError 5130 cass_statement_set_keyspace(CassStatement* statement, 5131 const char* keyspace); 5132 5133 /** 5134 * Same as cass_statement_set_keyspace(), but with lengths for string 5135 * parameters. 5136 * 5137 * @public @memberof CassStatement 5138 * 5139 * @param[in] statement 5140 * @param[in] keyspace 5141 * @param[in] keyspace_length 5142 * @return same as cass_statement_set_keyspace() 5143 * 5144 * @see cass_statement_set_keyspace() 5145 */ 5146 CASS_EXPORT CassError 5147 cass_statement_set_keyspace_n(CassStatement* statement, 5148 const char* keyspace, 5149 size_t keyspace_length); 5150 5151 /** 5152 * Sets the statement's consistency level. 5153 * 5154 * <b>Default:</b> CASS_CONSISTENCY_LOCAL_ONE 5155 * 5156 * @public @memberof CassStatement 5157 * 5158 * @param[in] statement 5159 * @param[in] consistency 5160 * @return CASS_OK if successful, otherwise an error occurred. 5161 */ 5162 CASS_EXPORT CassError 5163 cass_statement_set_consistency(CassStatement* statement, 5164 CassConsistency consistency); 5165 5166 /** 5167 * Sets the statement's serial consistency level. 5168 * 5169 * @cassandra{2.0+} 5170 * 5171 * <b>Default:</b> Not set 5172 * 5173 * @public @memberof CassStatement 5174 * 5175 * @param[in] statement 5176 * @param[in] serial_consistency 5177 * @return CASS_OK if successful, otherwise an error occurred. 5178 */ 5179 CASS_EXPORT CassError 5180 cass_statement_set_serial_consistency(CassStatement* statement, 5181 CassConsistency serial_consistency); 5182 5183 /** 5184 * Sets the statement's page size. 5185 * 5186 * @cassandra{2.0+} 5187 * 5188 * <b>Default:</b> -1 (Disabled) 5189 * 5190 * @public @memberof CassStatement 5191 * 5192 * @param[in] statement 5193 * @param[in] page_size 5194 * @return CASS_OK if successful, otherwise an error occurred. 5195 */ 5196 CASS_EXPORT CassError 5197 cass_statement_set_paging_size(CassStatement* statement, 5198 int page_size); 5199 5200 /** 5201 * Sets the statement's paging state. This can be used to get the next page of 5202 * data in a multi-page query. 5203 * 5204 * @cassandra{2.0+} 5205 * 5206 * @public @memberof CassStatement 5207 * 5208 * @param[in] statement 5209 * @param[in] result 5210 * @return CASS_OK if successful, otherwise an error occurred. 5211 */ 5212 CASS_EXPORT CassError 5213 cass_statement_set_paging_state(CassStatement* statement, 5214 const CassResult* result); 5215 5216 /** 5217 * Sets the statement's paging state. This can be used to get the next page of 5218 * data in a multi-page query. 5219 * 5220 * @cassandra{2.0+} 5221 * 5222 * <b>Warning:</b> The paging state should not be exposed to or come from 5223 * untrusted environments. The paging state could be spoofed and potentially 5224 * used to gain access to other data. 5225 * 5226 * @public @memberof CassStatement 5227 * 5228 * @param[in] statement 5229 * @param[in] paging_state 5230 * @param[in] paging_state_size 5231 * @return CASS_OK if successful, otherwise an error occurred. 5232 * 5233 * @see cass_result_paging_state_token() 5234 */ 5235 CASS_EXPORT CassError 5236 cass_statement_set_paging_state_token(CassStatement* statement, 5237 const char* paging_state, 5238 size_t paging_state_size); 5239 5240 /** 5241 * Sets the statement's timestamp. 5242 * 5243 * @cassandra{2.1+} 5244 * 5245 * @public @memberof CassStatement 5246 * 5247 * @param[in] statement 5248 * @param[in] timestamp 5249 * @return CASS_OK if successful, otherwise an error occurred. 5250 */ 5251 CASS_EXPORT CassError 5252 cass_statement_set_timestamp(CassStatement* statement, 5253 cass_int64_t timestamp); 5254 5255 /** 5256 * Sets the statement's timeout for waiting for a response from a node. 5257 * 5258 * <b>Default:</b> Disabled (use the cluster-level request timeout) 5259 * 5260 * @public @memberof CassStatement 5261 * 5262 * @param[in] statement 5263 * @param[in] timeout_ms Request timeout in milliseconds. Use 0 for no timeout 5264 * or CASS_UINT64_MAX to disable (to use the cluster-level request timeout). 5265 * @return CASS_OK if successful, otherwise an error occurred. 5266 * 5267 * @see cass_cluster_set_request_timeout() 5268 */ 5269 CASS_EXPORT CassError 5270 cass_statement_set_request_timeout(CassStatement* statement, 5271 cass_uint64_t timeout_ms); 5272 5273 /** 5274 * Sets whether the statement is idempotent. Idempotent statements are able to be 5275 * automatically retried after timeouts/errors and can be speculatively executed. 5276 * 5277 * @public @memberof CassStatement 5278 * 5279 * @param[in] statement 5280 * @param[in] is_idempotent 5281 * @return CASS_OK if successful, otherwise an error occurred. 5282 * 5283 * @see cass_cluster_set_constant_speculative_execution_policy() 5284 * @see cass_execution_profile_set_constant_speculative_execution_policy() 5285 */ 5286 CASS_EXPORT CassError 5287 cass_statement_set_is_idempotent(CassStatement* statement, 5288 cass_bool_t is_idempotent); 5289 5290 /** 5291 * Sets the statement's retry policy. 5292 * 5293 * @public @memberof CassStatement 5294 * 5295 * @param[in] statement 5296 * @param[in] retry_policy 5297 * @return CASS_OK if successful, otherwise an error occurred. 5298 */ 5299 CASS_EXPORT CassError 5300 cass_statement_set_retry_policy(CassStatement* statement, 5301 CassRetryPolicy* retry_policy); 5302 5303 /** 5304 * Sets the statement's custom payload. 5305 * 5306 * @cassandra{2.2+} 5307 * 5308 * @public @memberof CassStatement 5309 * 5310 * @param[in] statement 5311 * @param[in] payload 5312 * @return CASS_OK if successful, otherwise an error occurred. 5313 */ 5314 CASS_EXPORT CassError 5315 cass_statement_set_custom_payload(CassStatement* statement, 5316 const CassCustomPayload* payload); 5317 5318 /** 5319 * Sets the execution profile to execute the statement with. 5320 * 5321 * <b>Note:</b> NULL or empty string will clear execution profile from statement 5322 * 5323 * @public @memberof CassStatement 5324 * 5325 * @param[in] statement 5326 * @param[in] name 5327 * @return CASS_OK if successful, otherwise an error occurred. 5328 * 5329 * @see cass_cluster_set_execution_profile() 5330 */ 5331 CASS_EXPORT CassError 5332 cass_statement_set_execution_profile(CassStatement* statement, 5333 const char* name); 5334 5335 /** 5336 * Same as cass_statement_set_execution_profile(), but with lengths for string 5337 * parameters. 5338 * 5339 * @public @memberof CassStatement 5340 * 5341 * @param[in] statement 5342 * @param[in] name 5343 * @param[in] name_length 5344 * @return CASS_OK if successful, otherwise an error occurred. 5345 * 5346 * @see cass_statement_set_execution_profile() 5347 */ 5348 CASS_EXPORT CassError 5349 cass_statement_set_execution_profile_n(CassStatement* statement, 5350 const char* name, 5351 size_t name_length); 5352 5353 /** 5354 * Sets whether the statement should use tracing. 5355 * 5356 * @cassandra{2.2+} 5357 * 5358 * @public @memberof CassStatement 5359 * 5360 * @param[in] statement 5361 * @param[in] enabled 5362 * @return CASS_OK if successful, otherwise an error occurred. 5363 */ 5364 CASS_EXPORT CassError 5365 cass_statement_set_tracing(CassStatement* statement, 5366 cass_bool_t enabled); 5367 5368 /** 5369 * Sets a specific host that should run the query. 5370 * 5371 * In general, this should not be used, but it can be useful in the following 5372 * situations: 5373 * * To query node-local tables such as system and virtual tables. 5374 * * To apply a sequence of schema changes where it makes sense for all the 5375 * changes to be applied on a single node. 5376 * 5377 * @public @memberof CassStatement 5378 * 5379 * @param[in] statement 5380 * @param[in] host 5381 * @param[in] port 5382 * @return CASS_OK if successful, otherwise an error occurred. 5383 */ 5384 CASS_EXPORT CassError 5385 cass_statement_set_host(CassStatement* statement, 5386 const char* host, 5387 int port); 5388 5389 /** 5390 * Same as cass_statement_set_host(), but with lengths for string 5391 * parameters. 5392 * 5393 * @public @memberof CassStatement 5394 * 5395 * @param[in] statement 5396 * @param[in] host 5397 * @param[in] host_length 5398 * @param[in] port 5399 * @return CASS_OK if successful, otherwise an error occurred. 5400 */ 5401 CASS_EXPORT CassError 5402 cass_statement_set_host_n(CassStatement* statement, 5403 const char* host, 5404 size_t host_length, 5405 int port); 5406 5407 /** 5408 * Same as cass_statement_set_host(), but with the `CassInet` type 5409 * for the host instead of a string. 5410 * 5411 * @public @memberof CassStatement 5412 * 5413 * @param[in] statement 5414 * @param[in] host 5415 * @param[in] port 5416 * @return CASS_OK if successful, otherwise an error occurred. 5417 */ 5418 CASS_EXPORT CassError 5419 cass_statement_set_host_inet(CassStatement* statement, 5420 const CassInet* host, 5421 int port); 5422 5423 /** 5424 * Same as cass_statement_set_host(), but using the `CassNode` type. This can 5425 * be used to re-query the same coordinator when used with the result of 5426 * `cass_future_coordinator()` 5427 * 5428 * @public @memberof CassStatement 5429 * 5430 * @param statement 5431 * @param address 5432 * @return CASS_OK if successful, otherwise an error occurred. 5433 * 5434 * @see cass_future_coordinator() 5435 */ 5436 CASS_EXPORT CassError 5437 cass_statement_set_node(CassStatement* statement, 5438 const CassNode* node); 5439 5440 /** 5441 * Binds null to a query or bound statement at the specified index. 5442 * 5443 * @public @memberof CassStatement 5444 * 5445 * @param[in] statement 5446 * @param[in] index 5447 * @return CASS_OK if successful, otherwise an error occurred. 5448 */ 5449 CASS_EXPORT CassError 5450 cass_statement_bind_null(CassStatement* statement, 5451 size_t index); 5452 5453 /** 5454 * Binds a null to all the values with the specified name. 5455 * 5456 * This can only be used with statements created by 5457 * cass_prepared_bind() when using Cassandra 2.0 or earlier. 5458 * 5459 * @public @memberof CassStatement 5460 * 5461 * @param[in] statement 5462 * @param[in] name 5463 * @return CASS_OK if successful, otherwise an error occurred. 5464 */ 5465 CASS_EXPORT CassError 5466 cass_statement_bind_null_by_name(CassStatement* statement, 5467 const char* name); 5468 5469 /** 5470 * Same as cass_statement_bind_null_by_name(), but with lengths for string 5471 * parameters. 5472 * 5473 * @public @memberof CassStatement 5474 * 5475 * @param[in] statement 5476 * @param[in] name 5477 * @param[in] name_length 5478 * @return same as cass_statement_bind_null_by_name() 5479 * 5480 * @see cass_statement_bind_null_by_name() 5481 */ 5482 CASS_EXPORT CassError 5483 cass_statement_bind_null_by_name_n(CassStatement* statement, 5484 const char* name, 5485 size_t name_length); 5486 5487 /** 5488 * Binds a "tinyint" to a query or bound statement at the specified index. 5489 * 5490 * @cassandra{2.2+} 5491 * 5492 * @public @memberof CassStatement 5493 * 5494 * @param[in] statement 5495 * @param[in] index 5496 * @param[in] value 5497 * @return CASS_OK if successful, otherwise an error occurred. 5498 */ 5499 CASS_EXPORT CassError 5500 cass_statement_bind_int8(CassStatement* statement, 5501 size_t index, 5502 cass_int8_t value); 5503 5504 /** 5505 * Binds a "tinyint" to all the values with the specified name. 5506 * 5507 * @cassandra{2.2+} 5508 * 5509 * @public @memberof CassStatement 5510 * 5511 * @param[in] statement 5512 * @param[in] name 5513 * @param[in] value 5514 * @return CASS_OK if successful, otherwise an error occurred. 5515 */ 5516 CASS_EXPORT CassError 5517 cass_statement_bind_int8_by_name(CassStatement* statement, 5518 const char* name, 5519 cass_int8_t value); 5520 5521 /** 5522 * Same as cass_statement_bind_int8_by_name(), but with lengths for string 5523 * parameters. 5524 * 5525 * @cassandra{2.2+} 5526 * 5527 * @public @memberof CassStatement 5528 * 5529 * @param[in] statement 5530 * @param[in] name 5531 * @param[in] name_length 5532 * @param[in] value 5533 * @return same as cass_statement_bind_int8_by_name() 5534 * 5535 * @see cass_statement_bind_int8_by_name() 5536 */ 5537 CASS_EXPORT CassError 5538 cass_statement_bind_int8_by_name_n(CassStatement* statement, 5539 const char* name, 5540 size_t name_length, 5541 cass_int8_t value); 5542 5543 /** 5544 * Binds an "smallint" to a query or bound statement at the specified index. 5545 * 5546 * @cassandra{2.2+} 5547 * 5548 * @public @memberof CassStatement 5549 * 5550 * @param[in] statement 5551 * @param[in] index 5552 * @param[in] value 5553 * @return CASS_OK if successful, otherwise an error occurred. 5554 */ 5555 CASS_EXPORT CassError 5556 cass_statement_bind_int16(CassStatement* statement, 5557 size_t index, 5558 cass_int16_t value); 5559 5560 /** 5561 * Binds an "smallint" to all the values with the specified name. 5562 * 5563 * @cassandra{2.2+} 5564 * 5565 * @public @memberof CassStatement 5566 * 5567 * @param[in] statement 5568 * @param[in] name 5569 * @param[in] value 5570 * @return CASS_OK if successful, otherwise an error occurred. 5571 */ 5572 CASS_EXPORT CassError 5573 cass_statement_bind_int16_by_name(CassStatement* statement, 5574 const char* name, 5575 cass_int16_t value); 5576 5577 /** 5578 * Same as cass_statement_bind_int16_by_name(), but with lengths for string 5579 * parameters. 5580 * 5581 * @cassandra{2.2+} 5582 * 5583 * @public @memberof CassStatement 5584 * 5585 * @param[in] statement 5586 * @param[in] name 5587 * @param[in] name_length 5588 * @param[in] value 5589 * @return same as cass_statement_bind_int16_by_name() 5590 * 5591 * @see cass_statement_bind_int16_by_name() 5592 */ 5593 CASS_EXPORT CassError 5594 cass_statement_bind_int16_by_name_n(CassStatement* statement, 5595 const char* name, 5596 size_t name_length, 5597 cass_int16_t value); 5598 5599 /** 5600 * Binds an "int" to a query or bound statement at the specified index. 5601 * 5602 * @public @memberof CassStatement 5603 * 5604 * @param[in] statement 5605 * @param[in] index 5606 * @param[in] value 5607 * @return CASS_OK if successful, otherwise an error occurred. 5608 */ 5609 CASS_EXPORT CassError 5610 cass_statement_bind_int32(CassStatement* statement, 5611 size_t index, 5612 cass_int32_t value); 5613 5614 /** 5615 * Binds an "int" to all the values with the specified name. 5616 * 5617 * This can only be used with statements created by 5618 * cass_prepared_bind() when using Cassandra 2.0 or earlier. 5619 * 5620 * @public @memberof CassStatement 5621 * 5622 * @param[in] statement 5623 * @param[in] name 5624 * @param[in] value 5625 * @return CASS_OK if successful, otherwise an error occurred. 5626 */ 5627 CASS_EXPORT CassError 5628 cass_statement_bind_int32_by_name(CassStatement* statement, 5629 const char* name, 5630 cass_int32_t value); 5631 5632 /** 5633 * Same as cass_statement_bind_int32_by_name(), but with lengths for string 5634 * parameters. 5635 * 5636 * @public @memberof CassStatement 5637 * 5638 * @param[in] statement 5639 * @param[in] name 5640 * @param[in] name_length 5641 * @param[in] value 5642 * @return same as cass_statement_bind_int32_by_name() 5643 * 5644 * @see cass_statement_bind_int32_by_name() 5645 */ 5646 CASS_EXPORT CassError 5647 cass_statement_bind_int32_by_name_n(CassStatement* statement, 5648 const char* name, 5649 size_t name_length, 5650 cass_int32_t value); 5651 5652 /** 5653 * Binds a "date" to a query or bound statement at the specified index. 5654 * 5655 * @cassandra{2.2+} 5656 * 5657 * @public @memberof CassStatement 5658 * 5659 * @param[in] statement 5660 * @param[in] index 5661 * @param[in] value 5662 * @return CASS_OK if successful, otherwise an error occurred. 5663 */ 5664 CASS_EXPORT CassError 5665 cass_statement_bind_uint32(CassStatement* statement, 5666 size_t index, 5667 cass_uint32_t value); 5668 5669 /** 5670 * Binds a "date" to all the values with the specified name. 5671 * 5672 * @cassandra{2.2+} 5673 * 5674 * @public @memberof CassStatement 5675 * 5676 * @param[in] statement 5677 * @param[in] name 5678 * @param[in] value 5679 * @return CASS_OK if successful, otherwise an error occurred. 5680 */ 5681 CASS_EXPORT CassError 5682 cass_statement_bind_uint32_by_name(CassStatement* statement, 5683 const char* name, 5684 cass_uint32_t value); 5685 5686 /** 5687 * Same as cass_statement_bind_uint32_by_name(), but with lengths for string 5688 * parameters. 5689 * 5690 * @cassandra{2.2+} 5691 * 5692 * @public @memberof CassStatement 5693 * 5694 * @param[in] statement 5695 * @param[in] name 5696 * @param[in] name_length 5697 * @param[in] value 5698 * @return same as cass_statement_bind_uint32_by_name() 5699 * 5700 * @see cass_statement_bind_uint32_by_name() 5701 */ 5702 CASS_EXPORT CassError 5703 cass_statement_bind_uint32_by_name_n(CassStatement* statement, 5704 const char* name, 5705 size_t name_length, 5706 cass_uint32_t value); 5707 5708 /** 5709 * Binds a "bigint", "counter", "timestamp" or "time" to a query or 5710 * bound statement at the specified index. 5711 * 5712 * @public @memberof CassStatement 5713 * 5714 * @param[in] statement 5715 * @param[in] index 5716 * @param[in] value 5717 * @return CASS_OK if successful, otherwise an error occurred. 5718 */ 5719 CASS_EXPORT CassError 5720 cass_statement_bind_int64(CassStatement* statement, 5721 size_t index, 5722 cass_int64_t value); 5723 5724 /** 5725 * Binds a "bigint", "counter", "timestamp" or "time" to all values 5726 * with the specified name. 5727 * 5728 * This can only be used with statements created by 5729 * cass_prepared_bind() when using Cassandra 2.0 or earlier. 5730 * 5731 * @public @memberof CassStatement 5732 * 5733 * @param[in] statement 5734 * @param[in] name 5735 * @param[in] value 5736 * @return CASS_OK if successful, otherwise an error occurred. 5737 */ 5738 CASS_EXPORT CassError 5739 cass_statement_bind_int64_by_name(CassStatement* statement, 5740 const char* name, 5741 cass_int64_t value); 5742 5743 /** 5744 * Same as cass_statement_bind_int64_by_name(), but with lengths for string 5745 * parameters. 5746 * 5747 * @public @memberof CassStatement 5748 * 5749 * @param[in] statement 5750 * @param[in] name 5751 * @param[in] name_length 5752 * @param[in] value 5753 * @return same as cass_statement_bind_int64_by_name(0 5754 * 5755 * @see cass_statement_bind_int64_by_name() 5756 */ 5757 CASS_EXPORT CassError 5758 cass_statement_bind_int64_by_name_n(CassStatement* statement, 5759 const char* name, 5760 size_t name_length, 5761 cass_int64_t value); 5762 5763 /** 5764 * Binds a "float" to a query or bound statement at the specified index. 5765 * 5766 * @public @memberof CassStatement 5767 * 5768 * @param[in] statement 5769 * @param[in] index 5770 * @param[in] value 5771 * @return CASS_OK if successful, otherwise an error occurred. 5772 */ 5773 CASS_EXPORT CassError 5774 cass_statement_bind_float(CassStatement* statement, 5775 size_t index, 5776 cass_float_t value); 5777 5778 /** 5779 * Binds a "float" to all the values with the specified name. 5780 * 5781 * This can only be used with statements created by 5782 * cass_prepared_bind() when using Cassandra 2.0 or earlier. 5783 * 5784 * @public @memberof CassStatement 5785 * 5786 * @param[in] statement 5787 * @param[in] name 5788 * @param[in] value 5789 * @return CASS_OK if successful, otherwise an error occurred. 5790 */ 5791 CASS_EXPORT CassError 5792 cass_statement_bind_float_by_name(CassStatement* statement, 5793 const char* name, 5794 cass_float_t value); 5795 5796 /** 5797 * Same as cass_statement_bind_float_by_name(), but with lengths for string 5798 * parameters. 5799 * 5800 * @public @memberof CassStatement 5801 * 5802 * @param[in] statement 5803 * @param[in] name 5804 * @param[in] name_length 5805 * @param[in] value 5806 * @return same as cass_statement_bind_float_by_name() 5807 * 5808 * @see cass_statement_bind_float_by_name() 5809 */ 5810 CASS_EXPORT CassError 5811 cass_statement_bind_float_by_name_n(CassStatement* statement, 5812 const char* name, 5813 size_t name_length, 5814 cass_float_t value); 5815 5816 /** 5817 * Binds a "double" to a query or bound statement at the specified index. 5818 * 5819 * @public @memberof CassStatement 5820 * 5821 * @param[in] statement 5822 * @param[in] index 5823 * @param[in] value 5824 * @return CASS_OK if successful, otherwise an error occurred. 5825 */ 5826 CASS_EXPORT CassError 5827 cass_statement_bind_double(CassStatement* statement, 5828 size_t index, 5829 cass_double_t value); 5830 5831 /** 5832 * Binds a "double" to all the values with the specified name. 5833 * 5834 * This can only be used with statements created by 5835 * cass_prepared_bind() when using Cassandra 2.0 or earlier. 5836 * 5837 * @public @memberof CassStatement 5838 * 5839 * @param[in] statement 5840 * @param[in] name 5841 * @param[in] value 5842 * @return CASS_OK if successful, otherwise an error occurred. 5843 */ 5844 CASS_EXPORT CassError 5845 cass_statement_bind_double_by_name(CassStatement* statement, 5846 const char* name, 5847 cass_double_t value); 5848 5849 /** 5850 * Same as cass_statement_bind_double_by_name(), but with lengths for string 5851 * parameters. 5852 * 5853 * @public @memberof CassStatement 5854 * 5855 * @param[in] statement 5856 * @param[in] name 5857 * @param[in] name_length 5858 * @param[in] value 5859 * @return same as cass_statement_bind_double_by_name() 5860 * 5861 * @see cass_statement_bind_double_by_name() 5862 */ 5863 CASS_EXPORT CassError 5864 cass_statement_bind_double_by_name_n(CassStatement* statement, 5865 const char* name, 5866 size_t name_length, 5867 cass_double_t value); 5868 5869 /** 5870 * Binds a "boolean" to a query or bound statement at the specified index. 5871 * 5872 * @public @memberof CassStatement 5873 * 5874 * @param[in] statement 5875 * @param[in] index 5876 * @param[in] value 5877 * @return CASS_OK if successful, otherwise an error occurred. 5878 */ 5879 CASS_EXPORT CassError 5880 cass_statement_bind_bool(CassStatement* statement, 5881 size_t index, 5882 cass_bool_t value); 5883 5884 /** 5885 * Binds a "boolean" to all the values with the specified name. 5886 * 5887 * This can only be used with statements created by 5888 * cass_prepared_bind() when using Cassandra 2.0 or earlier. 5889 * 5890 * @public @memberof CassStatement 5891 * 5892 * @param[in] statement 5893 * @param[in] name 5894 * @param[in] value 5895 * @return CASS_OK if successful, otherwise an error occurred. 5896 */ 5897 CASS_EXPORT CassError 5898 cass_statement_bind_bool_by_name(CassStatement* statement, 5899 const char* name, 5900 cass_bool_t value); 5901 5902 /** 5903 * Same as cass_statement_bind_bool_by_name(), but with lengths for string 5904 * parameters. 5905 * 5906 * @public @memberof CassStatement 5907 * 5908 * @param[in] statement 5909 * @param[in] name 5910 * @param[in] name_length 5911 * @param[in] value 5912 * @return same as cass_statement_bind_bool_by_name() 5913 * 5914 * @see cass_statement_bind_bool_by_name() 5915 */ 5916 CASS_EXPORT CassError 5917 cass_statement_bind_bool_by_name_n(CassStatement* statement, 5918 const char* name, 5919 size_t name_length, 5920 cass_bool_t value); 5921 5922 /** 5923 * Binds an "ascii", "text" or "varchar" to a query or bound statement 5924 * at the specified index. 5925 * 5926 * @public @memberof CassStatement 5927 * 5928 * @param[in] statement 5929 * @param[in] index 5930 * @param[in] value The value is copied into the statement object; the 5931 * memory pointed to by this parameter can be freed after this call. 5932 * @return CASS_OK if successful, otherwise an error occurred. 5933 */ 5934 CASS_EXPORT CassError 5935 cass_statement_bind_string(CassStatement* statement, 5936 size_t index, 5937 const char* value); 5938 5939 /** 5940 * Same as cass_statement_bind_string(), but with lengths for string 5941 * parameters. 5942 * 5943 * @public @memberof CassStatement 5944 * 5945 * @param[in] statement 5946 * @param[in] index 5947 * @param[in] value 5948 * @param[in] value_length 5949 * @return same as cass_statement_bind_string() 5950 * 5951 * @see cass_statement_bind_string() 5952 */ 5953 CASS_EXPORT CassError 5954 cass_statement_bind_string_n(CassStatement* statement, 5955 size_t index, 5956 const char* value, 5957 size_t value_length); 5958 5959 /** 5960 * Binds an "ascii", "text" or "varchar" to all the values 5961 * with the specified name. 5962 * 5963 * This can only be used with statements created by 5964 * cass_prepared_bind() when using Cassandra 2.0 or earlier. 5965 * 5966 * @public @memberof CassStatement 5967 * 5968 * @param[in] statement 5969 * @param[in] name 5970 * @param[in] value The value is copied into the statement object; the 5971 * memory pointed to by this parameter can be freed after this call. 5972 * @return CASS_OK if successful, otherwise an error occurred. 5973 */ 5974 CASS_EXPORT CassError 5975 cass_statement_bind_string_by_name(CassStatement* statement, 5976 const char* name, 5977 const char* value); 5978 5979 /** 5980 * Same as cass_statement_bind_string_by_name(), but with lengths for string 5981 * parameters. 5982 * 5983 * @public @memberof CassStatement 5984 * 5985 * @param[in] statement 5986 * @param[in] name 5987 * @param[in] name_length 5988 * @param[in] value 5989 * @param[in] value_length 5990 * @return same as cass_statement_bind_string_by_name() 5991 * 5992 * @see cass_statement_bind_string_by_name() 5993 */ 5994 CASS_EXPORT CassError 5995 cass_statement_bind_string_by_name_n(CassStatement* statement, 5996 const char* name, 5997 size_t name_length, 5998 const char* value, 5999 size_t value_length); 6000 6001 /** 6002 * Binds a "blob", "varint" or "custom" to a query or bound statement at the specified index. 6003 * 6004 * @public @memberof CassStatement 6005 * 6006 * @param[in] statement 6007 * @param[in] index 6008 * @param[in] value The value is copied into the statement object; the 6009 * memory pointed to by this parameter can be freed after this call. 6010 * @param[in] value_size 6011 * @return CASS_OK if successful, otherwise an error occurred. 6012 */ 6013 CASS_EXPORT CassError 6014 cass_statement_bind_bytes(CassStatement* statement, 6015 size_t index, 6016 const cass_byte_t* value, 6017 size_t value_size); 6018 6019 /** 6020 * Binds a "blob", "varint" or "custom" to all the values with the 6021 * specified name. 6022 * 6023 * This can only be used with statements created by 6024 * cass_prepared_bind() when using Cassandra 2.0 or earlier. 6025 * 6026 * @public @memberof CassStatement 6027 * 6028 * @param[in] statement 6029 * @param[in] name 6030 * @param[in] value The value is copied into the statement object; the 6031 * memory pointed to by this parameter can be freed after this call. 6032 * @param[in] value_size 6033 * @return CASS_OK if successful, otherwise an error occurred. 6034 */ 6035 CASS_EXPORT CassError 6036 cass_statement_bind_bytes_by_name(CassStatement* statement, 6037 const char* name, 6038 const cass_byte_t* value, 6039 size_t value_size); 6040 6041 /** 6042 * Same as cass_statement_bind_bytes_by_name(), but with lengths for string 6043 * parameters. 6044 * 6045 * @public @memberof CassStatement 6046 * 6047 * @param[in] statement 6048 * @param[in] name 6049 * @param[in] name_length 6050 * @param[in] value 6051 * @param[in] value_size 6052 * @return same as cass_statement_bind_bytes_by_name() 6053 * 6054 * @see cass_statement_bind_bytes_by_name() 6055 */ 6056 CASS_EXPORT CassError 6057 cass_statement_bind_bytes_by_name_n(CassStatement* statement, 6058 const char* name, 6059 size_t name_length, 6060 const cass_byte_t* value, 6061 size_t value_size); 6062 6063 /** 6064 * Binds a "custom" to a query or bound statement at the specified index. 6065 * 6066 * @public @memberof CassStatement 6067 * 6068 * @param[in] statement 6069 * @param[in] index 6070 * @param[in] class_name 6071 * @param[in] value The value is copied into the statement object; the 6072 * memory pointed to by this parameter can be freed after this call. 6073 * @param[in] value_size 6074 * @return CASS_OK if successful, otherwise an error occurred. 6075 */ 6076 CASS_EXPORT CassError 6077 cass_statement_bind_custom(CassStatement* statement, 6078 size_t index, 6079 const char* class_name, 6080 const cass_byte_t* value, 6081 size_t value_size); 6082 /** 6083 * Same as cass_statement_bind_custom(), but with lengths for string 6084 * parameters. 6085 * 6086 * @public @memberof CassStatement 6087 * 6088 * @param[in] statement 6089 * @param[in] index 6090 * @param[in] class_name 6091 * @param[in] class_name_length 6092 * @param[in] value The value is copied into the statement object; the 6093 * memory pointed to by this parameter can be freed after this call. 6094 * @param[in] value_size 6095 * @return CASS_OK if successful, otherwise an error occurred. 6096 */ 6097 CASS_EXPORT CassError 6098 cass_statement_bind_custom_n(CassStatement* statement, 6099 size_t index, 6100 const char* class_name, 6101 size_t class_name_length, 6102 const cass_byte_t* value, 6103 size_t value_size); 6104 6105 /** 6106 * Binds a "custom" to all the values with the specified name. 6107 * 6108 * This can only be used with statements created by 6109 * cass_prepared_bind() when using Cassandra 2.0 or earlier. 6110 * 6111 * @public @memberof CassStatement 6112 * 6113 * @param[in] statement 6114 * @param[in] name 6115 * @param[in] class_name 6116 * @param[in] value The value is copied into the statement object; the 6117 * memory pointed to by this parameter can be freed after this call. 6118 * @param[in] value_size 6119 * @return CASS_OK if successful, otherwise an error occurred. 6120 */ 6121 CASS_EXPORT CassError 6122 cass_statement_bind_custom_by_name(CassStatement* statement, 6123 const char* name, 6124 const char* class_name, 6125 const cass_byte_t* value, 6126 size_t value_size); 6127 6128 /** 6129 * Same as cass_statement_bind_custom_by_name(), but with lengths for string 6130 * parameters. 6131 * 6132 * @public @memberof CassStatement 6133 * 6134 * @param[in] statement 6135 * @param[in] name 6136 * @param[in] name_length 6137 * @param[in] class_name 6138 * @param[in] class_name_length 6139 * @param[in] value 6140 * @param[in] value_size 6141 * @return same as cass_statement_bind_custom_by_name() 6142 * 6143 * @see cass_statement_bind_custom_by_name() 6144 */ 6145 CASS_EXPORT CassError 6146 cass_statement_bind_custom_by_name_n(CassStatement* statement, 6147 const char* name, 6148 size_t name_length, 6149 const char* class_name, 6150 size_t class_name_length, 6151 const cass_byte_t* value, 6152 size_t value_size); 6153 6154 /** 6155 * Binds a "uuid" or "timeuuid" to a query or bound statement at the specified index. 6156 * 6157 * @public @memberof CassStatement 6158 * 6159 * @param[in] statement 6160 * @param[in] index 6161 * @param[in] value 6162 * @return CASS_OK if successful, otherwise an error occurred. 6163 */ 6164 CASS_EXPORT CassError 6165 cass_statement_bind_uuid(CassStatement* statement, 6166 size_t index, 6167 CassUuid value); 6168 6169 /** 6170 * Binds a "uuid" or "timeuuid" to all the values 6171 * with the specified name. 6172 * 6173 * This can only be used with statements created by 6174 * cass_prepared_bind() when using Cassandra 2.0 or earlier. 6175 * 6176 * @public @memberof CassStatement 6177 * 6178 * @param[in] statement 6179 * @param[in] name 6180 * @param[in] value 6181 * @return CASS_OK if successful, otherwise an error occurred. 6182 */ 6183 CASS_EXPORT CassError 6184 cass_statement_bind_uuid_by_name(CassStatement* statement, 6185 const char* name, 6186 CassUuid value); 6187 6188 /** 6189 * Same as cass_statement_bind_uuid_by_name(), but with lengths for string 6190 * parameters. 6191 * 6192 * @public @memberof CassStatement 6193 * 6194 * @param[in] statement 6195 * @param[in] name 6196 * @param[in] name_length 6197 * @param[in] value 6198 * @return same as cass_statement_bind_uuid_by_name() 6199 * 6200 * @see cass_statement_bind_uuid_by_name() 6201 */ 6202 CASS_EXPORT CassError 6203 cass_statement_bind_uuid_by_name_n(CassStatement* statement, 6204 const char* name, 6205 size_t name_length, 6206 CassUuid value); 6207 6208 /** 6209 * Binds an "inet" to a query or bound statement at the specified index. 6210 * 6211 * @public @memberof CassStatement 6212 * 6213 * @param[in] statement 6214 * @param[in] index 6215 * @param[in] value 6216 * @return CASS_OK if successful, otherwise an error occurred. 6217 */ 6218 CASS_EXPORT CassError 6219 cass_statement_bind_inet(CassStatement* statement, 6220 size_t index, 6221 CassInet value); 6222 6223 /** 6224 * Binds an "inet" to all the values with the specified name. 6225 * 6226 * This can only be used with statements created by 6227 * cass_prepared_bind() when using Cassandra 2.0 or earlier. 6228 * 6229 * @public @memberof CassStatement 6230 * 6231 * @param[in] statement 6232 * @param[in] name 6233 * @param[in] value 6234 * @return CASS_OK if successful, otherwise an error occurred. 6235 */ 6236 CASS_EXPORT CassError 6237 cass_statement_bind_inet_by_name(CassStatement* statement, 6238 const char* name, 6239 CassInet value); 6240 6241 /** 6242 * Same as cass_statement_bind_inet_by_name(), but with lengths for string 6243 * parameters. 6244 * 6245 * @public @memberof CassStatement 6246 * 6247 * @param[in] statement 6248 * @param[in] name 6249 * @param[in] name_length 6250 * @param[in] value 6251 * @return same as cass_statement_bind_inet_by_name() 6252 * 6253 * @see cass_statement_bind_inet_by_name() 6254 */ 6255 CASS_EXPORT CassError 6256 cass_statement_bind_inet_by_name_n(CassStatement* statement, 6257 const char* name, 6258 size_t name_length, 6259 CassInet value); 6260 6261 /** 6262 * Bind a "decimal" to a query or bound statement at the specified index. 6263 * 6264 * @public @memberof CassStatement 6265 * 6266 * @param[in] statement 6267 * @param[in] index 6268 * @param[in] varint The value is copied into the statement object; the 6269 * memory pointed to by this parameter can be freed after this call. 6270 * @param[in] varint_size 6271 * @param[in] scale 6272 * @return CASS_OK if successful, otherwise an error occurred. 6273 */ 6274 CASS_EXPORT CassError 6275 cass_statement_bind_decimal(CassStatement* statement, 6276 size_t index, 6277 const cass_byte_t* varint, 6278 size_t varint_size, 6279 cass_int32_t scale); 6280 6281 /** 6282 * Binds a "decimal" to all the values with the specified name. 6283 * 6284 * This can only be used with statements created by 6285 * cass_prepared_bind() when using Cassandra 2.0 or earlier. 6286 * 6287 * @public @memberof CassStatement 6288 * 6289 * @param[in] statement 6290 * @param[in] name 6291 * @param[in] varint The value is copied into the statement object; the 6292 * memory pointed to by this parameter can be freed after this call. 6293 * @param[in] varint_size 6294 * @param[in] scale 6295 * @return CASS_OK if successful, otherwise an error occurred. 6296 */ 6297 CASS_EXPORT CassError 6298 cass_statement_bind_decimal_by_name(CassStatement* statement, 6299 const char* name, 6300 const cass_byte_t* varint, 6301 size_t varint_size, 6302 cass_int32_t scale); 6303 6304 /** 6305 * Same as cass_statement_bind_decimal_by_name(), but with lengths for string 6306 * parameters. 6307 * 6308 * @public @memberof CassStatement 6309 * 6310 * @param[in] statement 6311 * @param[in] name 6312 * @param[in] name_length 6313 * @param[in] varint 6314 * @param[in] varint_size 6315 * @param[in] scale 6316 * @return same as cass_statement_bind_decimal_by_name() 6317 * 6318 * @see cass_statement_bind_decimal_by_name() 6319 */ 6320 CASS_EXPORT CassError 6321 cass_statement_bind_decimal_by_name_n(CassStatement* statement, 6322 const char* name, 6323 size_t name_length, 6324 const cass_byte_t* varint, 6325 size_t varint_size, 6326 cass_int32_t scale); 6327 6328 /** 6329 * Binds a "duration" to a query or bound statement at the specified index. 6330 * 6331 * @cassandra{3.10+} 6332 * 6333 * @public @memberof CassStatement 6334 * 6335 * @param[in] statement 6336 * @param[in] index 6337 * @param[in] months 6338 * @param[in] days 6339 * @param[in] nanos 6340 * @return CASS_OK if successful, otherwise an error occurred. 6341 */ 6342 CASS_EXPORT CassError 6343 cass_statement_bind_duration(CassStatement* statement, 6344 size_t index, 6345 cass_int32_t months, 6346 cass_int32_t days, 6347 cass_int64_t nanos); 6348 6349 /** 6350 * Binds a "duration" to all the values with the specified name. 6351 * 6352 * @cassandra{3.10+} 6353 * 6354 * @public @memberof CassStatement 6355 * 6356 * @param[in] statement 6357 * @param[in] name 6358 * @param[in] months 6359 * @param[in] days 6360 * @param[in] nanos 6361 * @return CASS_OK if successful, otherwise an error occurred. 6362 */ 6363 CASS_EXPORT CassError 6364 cass_statement_bind_duration_by_name(CassStatement* statement, 6365 const char* name, 6366 cass_int32_t months, 6367 cass_int32_t days, 6368 cass_int64_t nanos); 6369 6370 /** 6371 * Same as cass_statement_bind_duration_by_name(), but with lengths for string 6372 * parameters. 6373 * 6374 * @cassandra{3.10+} 6375 * 6376 * @public @memberof CassStatement 6377 * 6378 * @param[in] statement 6379 * @param[in] name 6380 * @param[in] name_length 6381 * @param[in] months 6382 * @param[in] days 6383 * @param[in] nanos 6384 * @return same as cass_statement_bind_duration_by_name() 6385 * 6386 * @see cass_statement_bind_duration_by_name() 6387 */ 6388 CASS_EXPORT CassError 6389 cass_statement_bind_duration_by_name_n(CassStatement* statement, 6390 const char* name, 6391 size_t name_length, 6392 cass_int32_t months, 6393 cass_int32_t days, 6394 cass_int64_t nanos); 6395 6396 /** 6397 * Bind a "list", "map" or "set" to a query or bound statement at the 6398 * specified index. 6399 * 6400 * @public @memberof CassStatement 6401 * 6402 * @param[in] statement 6403 * @param[in] index 6404 * @param[in] collection The collection can be freed after this call. 6405 * @return CASS_OK if successful, otherwise an error occurred. 6406 */ 6407 CASS_EXPORT CassError 6408 cass_statement_bind_collection(CassStatement* statement, 6409 size_t index, 6410 const CassCollection* collection); 6411 6412 /** 6413 * Bind a "list", "map" or "set" to all the values with the 6414 * specified name. 6415 * 6416 * This can only be used with statements created by 6417 * cass_prepared_bind() when using Cassandra 2.0 or earlier. 6418 * 6419 * @public @memberof CassStatement 6420 * 6421 * @param[in] statement 6422 * @param[in] name 6423 * @param[in] collection The collection can be freed after this call. 6424 * @return CASS_OK if successful, otherwise an error occurred. 6425 */ 6426 CASS_EXPORT CassError 6427 cass_statement_bind_collection_by_name(CassStatement* statement, 6428 const char* name, 6429 const CassCollection* collection); 6430 6431 /** 6432 * Same as cass_statement_bind_collection_by_name(), but with lengths for string 6433 * parameters. 6434 * 6435 * @public @memberof CassStatement 6436 * 6437 * @param[in] statement 6438 * @param[in] name 6439 * @param[in] name_length 6440 * @param[in] collection 6441 * @return same as cass_statement_bind_collection_by_name() 6442 * 6443 * @see cass_statement_bind_collection_by_name() 6444 */ 6445 CASS_EXPORT CassError 6446 cass_statement_bind_collection_by_name_n(CassStatement* statement, 6447 const char* name, 6448 size_t name_length, 6449 const CassCollection* collection); 6450 6451 /** 6452 * Bind a "tuple" to a query or bound statement at the specified index. 6453 * 6454 * @cassandra{2.1+} 6455 * 6456 * @public @memberof CassStatement 6457 * 6458 * @param[in] statement 6459 * @param[in] index 6460 * @param[in] tuple The tuple can be freed after this call. 6461 * @return CASS_OK if successful, otherwise an error occurred. 6462 */ 6463 CASS_EXPORT CassError 6464 cass_statement_bind_tuple(CassStatement* statement, 6465 size_t index, 6466 const CassTuple* tuple); 6467 6468 /** 6469 * Bind a "tuple" to all the values with the specified name. 6470 * 6471 * @cassandra{2.1+} 6472 * 6473 * @public @memberof CassStatement 6474 * 6475 * @param[in] statement 6476 * @param[in] name 6477 * @param[in] tuple The tuple can be freed after this call. 6478 * @return CASS_OK if successful, otherwise an error occurred. 6479 */ 6480 CASS_EXPORT CassError 6481 cass_statement_bind_tuple_by_name(CassStatement* statement, 6482 const char* name, 6483 const CassTuple* tuple); 6484 6485 /** 6486 * Same as cass_statement_bind_tuple_by_name(), but with lengths for string 6487 * parameters. 6488 * 6489 * @cassandra{2.1+} 6490 * 6491 * @public @memberof CassStatement 6492 * 6493 * @param[in] statement 6494 * @param[in] name 6495 * @param[in] name_length 6496 * @param[in] tuple 6497 * @return same as cass_statement_bind_tuple_by_name() 6498 * 6499 * @see cass_statement_bind_tuple_by_name() 6500 */ 6501 CASS_EXPORT CassError 6502 cass_statement_bind_tuple_by_name_n(CassStatement* statement, 6503 const char* name, 6504 size_t name_length, 6505 const CassTuple* tuple); 6506 6507 /** 6508 * Bind a user defined type to a query or bound statement at the 6509 * specified index. 6510 * 6511 * @cassandra{2.1+} 6512 * 6513 * @public @memberof CassStatement 6514 * 6515 * @param[in] statement 6516 * @param[in] index 6517 * @param[in] user_type The user type can be freed after this call. 6518 * @return CASS_OK if successful, otherwise an error occurred. 6519 */ 6520 CASS_EXPORT CassError 6521 cass_statement_bind_user_type(CassStatement* statement, 6522 size_t index, 6523 const CassUserType* user_type); 6524 /** 6525 * Bind a user defined type to a query or bound statement with the 6526 * specified name. 6527 * 6528 * @cassandra{2.1+} 6529 * 6530 * @public @memberof CassStatement 6531 * 6532 * @param[in] statement 6533 * @param[in] name 6534 * @param[in] user_type The user type can be freed after this call. 6535 * @return CASS_OK if successful, otherwise an error occurred. 6536 */ 6537 CASS_EXPORT CassError 6538 cass_statement_bind_user_type_by_name(CassStatement* statement, 6539 const char* name, 6540 const CassUserType* user_type); 6541 6542 /** 6543 * Same as cass_statement_bind_user_type_by_name(), but with lengths for string 6544 * parameters. 6545 * 6546 * @cassandra{2.1+} 6547 * 6548 * @public @memberof CassStatement 6549 * 6550 * @param[in] statement 6551 * @param[in] name 6552 * @param[in] name_length 6553 * @param[in] user_type 6554 * @return same as cass_statement_bind_user_type_by_name() 6555 * 6556 * @see cass_statement_bind_collection_by_name() 6557 */ 6558 CASS_EXPORT CassError 6559 cass_statement_bind_user_type_by_name_n(CassStatement* statement, 6560 const char* name, 6561 size_t name_length, 6562 const CassUserType* user_type); 6563 6564 /*********************************************************************************** 6565 * 6566 * Prepared 6567 * 6568 ***********************************************************************************/ 6569 6570 /** 6571 * Frees a prepared instance. 6572 * 6573 * @public @memberof CassPrepared 6574 * 6575 * @param[in] prepared 6576 */ 6577 CASS_EXPORT void 6578 cass_prepared_free(const CassPrepared* prepared); 6579 6580 /** 6581 * Creates a bound statement from a pre-prepared statement. 6582 * 6583 * @public @memberof CassPrepared 6584 * 6585 * @param[in] prepared 6586 * @return Returns a bound statement that must be freed. 6587 * 6588 * @see cass_statement_free() 6589 */ 6590 CASS_EXPORT CassStatement* 6591 cass_prepared_bind(const CassPrepared* prepared); 6592 6593 /** 6594 * Gets the name of a parameter at the specified index. 6595 * 6596 * @public @memberof CassPrepared 6597 * 6598 * @param[in] prepared 6599 * @param[in] index 6600 * @param[out] name 6601 * @param[out] name_length 6602 * @return CASS_OK if successful, otherwise an error occurred. 6603 */ 6604 CASS_EXPORT CassError 6605 cass_prepared_parameter_name(const CassPrepared* prepared, 6606 size_t index, 6607 const char** name, 6608 size_t* name_length); 6609 6610 /** 6611 * Gets the data type of a parameter at the specified index. 6612 * 6613 * @public @memberof CassPrepared 6614 * 6615 * @param[in] prepared 6616 * @param[in] index 6617 * @return Returns a reference to the data type of the parameter. Do not free 6618 * this reference as it is bound to the lifetime of the prepared. 6619 */ 6620 CASS_EXPORT const CassDataType* 6621 cass_prepared_parameter_data_type(const CassPrepared* prepared, 6622 size_t index); 6623 6624 /** 6625 * Gets the data type of a parameter for the specified name. 6626 * 6627 * @public @memberof CassPrepared 6628 * 6629 * @param[in] prepared 6630 * @param[in] name 6631 * @return Returns a reference to the data type of the parameter. Do not free 6632 * this reference as it is bound to the lifetime of the prepared. 6633 */ 6634 CASS_EXPORT const CassDataType* 6635 cass_prepared_parameter_data_type_by_name(const CassPrepared* prepared, 6636 const char* name); 6637 6638 /** 6639 * Same as cass_prepared_parameter_data_type_by_name(), but with lengths for string 6640 * parameters. 6641 * 6642 * @public @memberof CassPrepared 6643 * 6644 * @param[in] prepared 6645 * @param[in] name 6646 * @param[in] name_length 6647 * @return Returns a reference to the data type of the parameter. Do not free 6648 * this reference as it is bound to the lifetime of the prepared. 6649 * 6650 * @see cass_prepared_parameter_data_type_by_name() 6651 */ 6652 CASS_EXPORT const CassDataType* 6653 cass_prepared_parameter_data_type_by_name_n(const CassPrepared* prepared, 6654 const char* name, 6655 size_t name_length); 6656 6657 /*********************************************************************************** 6658 * 6659 * Batch 6660 * 6661 ***********************************************************************************/ 6662 6663 /** 6664 * Creates a new batch statement with batch type. 6665 * 6666 * @cassandra{2.0+} 6667 * 6668 * @public @memberof CassBatch 6669 * 6670 * @param[in] type 6671 * @return Returns a batch statement that must be freed. 6672 * 6673 * @see cass_batch_free() 6674 */ 6675 CASS_EXPORT CassBatch* 6676 cass_batch_new(CassBatchType type); 6677 6678 /** 6679 * Frees a batch instance. Batches can be immediately freed after being 6680 * executed. 6681 * 6682 * @cassandra{2.0+} 6683 * 6684 * @public @memberof CassBatch 6685 * 6686 * @param[in] batch 6687 */ 6688 CASS_EXPORT void 6689 cass_batch_free(CassBatch* batch); 6690 6691 /** 6692 * Sets the batch's keyspace. When using protocol v5 or greater it overrides 6693 * the session's keyspace for the batch. 6694 * 6695 * <b>Note:</b> If not set explicitly then the batch will inherit the keyspace 6696 * of the first child statement with a non-empty keyspace. 6697 * 6698 * @public @memberof CassBatch 6699 * 6700 * @param[in] batch 6701 * @param[in] keyspace 6702 * @return CASS_OK if successful, otherwise an error occurred. 6703 */ 6704 CASS_EXPORT CassError 6705 cass_batch_set_keyspace(CassBatch* batch, 6706 const char* keyspace); 6707 6708 /** 6709 * Same as cass_batch_set_keyspace(), but with lengths for string 6710 * parameters. 6711 * 6712 * @public @memberof CassBatch 6713 * 6714 * @param[in] batch 6715 * @param[in] keyspace 6716 * @param[in] keyspace_length 6717 * @return same as cass_batch_set_keyspace() 6718 * 6719 * @see cass_batch_set_keyspace() 6720 */ 6721 CASS_EXPORT CassError 6722 cass_batch_set_keyspace_n(CassBatch* batch, 6723 const char* keyspace, 6724 size_t keyspace_length); 6725 6726 /** 6727 * Sets the batch's consistency level 6728 * 6729 * @cassandra{2.0+} 6730 * 6731 * @public @memberof CassBatch 6732 * 6733 * @param[in] batch 6734 * @param[in] consistency The batch's write consistency. 6735 * @return CASS_OK if successful, otherwise an error occurred. 6736 */ 6737 CASS_EXPORT CassError 6738 cass_batch_set_consistency(CassBatch* batch, 6739 CassConsistency consistency); 6740 6741 /** 6742 * Sets the batch's serial consistency level. 6743 * 6744 * @cassandra{2.0+} 6745 * 6746 * <b>Default:</b> Not set 6747 * 6748 * @public @memberof CassBatch 6749 * 6750 * @param[in] batch 6751 * @param[in] serial_consistency 6752 * @return CASS_OK if successful, otherwise an error occurred. 6753 */ 6754 CASS_EXPORT CassError 6755 cass_batch_set_serial_consistency(CassBatch* batch, 6756 CassConsistency serial_consistency); 6757 6758 /** 6759 * Sets the batch's timestamp. 6760 * 6761 * @cassandra{2.1+} 6762 * 6763 * @public @memberof CassBatch 6764 * 6765 * @param[in] batch 6766 * @param[in] timestamp 6767 * @return CASS_OK if successful, otherwise an error occurred. 6768 */ 6769 CASS_EXPORT CassError 6770 cass_batch_set_timestamp(CassBatch* batch, 6771 cass_int64_t timestamp); 6772 6773 /** 6774 * Sets the batch's timeout for waiting for a response from a node. 6775 * 6776 * <b>Default:</b> Disabled (use the cluster-level request timeout) 6777 * 6778 * @public @memberof CassBatch 6779 * 6780 * @param[in] batch 6781 * @param[in] timeout_ms Request timeout in milliseconds. Use 0 for no timeout 6782 * or CASS_UINT64_MAX to disable (to use the cluster-level request timeout). 6783 * @return CASS_OK if successful, otherwise an error occurred. 6784 * 6785 * @see cass_cluster_set_request_timeout() 6786 */ 6787 CASS_EXPORT CassError 6788 cass_batch_set_request_timeout(CassBatch* batch, 6789 cass_uint64_t timeout_ms); 6790 6791 /** 6792 * Sets whether the statements in a batch are idempotent. Idempotent batches 6793 * are able to be automatically retried after timeouts/errors and can be 6794 * speculatively executed. 6795 * 6796 * @public @memberof CassBatch 6797 * 6798 * @param[in] batch 6799 * @param[in] is_idempotent 6800 * @return CASS_OK if successful, otherwise an error occurred. 6801 * 6802 * @see cass_cluster_set_constant_speculative_execution_policy() 6803 * @see cass_execution_profile_set_constant_speculative_execution_policy() 6804 */ 6805 CASS_EXPORT CassError 6806 cass_batch_set_is_idempotent(CassBatch* batch, 6807 cass_bool_t is_idempotent); 6808 6809 /** 6810 * Sets the batch's retry policy. 6811 * 6812 * @cassandra{2.0+} 6813 * 6814 * @public @memberof CassBatch 6815 * 6816 * @param[in] batch 6817 * @param[in] retry_policy 6818 * @return CASS_OK if successful, otherwise an error occurred. 6819 */ 6820 CASS_EXPORT CassError 6821 cass_batch_set_retry_policy(CassBatch* batch, 6822 CassRetryPolicy* retry_policy); 6823 6824 /** 6825 * Sets the batch's custom payload. 6826 * 6827 * @cassandra{2.2+} 6828 * 6829 * @public @memberof CassBatch 6830 * 6831 * @param[in] batch 6832 * @param[in] payload 6833 * @return CASS_OK if successful, otherwise an error occurred. 6834 */ 6835 CASS_EXPORT CassError 6836 cass_batch_set_custom_payload(CassBatch* batch, 6837 const CassCustomPayload* payload); 6838 6839 /** 6840 * Sets whether the batch should use tracing. 6841 * 6842 * @cassandra{2.2+} 6843 * 6844 * @public @memberof CassStatement 6845 * 6846 * @param[in] batch 6847 * @param[in] enabled 6848 * @return CASS_OK if successful, otherwise an error occurred. 6849 */ 6850 CASS_EXPORT CassError 6851 cass_batch_set_tracing(CassBatch* batch, 6852 cass_bool_t enabled); 6853 6854 /** 6855 * Adds a statement to a batch. 6856 * 6857 * @cassandra{2.0+} 6858 * 6859 * @public @memberof CassBatch 6860 * 6861 * @param[in] batch 6862 * @param[in] statement 6863 * @return CASS_OK if successful, otherwise an error occurred. 6864 */ 6865 CASS_EXPORT CassError 6866 cass_batch_add_statement(CassBatch* batch, 6867 CassStatement* statement); 6868 6869 /** 6870 * Sets the execution profile to execute the batch with. 6871 * 6872 * <b>Note:</b> NULL or empty string will clear execution profile from batch 6873 * 6874 * @public @memberof CassBatch 6875 * 6876 * @param[in] batch 6877 * @param[in] name 6878 * @return CASS_OK if successful, otherwise an error occurred. 6879 * 6880 * @see cass_cluster_set_execution_profile() 6881 */ 6882 CASS_EXPORT CassError 6883 cass_batch_set_execution_profile(CassBatch* batch, 6884 const char* name); 6885 6886 /** 6887 * Same as cass_batch_set_execution_profile(), but with lengths for string 6888 * parameters. 6889 * 6890 * @public @memberof CassBatch 6891 * 6892 * @param[in] batch 6893 * @param[in] name 6894 * @param[in] name_length 6895 * @return CASS_OK if successful, otherwise an error occurred. 6896 * 6897 * @see cass_batch_set_execution_profile() 6898 */ 6899 CASS_EXPORT CassError 6900 cass_batch_set_execution_profile_n(CassBatch* batch, 6901 const char* name, 6902 size_t name_length); 6903 6904 /*********************************************************************************** 6905 * 6906 * Data type 6907 * 6908 ***********************************************************************************/ 6909 6910 /** 6911 * Creates a new data type with value type. 6912 * 6913 * @public @memberof CassDataType 6914 * 6915 * @param[in] type 6916 * @return Returns a data type that must be freed. 6917 * 6918 * @see cass_data_type_free() 6919 */ 6920 CASS_EXPORT CassDataType* 6921 cass_data_type_new(CassValueType type); 6922 6923 /** 6924 * Creates a new data type from an existing data type. 6925 * 6926 * @public @memberof CassDataType 6927 * 6928 * @param[in] data_type 6929 * @return Returns a data type that must be freed. 6930 * 6931 * @see cass_data_type_free() 6932 */ 6933 CASS_EXPORT CassDataType* 6934 cass_data_type_new_from_existing(const CassDataType* data_type); 6935 6936 /** 6937 * Creates a new tuple data type. 6938 * 6939 * @cassandra{2.1+} 6940 * 6941 * @public @memberof CassDataType 6942 * 6943 * @param[in] item_count The number of items in the tuple 6944 * @return Returns a data type that must be freed. 6945 * 6946 * @see cass_data_type_free() 6947 */ 6948 CASS_EXPORT CassDataType* 6949 cass_data_type_new_tuple(size_t item_count); 6950 6951 /** 6952 * Creates a new UDT (user defined type) data type. 6953 * 6954 * @cassandra{2.1+} 6955 * 6956 * @public @memberof CassDataType 6957 * 6958 * @param[in] field_count The number of fields in the UDT 6959 * @return Returns a data type that must be freed. 6960 * 6961 * @see cass_data_type_free() 6962 */ 6963 CASS_EXPORT CassDataType* 6964 cass_data_type_new_udt(size_t field_count); 6965 6966 /** 6967 * Frees a data type instance. 6968 * 6969 * @public @memberof CassDataType 6970 * 6971 * @param[in] data_type 6972 */ 6973 CASS_EXPORT void 6974 cass_data_type_free(CassDataType* data_type); 6975 6976 /** 6977 * Gets the value type of the specified data type. 6978 * 6979 * @param[in] data_type 6980 * @return The value type 6981 */ 6982 CASS_EXPORT CassValueType 6983 cass_data_type_type(const CassDataType* data_type); 6984 6985 /** 6986 * Gets whether a data type is frozen. 6987 * 6988 * @cassandra{2.1+} 6989 * 6990 * @param[in] data_type 6991 * @return cass_true if the data type is frozen, otherwise cass_false. 6992 */ 6993 CASS_EXPORT cass_bool_t 6994 cass_data_type_is_frozen(const CassDataType* data_type); 6995 6996 /** 6997 * Gets the type name of a UDT data type. 6998 * 6999 * <b>Note:</b> Only valid for UDT data types. 7000 * 7001 * @param[in] data_type 7002 * @param[out] type_name 7003 * @param[out] type_name_length 7004 * @return CASS_OK if successful, otherwise an error occurred. 7005 */ 7006 CASS_EXPORT CassError 7007 cass_data_type_type_name(const CassDataType* data_type, 7008 const char** type_name, 7009 size_t* type_name_length); 7010 7011 /** 7012 * Sets the type name of a UDT data type. 7013 * 7014 * <b>Note:</b> Only valid for UDT data types. 7015 * 7016 * @param[in] data_type 7017 * @param[in] type_name 7018 * @return CASS_OK if successful, otherwise an error occurred. 7019 */ 7020 CASS_EXPORT CassError 7021 cass_data_type_set_type_name(CassDataType* data_type, 7022 const char* type_name); 7023 7024 /** 7025 * Same as cass_data_type_set_type_name(), but with lengths for string 7026 * parameters. 7027 * 7028 * @public @memberof CassDataType 7029 * 7030 * @param[in] data_type 7031 * @param[in] type_name 7032 * @param[in] type_name_length 7033 * @return Returns a data type that must be freed. 7034 */ 7035 CASS_EXPORT CassError 7036 cass_data_type_set_type_name_n(CassDataType* data_type, 7037 const char* type_name, 7038 size_t type_name_length); 7039 7040 /** 7041 * Gets the type name of a UDT data type. 7042 * 7043 * <b>Note:</b> Only valid for UDT data types. 7044 * 7045 * @cassandra{2.1+} 7046 * 7047 * @param[in] data_type 7048 * @param[out] keyspace 7049 * @param[out] keyspace_length 7050 * @return CASS_OK if successful, otherwise an error occurred. 7051 */ 7052 CASS_EXPORT CassError 7053 cass_data_type_keyspace(const CassDataType* data_type, 7054 const char** keyspace, 7055 size_t* keyspace_length); 7056 7057 /** 7058 * Sets the keyspace of a UDT data type. 7059 * 7060 * <b>Note:</b> Only valid for UDT data types. 7061 * 7062 * @cassandra{2.1+} 7063 * 7064 * @param[in] data_type 7065 * @param[in] keyspace 7066 * @return CASS_OK if successful, otherwise an error occurred. 7067 */ 7068 CASS_EXPORT CassError 7069 cass_data_type_set_keyspace(CassDataType* data_type, 7070 const char* keyspace); 7071 7072 /** 7073 * Same as cass_data_type_set_keyspace(), but with lengths for string 7074 * parameters. 7075 * 7076 * @cassandra{2.1+} 7077 * 7078 * @public @memberof CassDataType 7079 * 7080 * @param[in] data_type 7081 * @param[in] keyspace 7082 * @param[in] keyspace_length 7083 * @return Returns a data type that must be freed. 7084 */ 7085 CASS_EXPORT CassError 7086 cass_data_type_set_keyspace_n(CassDataType* data_type, 7087 const char* keyspace, 7088 size_t keyspace_length); 7089 7090 /** 7091 * Gets the class name of a custom data type. 7092 * 7093 * <b>Note:</b> Only valid for custom data types. 7094 * 7095 * @param[in] data_type 7096 * @param[out] class_name 7097 * @param[out] class_name_length 7098 * @return CASS_OK if successful, otherwise an error occurred. 7099 */ 7100 CASS_EXPORT CassError 7101 cass_data_type_class_name(const CassDataType* data_type, 7102 const char** class_name, 7103 size_t* class_name_length); 7104 7105 /** 7106 * Sets the class name of a custom data type. 7107 * 7108 * <b>Note:</b> Only valid for custom data types. 7109 * 7110 * @param[in] data_type 7111 * @param[in] class_name 7112 * @return CASS_OK if successful, otherwise an error occurred. 7113 */ 7114 CASS_EXPORT CassError 7115 cass_data_type_set_class_name(CassDataType* data_type, 7116 const char* class_name); 7117 7118 /** 7119 * Same as cass_data_type_set_class_name(), but with lengths for string 7120 * parameters. 7121 * 7122 * @public @memberof CassDataType 7123 * 7124 * @param[in] data_type 7125 * @param[in] class_name 7126 * @param[in] class_name_length 7127 * @return Returns a data type that must be freed. 7128 */ 7129 CASS_EXPORT CassError 7130 cass_data_type_set_class_name_n(CassDataType* data_type, 7131 const char* class_name, 7132 size_t class_name_length); 7133 7134 /** 7135 * Gets the sub-data type count of a UDT (user defined type), tuple 7136 * or collection. 7137 * 7138 * <b>Note:</b> Only valid for UDT, tuple and collection data types. 7139 * 7140 * @param[in] data_type 7141 * @return Returns the number of sub-data types 7142 */ 7143 CASS_EXPORT size_t 7144 cass_data_type_sub_type_count(const CassDataType* data_type); 7145 7146 /** 7147 * @deprecated Use cass_data_type_sub_type_count() 7148 */ 7149 CASS_EXPORT CASS_DEPRECATED(size_t 7150 cass_data_sub_type_count(const CassDataType* data_type)); 7151 7152 /** 7153 * Gets the sub-data type count of a UDT (user defined type), tuple 7154 * or collection. 7155 * 7156 * <b>Note:</b> Only valid for UDT, tuple and collection data types. 7157 * 7158 * @param[in] data_type 7159 * @return Returns the number of sub-data types 7160 */ 7161 7162 /** 7163 * Gets the sub-data type of a UDT (user defined type), tuple or collection at 7164 * the specified index. 7165 * 7166 * <b>Note:</b> Only valid for UDT, tuple and collection data types. 7167 * 7168 * @param[in] data_type 7169 * @param[in] index 7170 * @return Returns a reference to a child data type. Do not free this 7171 * reference as it is bound to the lifetime of the parent data type. NULL 7172 * is returned if the index is out of range. 7173 */ 7174 CASS_EXPORT const CassDataType* 7175 cass_data_type_sub_data_type(const CassDataType* data_type, 7176 size_t index); 7177 7178 /** 7179 * Gets the sub-data type of a UDT (user defined type) at the specified index. 7180 * 7181 * <b>Note:</b> Only valid for UDT data types. 7182 * 7183 * @cassandra{2.1+} 7184 * 7185 * @param[in] data_type 7186 * @param[in] name 7187 * @return Returns a reference to a child data type. Do not free this 7188 * reference as it is bound to the lifetime of the parent data type. NULL 7189 * is returned if the name doesn't exist. 7190 */ 7191 CASS_EXPORT const CassDataType* 7192 cass_data_type_sub_data_type_by_name(const CassDataType* data_type, 7193 const char* name); 7194 7195 /** 7196 * Same as cass_data_type_sub_data_type_by_name(), but with lengths for string 7197 * parameters. 7198 * 7199 * @cassandra{2.1+} 7200 * 7201 * @public @memberof CassDataType 7202 * 7203 * @param[in] data_type 7204 * @param[in] name 7205 * @param[in] name_length 7206 * @return Returns a reference to a child data type. Do not free this 7207 * reference as it is bound to the lifetime of the parent data type. NULL 7208 * is returned if the name doesn't exist. 7209 */ 7210 CASS_EXPORT const CassDataType* 7211 cass_data_type_sub_data_type_by_name_n(const CassDataType* data_type, 7212 const char* name, 7213 size_t name_length); 7214 7215 /** 7216 * Gets the sub-type name of a UDT (user defined type) at the specified index. 7217 * 7218 * @cassandra{2.1+} 7219 * 7220 * <b>Note:</b> Only valid for UDT data types. 7221 * 7222 * @param[in] data_type 7223 * @param[in] index 7224 * @param[out] name 7225 * @param[out] name_length 7226 * @return CASS_OK if successful, otherwise an error occurred. 7227 */ 7228 CASS_EXPORT CassError 7229 cass_data_type_sub_type_name(const CassDataType* data_type, 7230 size_t index, 7231 const char** name, 7232 size_t* name_length); 7233 7234 /** 7235 * Adds a sub-data type to a tuple or collection. 7236 * 7237 * <b>Note:</b> Only valid for tuple and collection data types. 7238 * 7239 * @param[in] data_type 7240 * @param[in] sub_data_type 7241 * @return CASS_OK if successful, otherwise an error occurred. 7242 */ 7243 CASS_EXPORT CassError 7244 cass_data_type_add_sub_type(CassDataType* data_type, 7245 const CassDataType* sub_data_type); 7246 7247 /** 7248 * Adds a sub-data type to a UDT (user defined type). 7249 * 7250 * <b>Note:</b> Only valid for UDT data types. 7251 * 7252 * @cassandra{2.1+} 7253 * 7254 * @param[in] data_type 7255 * @param[in] name 7256 * @param[in] sub_data_type 7257 * @return CASS_OK if successful, otherwise an error occurred. 7258 */ 7259 CASS_EXPORT CassError 7260 cass_data_type_add_sub_type_by_name(CassDataType* data_type, 7261 const char* name, 7262 const CassDataType* sub_data_type); 7263 7264 /** 7265 * Same as cass_data_type_add_sub_type_by_name(), but with lengths for string 7266 * parameters. 7267 * 7268 * <b>Note:</b> Only valid for UDT data types. 7269 * 7270 * @cassandra{2.1+} 7271 * 7272 * @param[in] data_type 7273 * @param[in] name 7274 * @param[in] name_length 7275 * @param[in] sub_data_type 7276 * @return CASS_OK if successful, otherwise an error occurred. 7277 */ 7278 CASS_EXPORT CassError 7279 cass_data_type_add_sub_type_by_name_n(CassDataType* data_type, 7280 const char* name, 7281 size_t name_length, 7282 const CassDataType* sub_data_type); 7283 7284 /** 7285 * Adds a sub-data type to a tuple or collection using a value type. 7286 * 7287 * <b>Note:</b> Only valid for tuple and collection data types. 7288 * 7289 * @param[in] data_type 7290 * @param[in] sub_value_type 7291 * @return CASS_OK if successful, otherwise an error occurred. 7292 */ 7293 CASS_EXPORT CassError 7294 cass_data_type_add_sub_value_type(CassDataType* data_type, 7295 CassValueType sub_value_type); 7296 7297 7298 /** 7299 * Adds a sub-data type to a UDT (user defined type) using a value type. 7300 * 7301 * <b>Note:</b> Only valid for UDT data types. 7302 * 7303 * @cassandra{2.1+} 7304 * 7305 * @param[in] data_type 7306 * @param[in] name 7307 * @param[in] sub_value_type 7308 * @return CASS_OK if successful, otherwise an error occurred. 7309 */ 7310 CASS_EXPORT CassError 7311 cass_data_type_add_sub_value_type_by_name(CassDataType* data_type, 7312 const char* name, 7313 CassValueType sub_value_type); 7314 7315 /** 7316 * Same as cass_data_type_add_sub_value_type_by_name(), but with lengths for string 7317 * parameters. 7318 * 7319 * <b>Note:</b> Only valid for UDT data types. 7320 * 7321 * @cassandra{2.1+} 7322 * 7323 * @param[in] data_type 7324 * @param[in] name 7325 * @param[in] name_length 7326 * @param[in] sub_value_type 7327 * @return CASS_OK if successful, otherwise an error occurred. 7328 */ 7329 CASS_EXPORT CassError 7330 cass_data_type_add_sub_value_type_by_name_n(CassDataType* data_type, 7331 const char* name, 7332 size_t name_length, 7333 CassValueType sub_value_type); 7334 7335 /*********************************************************************************** 7336 * 7337 * Collection 7338 * 7339 ***********************************************************************************/ 7340 7341 /** 7342 * Creates a new collection. 7343 * 7344 * @public @memberof CassCollection 7345 * 7346 * @param[in] type 7347 * @param[in] item_count The approximate number of items in the collection. 7348 * @return Returns a collection that must be freed. 7349 * 7350 * @see cass_collection_free() 7351 */ 7352 CASS_EXPORT CassCollection* 7353 cass_collection_new(CassCollectionType type, 7354 size_t item_count); 7355 7356 /** 7357 * Creates a new collection from an existing data type. 7358 * 7359 * @public @memberof CassCollection 7360 * 7361 * @param[in] data_type 7362 * @param[in] item_count The approximate number of items in the collection. 7363 * @return Returns a collection that must be freed. 7364 * 7365 * @see cass_collection_free(); 7366 */ 7367 CASS_EXPORT CassCollection* 7368 cass_collection_new_from_data_type(const CassDataType* data_type, 7369 size_t item_count); 7370 7371 /** 7372 * Frees a collection instance. 7373 * 7374 * @public @memberof CassCollection 7375 * 7376 * @param[in] collection 7377 */ 7378 CASS_EXPORT void 7379 cass_collection_free(CassCollection* collection); 7380 7381 /** 7382 * Gets the data type of a collection. 7383 * 7384 * @param[in] collection 7385 * @return Returns a reference to the data type of the collection. Do not free 7386 * this reference as it is bound to the lifetime of the collection. 7387 */ 7388 CASS_EXPORT const CassDataType* 7389 cass_collection_data_type(const CassCollection* collection); 7390 7391 /** 7392 * Appends a "tinyint" to the collection. 7393 * 7394 * @cassandra{2.2+} 7395 * 7396 * @public @memberof CassCollection 7397 * 7398 * @param[in] collection 7399 * @param[in] value 7400 * @return CASS_OK if successful, otherwise an error occurred. 7401 */ 7402 CASS_EXPORT CassError 7403 cass_collection_append_int8(CassCollection* collection, 7404 cass_int8_t value); 7405 7406 /** 7407 * Appends an "smallint" to the collection. 7408 * 7409 * @cassandra{2.2+} 7410 * 7411 * @public @memberof CassCollection 7412 * 7413 * @param[in] collection 7414 * @param[in] value 7415 * @return CASS_OK if successful, otherwise an error occurred. 7416 */ 7417 CASS_EXPORT CassError 7418 cass_collection_append_int16(CassCollection* collection, 7419 cass_int16_t value); 7420 7421 /** 7422 * Appends an "int" to the collection. 7423 * 7424 * @public @memberof CassCollection 7425 * 7426 * @param[in] collection 7427 * @param[in] value 7428 * @return CASS_OK if successful, otherwise an error occurred. 7429 */ 7430 CASS_EXPORT CassError 7431 cass_collection_append_int32(CassCollection* collection, 7432 cass_int32_t value); 7433 7434 /** 7435 * Appends a "date" to the collection. 7436 * 7437 * @cassandra{2.2+} 7438 * 7439 * @public @memberof CassCollection 7440 * 7441 * @param[in] collection 7442 * @param[in] value 7443 * @return CASS_OK if successful, otherwise an error occurred. 7444 */ 7445 CASS_EXPORT CassError 7446 cass_collection_append_uint32(CassCollection* collection, 7447 cass_uint32_t value); 7448 7449 7450 /** 7451 * Appends a "bigint", "counter", "timestamp" or "time" to the 7452 * collection. 7453 * 7454 * @public @memberof CassCollection 7455 * 7456 * @param[in] collection 7457 * @param[in] value 7458 * @return CASS_OK if successful, otherwise an error occurred. 7459 */ 7460 CASS_EXPORT CassError 7461 cass_collection_append_int64(CassCollection* collection, 7462 cass_int64_t value); 7463 7464 /** 7465 * Appends a "float" to the collection. 7466 * 7467 * @public @memberof CassCollection 7468 * 7469 * @param[in] collection 7470 * @param[in] value 7471 * @return CASS_OK if successful, otherwise an error occurred. 7472 */ 7473 CASS_EXPORT CassError 7474 cass_collection_append_float(CassCollection* collection, 7475 cass_float_t value); 7476 7477 /** 7478 * Appends a "double" to the collection. 7479 * 7480 * @public @memberof CassCollection 7481 * 7482 * @param[in] collection 7483 * @param[in] value 7484 * @return CASS_OK if successful, otherwise an error occurred. 7485 */ 7486 CASS_EXPORT CassError 7487 cass_collection_append_double(CassCollection* collection, 7488 cass_double_t value); 7489 7490 /** 7491 * Appends a "boolean" to the collection. 7492 * 7493 * @public @memberof CassCollection 7494 * 7495 * @param[in] collection 7496 * @param[in] value 7497 * @return CASS_OK if successful, otherwise an error occurred. 7498 */ 7499 CASS_EXPORT CassError 7500 cass_collection_append_bool(CassCollection* collection, 7501 cass_bool_t value); 7502 7503 /** 7504 * Appends an "ascii", "text" or "varchar" to the collection. 7505 * 7506 * @public @memberof CassCollection 7507 * 7508 * @param[in] collection 7509 * @param[in] value The value is copied into the collection object; the 7510 * memory pointed to by this parameter can be freed after this call. 7511 * @return CASS_OK if successful, otherwise an error occurred. 7512 */ 7513 CASS_EXPORT CassError 7514 cass_collection_append_string(CassCollection* collection, 7515 const char* value); 7516 7517 7518 /** 7519 * Same as cass_collection_append_string(), but with lengths for string 7520 * parameters. 7521 * 7522 * @public @memberof CassCollection 7523 * 7524 * @param[in] collection 7525 * @param[in] value 7526 * @param[in] value_length 7527 * @return same as cass_collection_append_string() 7528 * 7529 * @see cass_collection_append_string(); 7530 */ 7531 CASS_EXPORT CassError 7532 cass_collection_append_string_n(CassCollection* collection, 7533 const char* value, 7534 size_t value_length); 7535 7536 /** 7537 * Appends a "blob", "varint" or "custom" to the collection. 7538 * 7539 * @public @memberof CassCollection 7540 * 7541 * @param[in] collection 7542 * @param[in] value The value is copied into the collection object; the 7543 * memory pointed to by this parameter can be freed after this call. 7544 * @param[in] value_size 7545 * @return CASS_OK if successful, otherwise an error occurred. 7546 */ 7547 CASS_EXPORT CassError 7548 cass_collection_append_bytes(CassCollection* collection, 7549 const cass_byte_t* value, 7550 size_t value_size); 7551 7552 /** 7553 * Appends a "custom" to the collection. 7554 * 7555 * @public @memberof CassCollection 7556 * 7557 * @param[in] collection 7558 * @param[in] class_name 7559 * @param[in] value The value is copied into the collection object; the 7560 * memory pointed to by this parameter can be freed after this call. 7561 * @param[in] value_size 7562 * @return CASS_OK if successful, otherwise an error occurred. 7563 */ 7564 CASS_EXPORT CassError 7565 cass_collection_append_custom(CassCollection* collection, 7566 const char* class_name, 7567 const cass_byte_t* value, 7568 size_t value_size); 7569 7570 /** 7571 * Same as cass_collection_append_custom(), but with lengths for string 7572 * parameters. 7573 * 7574 * @public @memberof CassCollection 7575 * 7576 * @param[in] collection 7577 * @param[in] class_name 7578 * @param[in] class_name_length 7579 * @param[in] value 7580 * @param[in] value_size 7581 * @return same as cass_collection_append_custom() 7582 * 7583 * @see cass_collection_append_custom() 7584 */ 7585 CASS_EXPORT CassError 7586 cass_collection_append_custom_n(CassCollection* collection, 7587 const char* class_name, 7588 size_t class_name_length, 7589 const cass_byte_t* value, 7590 size_t value_size); 7591 7592 /** 7593 * Appends a "uuid" or "timeuuid" to the collection. 7594 * 7595 * @public @memberof CassCollection 7596 * 7597 * @param[in] collection 7598 * @param[in] value 7599 * @return CASS_OK if successful, otherwise an error occurred. 7600 */ 7601 CASS_EXPORT CassError 7602 cass_collection_append_uuid(CassCollection* collection, 7603 CassUuid value); 7604 7605 /** 7606 * Appends an "inet" to the collection. 7607 * 7608 * @public @memberof CassCollection 7609 * 7610 * @param[in] collection 7611 * @param[in] value 7612 * @return CASS_OK if successful, otherwise an error occurred. 7613 */ 7614 CASS_EXPORT CassError 7615 cass_collection_append_inet(CassCollection* collection, 7616 CassInet value); 7617 7618 /** 7619 * Appends a "decimal" to the collection. 7620 * 7621 * @public @memberof CassCollection 7622 * 7623 * @param[in] collection 7624 * @param[in] varint The value is copied into the collection object; the 7625 * memory pointed to by this parameter can be freed after this call. 7626 * @param[in] varint_size 7627 * @param[in] scale 7628 * @return CASS_OK if successful, otherwise an error occurred. 7629 */ 7630 CASS_EXPORT CassError 7631 cass_collection_append_decimal(CassCollection* collection, 7632 const cass_byte_t* varint, 7633 size_t varint_size, 7634 cass_int32_t scale); 7635 7636 /** 7637 * Appends a "duration" to the collection. 7638 * 7639 * @cassandra{3.10+} 7640 * 7641 * @public @memberof CassCollection 7642 * 7643 * @param[in] collection 7644 * @param[in] months 7645 * @param[in] days 7646 * @param[in] nanos 7647 * @return CASS_OK if successful, otherwise an error occurred. 7648 */ 7649 CASS_EXPORT CassError 7650 cass_collection_append_duration(CassCollection* collection, 7651 cass_int32_t months, 7652 cass_int32_t days, 7653 cass_int64_t nanos); 7654 7655 /** 7656 * Appends a "list", "map" or "set" to the collection. 7657 * 7658 * @cassandra{2.1+} 7659 * 7660 * @public @memberof CassCollection 7661 * 7662 * @param[in] collection 7663 * @param[in] value 7664 * @return CASS_OK if successful, otherwise an error occurred. 7665 */ 7666 CASS_EXPORT CassError 7667 cass_collection_append_collection(CassCollection* collection, 7668 const CassCollection* value); 7669 7670 /** 7671 * Appends a "tuple" to the collection. 7672 * 7673 * @cassandra{2.1+} 7674 * 7675 * @public @memberof CassCollection 7676 * 7677 * @param[in] collection 7678 * @param[in] value 7679 * @return CASS_OK if successful, otherwise an error occurred. 7680 */ 7681 CASS_EXPORT CassError 7682 cass_collection_append_tuple(CassCollection* collection, 7683 const CassTuple* value); 7684 7685 /** 7686 * Appends a "udt" to the collection. 7687 * 7688 * @cassandra{2.1+} 7689 * 7690 * @public @memberof CassCollection 7691 * 7692 * @param[in] collection 7693 * @param[in] value 7694 * @return CASS_OK if successful, otherwise an error occurred. 7695 */ 7696 CASS_EXPORT CassError 7697 cass_collection_append_user_type(CassCollection* collection, 7698 const CassUserType* value); 7699 7700 /*********************************************************************************** 7701 * 7702 * Tuple 7703 * 7704 ***********************************************************************************/ 7705 7706 /** 7707 * Creates a new tuple. 7708 * 7709 * @cassandra{2.1+} 7710 * 7711 * @public @memberof CassTuple 7712 * 7713 * @param[in] item_count The number of items in the tuple. 7714 * @return Returns a tuple that must be freed. 7715 * 7716 * @see cass_tuple_free() 7717 */ 7718 CASS_EXPORT CassTuple* 7719 cass_tuple_new(size_t item_count); 7720 7721 /** 7722 * Creates a new tuple from an existing data type. 7723 * 7724 * @cassandra{2.1+} 7725 * 7726 * @public @memberof CassTuple 7727 * 7728 * @param[in] data_type 7729 * @return Returns a tuple that must be freed. 7730 * 7731 * @see cass_tuple_free(); 7732 */ 7733 CASS_EXPORT CassTuple* 7734 cass_tuple_new_from_data_type(const CassDataType* data_type); 7735 7736 /** 7737 * Frees a tuple instance. 7738 * 7739 * @cassandra{2.1+} 7740 * 7741 * @public @memberof CassTuple 7742 * 7743 * @param[in] tuple 7744 */ 7745 CASS_EXPORT void 7746 cass_tuple_free(CassTuple* tuple); 7747 7748 /** 7749 * Gets the data type of a tuple. 7750 * 7751 * @cassandra{2.1+} 7752 * 7753 * @param[in] tuple 7754 * @return Returns a reference to the data type of the tuple. Do not free 7755 * this reference as it is bound to the lifetime of the tuple. 7756 */ 7757 CASS_EXPORT const CassDataType* 7758 cass_tuple_data_type(const CassTuple* tuple); 7759 7760 /** 7761 * Sets an null in a tuple at the specified index. 7762 * 7763 * @cassandra{2.1+} 7764 * 7765 * @public @memberof CassTuple 7766 * 7767 * @param[in] tuple 7768 * @param[in] index 7769 * @return CASS_OK if successful, otherwise an error occurred. 7770 */ 7771 CASS_EXPORT CassError 7772 cass_tuple_set_null(CassTuple* tuple, size_t index); 7773 7774 /** 7775 * Sets a "tinyint" in a tuple at the specified index. 7776 * 7777 * @cassandra{2.2+} 7778 * 7779 * @public @memberof CassTuple 7780 * 7781 * @param[in] tuple 7782 * @param[in] index 7783 * @param[in] value 7784 * @return CASS_OK if successful, otherwise an error occurred. 7785 */ 7786 CASS_EXPORT CassError 7787 cass_tuple_set_int8(CassTuple* tuple, 7788 size_t index, 7789 cass_int8_t value); 7790 7791 /** 7792 * Sets an "smallint" in a tuple at the specified index. 7793 * 7794 * @cassandra{2.2+} 7795 * 7796 * @public @memberof CassTuple 7797 * 7798 * @param[in] tuple 7799 * @param[in] index 7800 * @param[in] value 7801 * @return CASS_OK if successful, otherwise an error occurred. 7802 */ 7803 CASS_EXPORT CassError 7804 cass_tuple_set_int16(CassTuple* tuple, 7805 size_t index, 7806 cass_int16_t value); 7807 7808 /** 7809 * Sets an "int" in a tuple at the specified index. 7810 * 7811 * @cassandra{2.1+} 7812 * 7813 * @public @memberof CassTuple 7814 * 7815 * @param[in] tuple 7816 * @param[in] index 7817 * @param[in] value 7818 * @return CASS_OK if successful, otherwise an error occurred. 7819 */ 7820 CASS_EXPORT CassError 7821 cass_tuple_set_int32(CassTuple* tuple, 7822 size_t index, 7823 cass_int32_t value); 7824 7825 /** 7826 * Sets a "date" in a tuple at the specified index. 7827 * 7828 * @cassandra{2.2+} 7829 * 7830 * @public @memberof CassTuple 7831 * 7832 * @param[in] tuple 7833 * @param[in] index 7834 * @param[in] value 7835 * @return CASS_OK if successful, otherwise an error occurred. 7836 */ 7837 CASS_EXPORT CassError 7838 cass_tuple_set_uint32(CassTuple* tuple, 7839 size_t index, 7840 cass_uint32_t value); 7841 7842 /** 7843 * Sets a "bigint", "counter", "timestamp" or "time" in a tuple at the 7844 * specified index. 7845 * 7846 * @cassandra{2.1+} 7847 * 7848 * @public @memberof CassTuple 7849 * 7850 * @param[in] tuple 7851 * @param[in] index 7852 * @param[in] value 7853 * @return CASS_OK if successful, otherwise an error occurred. 7854 */ 7855 CASS_EXPORT CassError 7856 cass_tuple_set_int64(CassTuple* tuple, 7857 size_t index, 7858 cass_int64_t value); 7859 7860 /** 7861 * Sets a "float" in a tuple at the specified index. 7862 * 7863 * @cassandra{2.1+} 7864 * 7865 * @public @memberof CassTuple 7866 * 7867 * @param[in] tuple 7868 * @param[in] index 7869 * @param[in] value 7870 * @return CASS_OK if successful, otherwise an error occurred. 7871 */ 7872 CASS_EXPORT CassError 7873 cass_tuple_set_float(CassTuple* tuple, 7874 size_t index, 7875 cass_float_t value); 7876 7877 /** 7878 * Sets a "double" in a tuple at the specified index. 7879 * 7880 * @cassandra{2.1+} 7881 * 7882 * @public @memberof CassTuple 7883 * 7884 * @param[in] tuple 7885 * @param[in] index 7886 * @param[in] value 7887 * @return CASS_OK if successful, otherwise an error occurred. 7888 */ 7889 CASS_EXPORT CassError 7890 cass_tuple_set_double(CassTuple* tuple, 7891 size_t index, 7892 cass_double_t value); 7893 7894 /** 7895 * Sets a "boolean" in a tuple at the specified index. 7896 * 7897 * @cassandra{2.1+} 7898 * 7899 * @public @memberof CassTuple 7900 * 7901 * @param[in] tuple 7902 * @param[in] index 7903 * @param[in] value 7904 * @return CASS_OK if successful, otherwise an error occurred. 7905 */ 7906 CASS_EXPORT CassError 7907 cass_tuple_set_bool(CassTuple* tuple, 7908 size_t index, 7909 cass_bool_t value); 7910 7911 /** 7912 * Sets an "ascii", "text" or "varchar" in a tuple at the specified index. 7913 * 7914 * @cassandra{2.1+} 7915 * 7916 * @public @memberof CassTuple 7917 * 7918 * @param[in] tuple 7919 * @param[in] index 7920 * @param[in] value The value is copied into the tuple object; the 7921 * memory pointed to by this parameter can be freed after this call. 7922 * @return CASS_OK if successful, otherwise an error occurred. 7923 */ 7924 CASS_EXPORT CassError 7925 cass_tuple_set_string(CassTuple* tuple, 7926 size_t index, 7927 const char* value); 7928 7929 /** 7930 * Same as cass_tuple_set_string(), but with lengths for string 7931 * parameters. 7932 * 7933 * @cassandra{2.1+} 7934 * 7935 * @public @memberof CassTuple 7936 * 7937 * @param[in] tuple 7938 * @param[in] index 7939 * @param[in] value 7940 * @param[in] value_length 7941 * @return same as cass_tuple_set_string() 7942 * 7943 * @see cass_tuple_set_string(); 7944 */ 7945 CASS_EXPORT CassError 7946 cass_tuple_set_string_n(CassTuple* tuple, 7947 size_t index, 7948 const char* value, 7949 size_t value_length); 7950 7951 /** 7952 * Sets a "blob", "varint" or "custom" in a tuple at the specified index. 7953 * 7954 * @cassandra{2.1+} 7955 * 7956 * @public @memberof CassTuple 7957 * 7958 * @param[in] tuple 7959 * @param[in] index 7960 * @param[in] value The value is copied into the tuple object; the 7961 * memory pointed to by this parameter can be freed after this call. 7962 * @param[in] value_size 7963 * @return CASS_OK if successful, otherwise an error occurred. 7964 */ 7965 CASS_EXPORT CassError 7966 cass_tuple_set_bytes(CassTuple* tuple, 7967 size_t index, 7968 const cass_byte_t* value, 7969 size_t value_size); 7970 7971 /** 7972 * Sets a "custom" in a tuple at the specified index. 7973 * 7974 * @public @memberof CassTuple 7975 * 7976 * @param[in] tuple 7977 * @param[in] index 7978 * @param[in] class_name 7979 * @param[in] value The value is copied into the tuple object; the 7980 * memory pointed to by this parameter can be freed after this call. 7981 * @param[in] value_size 7982 * @return CASS_OK if successful, otherwise an error occurred. 7983 */ 7984 CASS_EXPORT CassError 7985 cass_tuple_set_custom(CassTuple* tuple, 7986 size_t index, 7987 const char* class_name, 7988 const cass_byte_t* value, 7989 size_t value_size); 7990 7991 /** 7992 * Same as cass_tuple_set_custom(), but with lengths for string 7993 * parameters. 7994 * 7995 * @public @memberof CassTuple 7996 * 7997 * @param[in] tuple 7998 * @param[in] index 7999 * @param[in] class_name 8000 * @param[in] class_name_length 8001 * @param[in] value 8002 * @param[in] value_size 8003 * @return same as cass_tuple_set_custom() 8004 * 8005 * @see cass_tuple_set_custom() 8006 */ 8007 CASS_EXPORT CassError 8008 cass_tuple_set_custom_n(CassTuple* tuple, 8009 size_t index, 8010 const char* class_name, 8011 size_t class_name_length, 8012 const cass_byte_t* value, 8013 size_t value_size); 8014 8015 /** 8016 * Sets a "uuid" or "timeuuid" in a tuple at the specified index. 8017 * 8018 * @cassandra{2.1+} 8019 * 8020 * @public @memberof CassTuple 8021 * 8022 * @param[in] tuple 8023 * @param[in] index 8024 * @param[in] value 8025 * @return CASS_OK if successful, otherwise an error occurred. 8026 */ 8027 CASS_EXPORT CassError 8028 cass_tuple_set_uuid(CassTuple* tuple, 8029 size_t index, 8030 CassUuid value); 8031 8032 /** 8033 * Sets an "inet" in a tuple at the specified index. 8034 * 8035 * @cassandra{2.1+} 8036 * 8037 * @public @memberof CassTuple 8038 * 8039 * @param[in] tuple 8040 * @param[in] index 8041 * @param[in] value 8042 * @return CASS_OK if successful, otherwise an error occurred. 8043 */ 8044 CASS_EXPORT CassError 8045 cass_tuple_set_inet(CassTuple* tuple, 8046 size_t index, 8047 CassInet value); 8048 8049 /** 8050 * Sets a "decimal" in a tuple at the specified index. 8051 * 8052 * @cassandra{2.1+} 8053 * 8054 * @public @memberof CassTuple 8055 * 8056 * @param[in] tuple 8057 * @param[in] index 8058 * @param[in] varint The value is copied into the tuple object; the 8059 * memory pointed to by this parameter can be freed after this call. 8060 * @param[in] varint_size 8061 * @param[in] scale 8062 * @return CASS_OK if successful, otherwise an error occurred. 8063 */ 8064 CASS_EXPORT CassError 8065 cass_tuple_set_decimal(CassTuple* tuple, 8066 size_t index, 8067 const cass_byte_t* varint, 8068 size_t varint_size, 8069 cass_int32_t scale); 8070 8071 /** 8072 * Sets a "duration" in a tuple at the specified index. 8073 * 8074 * @cassandra{3.10+} 8075 * 8076 * @public @memberof CassTuple 8077 * 8078 * @param[in] tuple 8079 * @param[in] index 8080 * @param[in] months 8081 * @param[in] days 8082 * @param[in] nanos 8083 * @return CASS_OK if successful, otherwise an error occurred. 8084 */ 8085 CASS_EXPORT CassError 8086 cass_tuple_set_duration(CassTuple* tuple, 8087 size_t index, 8088 cass_int32_t months, 8089 cass_int32_t days, 8090 cass_int64_t nanos); 8091 8092 /** 8093 * Sets a "list", "map" or "set" in a tuple at the specified index. 8094 * 8095 * @cassandra{2.1+} 8096 * 8097 * @public @memberof CassTuple 8098 * 8099 * @param[in] tuple 8100 * @param[in] index 8101 * @param[in] value 8102 * @return CASS_OK if successful, otherwise an error occurred. 8103 */ 8104 CASS_EXPORT CassError 8105 cass_tuple_set_collection(CassTuple* tuple, 8106 size_t index, 8107 const CassCollection* value); 8108 8109 /** 8110 * Sets a "tuple" in a tuple at the specified index. 8111 * 8112 * @cassandra{2.1+} 8113 * 8114 * @public @memberof CassTuple 8115 * 8116 * @param[in] tuple 8117 * @param[in] index 8118 * @param[in] value 8119 * @return CASS_OK if successful, otherwise an error occurred. 8120 */ 8121 CASS_EXPORT CassError 8122 cass_tuple_set_tuple(CassTuple* tuple, 8123 size_t index, 8124 const CassTuple* value); 8125 8126 /** 8127 * Sets a "udt" in a tuple at the specified index. 8128 * 8129 * @cassandra{2.1+} 8130 * 8131 * @public @memberof CassTuple 8132 * 8133 * @param[in] tuple 8134 * @param[in] index 8135 * @param[in] value 8136 * @return CASS_OK if successful, otherwise an error occurred. 8137 */ 8138 CASS_EXPORT CassError 8139 cass_tuple_set_user_type(CassTuple* tuple, 8140 size_t index, 8141 const CassUserType* value); 8142 8143 /*********************************************************************************** 8144 * 8145 * User defined type 8146 * 8147 ***********************************************************************************/ 8148 8149 /** 8150 * Creates a new user defined type from existing data type; 8151 * 8152 * @cassandra{2.1+} 8153 * 8154 * @public @memberof CassUserType 8155 * 8156 * @param[in] data_type 8157 * @return Returns a user defined type that must be freed. NULL is returned if 8158 * the data type is not a user defined type. 8159 * 8160 * @see cass_user_type_free() 8161 */ 8162 CASS_EXPORT CassUserType* 8163 cass_user_type_new_from_data_type(const CassDataType* data_type); 8164 8165 /** 8166 * Frees a user defined type instance. 8167 * 8168 * @cassandra{2.1+} 8169 * 8170 * @public @memberof CassUserType 8171 * 8172 * @param[in] user_type 8173 */ 8174 CASS_EXPORT void 8175 cass_user_type_free(CassUserType* user_type); 8176 8177 /** 8178 * Gets the data type of a user defined type. 8179 * 8180 * @cassandra{2.1+} 8181 * 8182 * @param[in] user_type 8183 * @return Returns a reference to the data type of the user defined type. 8184 * Do not free this reference as it is bound to the lifetime of the 8185 * user defined type. 8186 */ 8187 CASS_EXPORT const CassDataType* 8188 cass_user_type_data_type(const CassUserType* user_type); 8189 8190 /** 8191 * Sets a null in a user defined type at the specified index. 8192 * 8193 * @cassandra{2.1+} 8194 * 8195 * @public @memberof CassUserType 8196 * 8197 * @param[in] user_type 8198 * @param[in] index 8199 * @return CASS_OK if successful, otherwise an error occurred. 8200 */ 8201 CASS_EXPORT CassError 8202 cass_user_type_set_null(CassUserType* user_type, 8203 size_t index); 8204 8205 /** 8206 * Sets a null in a user defined type at the specified name. 8207 * 8208 * @cassandra{2.1+} 8209 * 8210 * @public @memberof CassUserType 8211 * 8212 * @param[in] user_type 8213 * @param[in] name 8214 * @return CASS_OK if successful, otherwise an error occurred. 8215 */ 8216 CASS_EXPORT CassError 8217 cass_user_type_set_null_by_name(CassUserType* user_type, 8218 const char* name); 8219 8220 /** 8221 * Same as cass_user_type_set_null_by_name(), but with lengths for string 8222 * parameters. 8223 * 8224 * @cassandra{2.1+} 8225 * 8226 * @public @memberof CassUserType 8227 * 8228 * @param[in] user_type 8229 * @param[in] name 8230 * @param[in] name_length 8231 * @return same as cass_user_type_set_null_by_name() 8232 * 8233 * @see cass_user_type_set_null_by_name() 8234 */ 8235 CASS_EXPORT CassError 8236 cass_user_type_set_null_by_name_n(CassUserType* user_type, 8237 const char* name, 8238 size_t name_length); 8239 8240 /** 8241 * Sets a "tinyint" in a user defined type at the specified index. 8242 * 8243 * @cassandra{2.2+} 8244 * 8245 * @public @memberof CassUserType 8246 * 8247 * @param[in] user_type 8248 * @param[in] index 8249 * @param[in] value 8250 * @return CASS_OK if successful, otherwise an error occurred. 8251 */ 8252 CASS_EXPORT CassError 8253 cass_user_type_set_int8(CassUserType* user_type, 8254 size_t index, 8255 cass_int8_t value); 8256 8257 /** 8258 * Sets a "tinyint" in a user defined type at the specified name. 8259 * 8260 * @cassandra{2.2+} 8261 * 8262 * @public @memberof CassUserType 8263 * 8264 * @param[in] user_type 8265 * @param[in] name 8266 * @param[in] value 8267 * @return CASS_OK if successful, otherwise an error occurred. 8268 */ 8269 CASS_EXPORT CassError 8270 cass_user_type_set_int8_by_name(CassUserType* user_type, 8271 const char* name, 8272 cass_int8_t value); 8273 8274 /** 8275 * Same as cass_user_type_set_int8_by_name(), but with lengths for string 8276 * parameters. 8277 * 8278 * @cassandra{2.2+} 8279 * 8280 * @public @memberof CassUserType 8281 * 8282 * @param[in] user_type 8283 * @param[in] name 8284 * @param[in] name_length 8285 * @param[in] value 8286 * @return same as cass_user_type_set_int8_by_name() 8287 * 8288 * @see cass_user_type_set_int8_by_name() 8289 */ 8290 CASS_EXPORT CassError 8291 cass_user_type_set_int8_by_name_n(CassUserType* user_type, 8292 const char* name, 8293 size_t name_length, 8294 cass_int8_t value); 8295 8296 /** 8297 * Sets an "smallint" in a user defined type at the specified index. 8298 * 8299 * @cassandra{2.2+} 8300 * 8301 * @public @memberof CassUserType 8302 * 8303 * @param[in] user_type 8304 * @param[in] index 8305 * @param[in] value 8306 * @return CASS_OK if successful, otherwise an error occurred. 8307 */ 8308 CASS_EXPORT CassError 8309 cass_user_type_set_int16(CassUserType* user_type, 8310 size_t index, 8311 cass_int16_t value); 8312 8313 /** 8314 * Sets an "smallint" in a user defined type at the specified name. 8315 * 8316 * @cassandra{2.2+} 8317 * 8318 * @public @memberof CassUserType 8319 * 8320 * @param[in] user_type 8321 * @param[in] name 8322 * @param[in] value 8323 * @return CASS_OK if successful, otherwise an error occurred. 8324 */ 8325 CASS_EXPORT CassError 8326 cass_user_type_set_int16_by_name(CassUserType* user_type, 8327 const char* name, 8328 cass_int16_t value); 8329 8330 /** 8331 * Same as cass_user_type_set_int16_by_name(), but with lengths for string 8332 * parameters. 8333 * 8334 * @cassandra{2.2+} 8335 * 8336 * @public @memberof CassUserType 8337 * 8338 * @param[in] user_type 8339 * @param[in] name 8340 * @param[in] name_length 8341 * @param[in] value 8342 * @return same as cass_user_type_set_int16_by_name() 8343 * 8344 * @see cass_user_type_set_int16_by_name() 8345 */ 8346 CASS_EXPORT CassError 8347 cass_user_type_set_int16_by_name_n(CassUserType* user_type, 8348 const char* name, 8349 size_t name_length, 8350 cass_int16_t value); 8351 8352 /** 8353 * Sets an "int" in a user defined type at the specified index. 8354 * 8355 * @cassandra{2.1+} 8356 * 8357 * @public @memberof CassUserType 8358 * 8359 * @param[in] user_type 8360 * @param[in] index 8361 * @param[in] value 8362 * @return CASS_OK if successful, otherwise an error occurred. 8363 */ 8364 CASS_EXPORT CassError 8365 cass_user_type_set_int32(CassUserType* user_type, 8366 size_t index, 8367 cass_int32_t value); 8368 8369 /** 8370 * Sets an "int" in a user defined type at the specified name. 8371 * 8372 * @cassandra{2.1+} 8373 * 8374 * @public @memberof CassUserType 8375 * 8376 * @param[in] user_type 8377 * @param[in] name 8378 * @param[in] value 8379 * @return CASS_OK if successful, otherwise an error occurred. 8380 */ 8381 CASS_EXPORT CassError 8382 cass_user_type_set_int32_by_name(CassUserType* user_type, 8383 const char* name, 8384 cass_int32_t value); 8385 8386 /** 8387 * Same as cass_user_type_set_int32_by_name(), but with lengths for string 8388 * parameters. 8389 * 8390 * @cassandra{2.1+} 8391 * 8392 * @public @memberof CassUserType 8393 * 8394 * @param[in] user_type 8395 * @param[in] name 8396 * @param[in] name_length 8397 * @param[in] value 8398 * @return same as cass_user_type_set_int32_by_name() 8399 * 8400 * @see cass_user_type_set_int32_by_name() 8401 */ 8402 CASS_EXPORT CassError 8403 cass_user_type_set_int32_by_name_n(CassUserType* user_type, 8404 const char* name, 8405 size_t name_length, 8406 cass_int32_t value); 8407 8408 /** 8409 * Sets a "date" in a user defined type at the specified index. 8410 * 8411 * @cassandra{2.2+} 8412 * 8413 * @public @memberof CassUserType 8414 * 8415 * @param[in] user_type 8416 * @param[in] index 8417 * @param[in] value 8418 * @return CASS_OK if successful, otherwise an error occurred. 8419 */ 8420 CASS_EXPORT CassError 8421 cass_user_type_set_uint32(CassUserType* user_type, 8422 size_t index, 8423 cass_uint32_t value); 8424 8425 /** 8426 * Sets a "date" in a user defined type at the specified name. 8427 * 8428 * @cassandra{2.2+} 8429 * 8430 * @public @memberof CassUserType 8431 * 8432 * @param[in] user_type 8433 * @param[in] name 8434 * @param[in] value 8435 * @return CASS_OK if successful, otherwise an error occurred. 8436 */ 8437 CASS_EXPORT CassError 8438 cass_user_type_set_uint32_by_name(CassUserType* user_type, 8439 const char* name, 8440 cass_uint32_t value); 8441 8442 /** 8443 * Same as cass_user_type_set_uint32_by_name(), but with lengths for string 8444 * parameters. 8445 * 8446 * @cassandra{2.2+} 8447 * 8448 * @public @memberof CassUserType 8449 * 8450 * @param[in] user_type 8451 * @param[in] name 8452 * @param[in] name_length 8453 * @param[in] value 8454 * @return same as cass_user_type_set_uint32_by_name() 8455 * 8456 * @see cass_user_type_set_uint32_by_name() 8457 */ 8458 CASS_EXPORT CassError 8459 cass_user_type_set_uint32_by_name_n(CassUserType* user_type, 8460 const char* name, 8461 size_t name_length, 8462 cass_uint32_t value); 8463 8464 8465 /** 8466 * Sets an "bigint", "counter", "timestamp" or "time" in a 8467 * user defined type at the specified index. 8468 * 8469 * @cassandra{2.1+} 8470 * 8471 * @public @memberof CassUserType 8472 * 8473 * @param[in] user_type 8474 * @param[in] index 8475 * @param[in] value 8476 * @return CASS_OK if successful, otherwise an error occurred. 8477 */ 8478 CASS_EXPORT CassError 8479 cass_user_type_set_int64(CassUserType* user_type, 8480 size_t index, 8481 cass_int64_t value); 8482 8483 /** 8484 * Sets an "bigint", "counter", "timestamp" or "time" in a 8485 * user defined type at the specified name. 8486 * 8487 * @cassandra{2.1+} 8488 * 8489 * @public @memberof CassUserType 8490 * 8491 * @param[in] user_type 8492 * @param[in] name 8493 * @param[in] value 8494 * @return CASS_OK if successful, otherwise an error occurred. 8495 */ 8496 CASS_EXPORT CassError 8497 cass_user_type_set_int64_by_name(CassUserType* user_type, 8498 const char* name, 8499 cass_int64_t value); 8500 8501 /** 8502 * Same as cass_user_type_set_int64_by_name(), but with lengths for string 8503 * parameters. 8504 * 8505 * @cassandra{2.1+} 8506 * 8507 * @public @memberof CassUserType 8508 * 8509 * @param[in] user_type 8510 * @param[in] name 8511 * @param[in] name_length 8512 * @param[in] value 8513 * @return same as cass_user_type_set_int64_by_name() 8514 * 8515 * @see cass_user_type_set_int64_by_name() 8516 */ 8517 CASS_EXPORT CassError 8518 cass_user_type_set_int64_by_name_n(CassUserType* user_type, 8519 const char* name, 8520 size_t name_length, 8521 cass_int64_t value); 8522 8523 /** 8524 * Sets a "float" in a user defined type at the specified index. 8525 * 8526 * @cassandra{2.1+} 8527 * 8528 * @public @memberof CassUserType 8529 * 8530 * @param[in] user_type 8531 * @param[in] index 8532 * @param[in] value 8533 * @return CASS_OK if successful, otherwise an error occurred. 8534 */ 8535 CASS_EXPORT CassError 8536 cass_user_type_set_float(CassUserType* user_type, 8537 size_t index, 8538 cass_float_t value); 8539 8540 /** 8541 * Sets a "float" in a user defined type at the specified name. 8542 * 8543 * @cassandra{2.1+} 8544 * 8545 * @public @memberof CassUserType 8546 * 8547 * @param[in] user_type 8548 * @param[in] name 8549 * @param[in] value 8550 * @return CASS_OK if successful, otherwise an error occurred. 8551 */ 8552 CASS_EXPORT CassError 8553 cass_user_type_set_float_by_name(CassUserType* user_type, 8554 const char* name, 8555 cass_float_t value); 8556 8557 /** 8558 * Same as cass_user_type_set_float_by_name(), but with lengths for string 8559 * parameters. 8560 * 8561 * @cassandra{2.1+} 8562 * 8563 * @public @memberof CassUserType 8564 * 8565 * @param[in] user_type 8566 * @param[in] name 8567 * @param[in] name_length 8568 * @param[in] value 8569 * @return same as cass_user_type_set_float_by_name() 8570 * 8571 * @see cass_user_type_set_float_by_name() 8572 */ 8573 CASS_EXPORT CassError 8574 cass_user_type_set_float_by_name_n(CassUserType* user_type, 8575 const char* name, 8576 size_t name_length, 8577 cass_float_t value); 8578 8579 /** 8580 * Sets an "double" in a user defined type at the specified index. 8581 * 8582 * @cassandra{2.1+} 8583 * 8584 * @public @memberof CassUserType 8585 * 8586 * @param[in] user_type 8587 * @param[in] index 8588 * @param[in] value 8589 * @return CASS_OK if successful, otherwise an error occurred. 8590 */ 8591 CASS_EXPORT CassError 8592 cass_user_type_set_double(CassUserType* user_type, 8593 size_t index, 8594 cass_double_t value); 8595 8596 /** 8597 * Sets an "double" in a user defined type at the specified name. 8598 * 8599 * @cassandra{2.1+} 8600 * 8601 * @public @memberof CassUserType 8602 * 8603 * @param[in] user_type 8604 * @param[in] name 8605 * @param[in] value 8606 * @return CASS_OK if successful, otherwise an error occurred. 8607 */ 8608 CASS_EXPORT CassError 8609 cass_user_type_set_double_by_name(CassUserType* user_type, 8610 const char* name, 8611 cass_double_t value); 8612 8613 /** 8614 * Same as cass_user_type_set_double_by_name(), but with lengths for string 8615 * parameters. 8616 * 8617 * @cassandra{2.1+} 8618 * 8619 * @public @memberof CassUserType 8620 * 8621 * @param[in] user_type 8622 * @param[in] name 8623 * @param[in] name_length 8624 * @param[in] value 8625 * @return same as cass_user_type_set_double_by_name() 8626 * 8627 * @see cass_user_type_set_double_by_name() 8628 */ 8629 CASS_EXPORT CassError 8630 cass_user_type_set_double_by_name_n(CassUserType* user_type, 8631 const char* name, 8632 size_t name_length, 8633 cass_double_t value); 8634 8635 /** 8636 * Sets a "boolean" in a user defined type at the specified index. 8637 * 8638 * @cassandra{2.1+} 8639 * 8640 * @public @memberof CassUserType 8641 * 8642 * @param[in] user_type 8643 * @param[in] index 8644 * @param[in] value 8645 * @return CASS_OK if successful, otherwise an error occurred. 8646 */ 8647 CASS_EXPORT CassError 8648 cass_user_type_set_bool(CassUserType* user_type, 8649 size_t index, 8650 cass_bool_t value); 8651 8652 /** 8653 * Sets a "boolean" in a user defined type at the specified name. 8654 * 8655 * @cassandra{2.1+} 8656 * 8657 * @public @memberof CassUserType 8658 * 8659 * @param[in] user_type 8660 * @param[in] name 8661 * @param[in] value 8662 * @return CASS_OK if successful, otherwise an error occurred. 8663 */ 8664 CASS_EXPORT CassError 8665 cass_user_type_set_bool_by_name(CassUserType* user_type, 8666 const char* name, 8667 cass_bool_t value); 8668 8669 /** 8670 * Same as cass_user_type_set_double_by_name(), but with lengths for string 8671 * parameters. 8672 * 8673 * @cassandra{2.1+} 8674 * 8675 * @public @memberof CassUserType 8676 * 8677 * @param[in] user_type 8678 * @param[in] name 8679 * @param[in] name_length 8680 * @param[in] value 8681 * @return same as cass_user_type_set_double_by_name() 8682 * 8683 * @see cass_user_type_set_double_by_name() 8684 */ 8685 CASS_EXPORT CassError 8686 cass_user_type_set_bool_by_name_n(CassUserType* user_type, 8687 const char* name, 8688 size_t name_length, 8689 cass_bool_t value); 8690 8691 8692 /** 8693 * Sets an "ascii", "text" or "varchar" in a user defined type at the 8694 * specified index. 8695 * 8696 * @cassandra{2.1+} 8697 * 8698 * @public @memberof CassUserType 8699 * 8700 * @param[in] user_type 8701 * @param[in] index 8702 * @param[in] value 8703 * @return CASS_OK if successful, otherwise an error occurred. 8704 */ 8705 CASS_EXPORT CassError 8706 cass_user_type_set_string(CassUserType* user_type, 8707 size_t index, 8708 const char* value); 8709 8710 /** 8711 * Same as cass_user_type_set_string(), but with lengths for string 8712 * parameters. 8713 * 8714 * @cassandra{2.1+} 8715 * 8716 * @public @memberof CassUserType 8717 * 8718 * @param[in] user_type 8719 * @param[in] index 8720 * @param[in] value 8721 * @param[in] value_length 8722 * @return same as cass_user_type_set_string() 8723 * 8724 * @see cass_user_type_set_string() 8725 */ 8726 CASS_EXPORT CassError 8727 cass_user_type_set_string_n(CassUserType* user_type, 8728 size_t index, 8729 const char* value, 8730 size_t value_length); 8731 8732 /** 8733 * Sets an "ascii", "text" or "varchar" in a user defined type at the 8734 * specified name. 8735 * 8736 * @cassandra{2.1+} 8737 * 8738 * @public @memberof CassUserType 8739 * 8740 * @param[in] user_type 8741 * @param[in] name 8742 * @param[in] value 8743 * @return CASS_OK if successful, otherwise an error occurred. 8744 */ 8745 CASS_EXPORT CassError 8746 cass_user_type_set_string_by_name(CassUserType* user_type, 8747 const char* name, 8748 const char* value); 8749 8750 /** 8751 * Same as cass_user_type_set_string_by_name(), but with lengths for string 8752 * parameters. 8753 * 8754 * @cassandra{2.1+} 8755 * 8756 * @public @memberof CassUserType 8757 * 8758 * @param[in] user_type 8759 * @param[in] name 8760 * @param[in] name_length 8761 * @param[in] value 8762 * @param[in] value_length 8763 * @return same as cass_user_type_set_string_by_name() 8764 * 8765 * @see cass_user_type_set_string_by_name() 8766 */ 8767 CASS_EXPORT CassError 8768 cass_user_type_set_string_by_name_n(CassUserType* user_type, 8769 const char* name, 8770 size_t name_length, 8771 const char* value, 8772 size_t value_length); 8773 8774 /** 8775 * Sets a "blob" "varint" or "custom" in a user defined type at the specified index. 8776 * 8777 * @cassandra{2.1+} 8778 * 8779 * @public @memberof CassUserType 8780 * 8781 * @param[in] user_type 8782 * @param[in] index 8783 * @param[in] value 8784 * @param[in] value_size 8785 * @return CASS_OK if successful, otherwise an error occurred. 8786 */ 8787 CASS_EXPORT CassError 8788 cass_user_type_set_bytes(CassUserType* user_type, 8789 size_t index, 8790 const cass_byte_t* value, 8791 size_t value_size); 8792 8793 /** 8794 * Sets a "blob", "varint" or "custom" in a user defined type at the specified name. 8795 * 8796 * @cassandra{2.1+} 8797 * 8798 * @public @memberof CassUserType 8799 * 8800 * @param[in] user_type 8801 * @param[in] name 8802 * @param[in] value 8803 * @param[in] value_size 8804 * @return CASS_OK if successful, otherwise an error occurred. 8805 */ 8806 CASS_EXPORT CassError 8807 cass_user_type_set_bytes_by_name(CassUserType* user_type, 8808 const char* name, 8809 const cass_byte_t* value, 8810 size_t value_size); 8811 8812 /** 8813 * Same as cass_user_type_set_bytes_by_name(), but with lengths for string 8814 * parameters. 8815 * 8816 * @cassandra{2.1+} 8817 * 8818 * @public @memberof CassUserType 8819 * 8820 * @param[in] user_type 8821 * @param[in] name 8822 * @param[in] name_length 8823 * @param[in] value 8824 * @param[in] value_size 8825 * @return same as cass_user_type_set_bytes_by_name() 8826 * 8827 * @see cass_user_type_set_bytes_by_name() 8828 */ 8829 CASS_EXPORT CassError 8830 cass_user_type_set_bytes_by_name_n(CassUserType* user_type, 8831 const char* name, 8832 size_t name_length, 8833 const cass_byte_t* value, 8834 size_t value_size); 8835 8836 /** 8837 * Sets a "custom" in a user defined type at the specified index. 8838 * 8839 * @public @memberof CassUserType 8840 * 8841 * @param[in] user_type 8842 * @param[in] index 8843 * @param[in] class_name 8844 * @param[in] value 8845 * @param[in] value_size 8846 * @return CASS_OK if successful, otherwise an error occurred. 8847 */ 8848 CASS_EXPORT CassError 8849 cass_user_type_set_custom(CassUserType* user_type, 8850 size_t index, 8851 const char* class_name, 8852 const cass_byte_t* value, 8853 size_t value_size); 8854 8855 /** 8856 * Same as cass_user_type_set_custom(), but with lengths for string 8857 * parameters. 8858 * 8859 * @public @memberof CassUserType 8860 * 8861 * @param[in] user_type 8862 * @param[in] index 8863 * @param[in] class_name 8864 * @param[in] class_name_length 8865 * @param[in] value 8866 * @param[in] value_size 8867 * @return same as cass_user_type_set_custom() 8868 * 8869 * @see cass_user_type_set_custom() 8870 */ 8871 CASS_EXPORT CassError 8872 cass_user_type_set_custom_n(CassUserType* user_type, 8873 size_t index, 8874 const char* class_name, 8875 size_t class_name_length, 8876 const cass_byte_t* value, 8877 size_t value_size); 8878 8879 /** 8880 * Sets a "custom" in a user defined type at the specified name. 8881 * 8882 * @public @memberof CassUserType 8883 * 8884 * @param[in] user_type 8885 * @param[in] name 8886 * @param[in] class_name 8887 * @param[in] value 8888 * @param[in] value_size 8889 * @return CASS_OK if successful, otherwise an error occurred. 8890 */ 8891 CASS_EXPORT CassError 8892 cass_user_type_set_custom_by_name(CassUserType* user_type, 8893 const char* name, 8894 const char* class_name, 8895 const cass_byte_t* value, 8896 size_t value_size); 8897 8898 /** 8899 * Same as cass_user_type_set_custom_by_name(), but with lengths for string 8900 * parameters. 8901 * 8902 * @public @memberof CassUserType 8903 * 8904 * @param[in] user_type 8905 * @param[in] name 8906 * @param[in] name_length 8907 * @param[in] class_name 8908 * @param[in] class_name_length 8909 * @param[in] value 8910 * @param[in] value_size 8911 * @return same as cass_user_type_set_custom_by_name() 8912 * 8913 * @see cass_user_type_set_custom_by_name() 8914 */ 8915 CASS_EXPORT CassError 8916 cass_user_type_set_custom_by_name_n(CassUserType* user_type, 8917 const char* name, 8918 size_t name_length, 8919 const char* class_name, 8920 size_t class_name_length, 8921 const cass_byte_t* value, 8922 size_t value_size); 8923 8924 /** 8925 * Sets a "uuid" or "timeuuid" in a user defined type at the specified index. 8926 * 8927 * @cassandra{2.1+} 8928 * 8929 * @public @memberof CassUserType 8930 * 8931 * @param[in] user_type 8932 * @param[in] index 8933 * @param[in] value 8934 * @return CASS_OK if successful, otherwise an error occurred. 8935 */ 8936 CASS_EXPORT CassError 8937 cass_user_type_set_uuid(CassUserType* user_type, 8938 size_t index, 8939 CassUuid value); 8940 8941 /** 8942 * Sets a "uuid" or "timeuuid" in a user defined type at the specified name. 8943 * 8944 * @cassandra{2.1+} 8945 * 8946 * @public @memberof CassUserType 8947 * 8948 * @param[in] user_type 8949 * @param[in] name 8950 * @param[in] value 8951 * @return CASS_OK if successful, otherwise an error occurred. 8952 */ 8953 CASS_EXPORT CassError 8954 cass_user_type_set_uuid_by_name(CassUserType* user_type, 8955 const char* name, 8956 CassUuid value); 8957 8958 /** 8959 * Same as cass_user_type_set_uuid_by_name(), but with lengths for string 8960 * parameters. 8961 * 8962 * @cassandra{2.1+} 8963 * 8964 * @public @memberof CassUserType 8965 * 8966 * @param[in] user_type 8967 * @param[in] name 8968 * @param[in] name_length 8969 * @param[in] value 8970 * @return same as cass_user_type_set_uuid_by_name() 8971 * 8972 * @see cass_user_type_set_uuid_by_name() 8973 */ 8974 CASS_EXPORT CassError 8975 cass_user_type_set_uuid_by_name_n(CassUserType* user_type, 8976 const char* name, 8977 size_t name_length, 8978 CassUuid value); 8979 8980 /** 8981 * Sets a "inet" in a user defined type at the specified index. 8982 * 8983 * @cassandra{2.1+} 8984 * 8985 * @public @memberof CassUserType 8986 * 8987 * @param[in] user_type 8988 * @param[in] index 8989 * @param[in] value 8990 * @return CASS_OK if successful, otherwise an error occurred. 8991 */ 8992 CASS_EXPORT CassError 8993 cass_user_type_set_inet(CassUserType* user_type, 8994 size_t index, 8995 CassInet value); 8996 8997 /** 8998 * Sets a "inet" in a user defined type at the specified name. 8999 * 9000 * @cassandra{2.1+} 9001 * 9002 * @public @memberof CassUserType 9003 * 9004 * @param[in] user_type 9005 * @param[in] name 9006 * @param[in] value 9007 * @return CASS_OK if successful, otherwise an error occurred. 9008 */ 9009 CASS_EXPORT CassError 9010 cass_user_type_set_inet_by_name(CassUserType* user_type, 9011 const char* name, 9012 CassInet value); 9013 9014 /** 9015 * Same as cass_user_type_set_inet_by_name(), but with lengths for string 9016 * parameters. 9017 * 9018 * @cassandra{2.1+} 9019 * 9020 * @public @memberof CassUserType 9021 * 9022 * @param[in] user_type 9023 * @param[in] name 9024 * @param[in] name_length 9025 * @param[in] value 9026 * @return same as cass_user_type_set_inet_by_name() 9027 * 9028 * @see cass_user_type_set_inet_by_name() 9029 */ 9030 CASS_EXPORT CassError 9031 cass_user_type_set_inet_by_name_n(CassUserType* user_type, 9032 const char* name, 9033 size_t name_length, 9034 CassInet value); 9035 9036 /** 9037 * Sets an "decimal" in a user defined type at the specified index. 9038 * 9039 * @cassandra{2.1+} 9040 * 9041 * @public @memberof CassUserType 9042 * 9043 * @param[in] user_type 9044 * @param[in] index 9045 * @param[in] varint 9046 * @param[in] varint_size 9047 * @param[in] scale 9048 * @return CASS_OK if successful, otherwise an error occurred. 9049 */ 9050 CASS_EXPORT CassError 9051 cass_user_type_set_decimal(CassUserType* user_type, 9052 size_t index, 9053 const cass_byte_t* varint, 9054 size_t varint_size, 9055 int scale); 9056 9057 /** 9058 * Sets "decimal" in a user defined type at the specified name. 9059 * 9060 * @cassandra{2.1+} 9061 * 9062 * @public @memberof CassUserType 9063 * 9064 * @param[in] user_type 9065 * @param[in] name 9066 * @param[in] varint 9067 * @param[in] varint_size 9068 * @param[in] scale 9069 * @return CASS_OK if successful, otherwise an error occurred. 9070 */ 9071 CASS_EXPORT CassError 9072 cass_user_type_set_decimal_by_name(CassUserType* user_type, 9073 const char* name, 9074 const cass_byte_t* varint, 9075 size_t varint_size, 9076 int scale); 9077 9078 /** 9079 * Same as cass_user_type_set_decimal_by_name(), but with lengths for string 9080 * parameters. 9081 * 9082 * @cassandra{2.1+} 9083 * 9084 * @public @memberof CassUserType 9085 * 9086 * @param[in] user_type 9087 * @param[in] name 9088 * @param[in] name_length 9089 * @param[in] varint 9090 * @param[in] varint_size 9091 * @param[in] scale 9092 * @return same as cass_user_type_set_decimal_by_name() 9093 * 9094 * @see cass_user_type_set_decimal_by_name() 9095 */ 9096 CASS_EXPORT CassError 9097 cass_user_type_set_decimal_by_name_n(CassUserType* user_type, 9098 const char* name, 9099 size_t name_length, 9100 const cass_byte_t* varint, 9101 size_t varint_size, 9102 int scale); 9103 9104 /** 9105 * Sets a "duration" in a user defined type at the specified index. 9106 * 9107 * @cassandra{3.10+} 9108 * 9109 * @public @memberof CassUserType 9110 * 9111 * @param[in] user_type 9112 * @param[in] index 9113 * @param[in] months 9114 * @param[in] days 9115 * @param[in] nanos 9116 * @return CASS_OK if successful, otherwise an error occurred. 9117 */ 9118 CASS_EXPORT CassError 9119 cass_user_type_set_duration(CassUserType* user_type, 9120 size_t index, 9121 cass_int32_t months, 9122 cass_int32_t days, 9123 cass_int64_t nanos); 9124 9125 /** 9126 * Sets "duration" in a user defined type at the specified name. 9127 * 9128 * @cassandra{3.10+} 9129 * 9130 * @public @memberof CassUserType 9131 * 9132 * @param[in] user_type 9133 * @param[in] name 9134 * @param[in] months 9135 * @param[in] days 9136 * @param[in] nanos 9137 * @return CASS_OK if successful, otherwise an error occurred. 9138 */ 9139 CASS_EXPORT CassError 9140 cass_user_type_set_duration_by_name(CassUserType* user_type, 9141 const char* name, 9142 cass_int32_t months, 9143 cass_int32_t days, 9144 cass_int64_t nanos); 9145 9146 /** 9147 * Same as cass_user_type_set_duration_by_name(), but with lengths for string 9148 * parameters. 9149 * 9150 * @cassandra{3.10+} 9151 * 9152 * @public @memberof CassUserType 9153 * 9154 * @param[in] user_type 9155 * @param[in] name 9156 * @param[in] name_length 9157 * @param[in] months 9158 * @param[in] days 9159 * @param[in] nanos 9160 * @return same as cass_user_type_set_duration_by_name() 9161 * 9162 * @see cass_user_type_set_duration_by_name() 9163 */ 9164 CASS_EXPORT CassError 9165 cass_user_type_set_duration_by_name_n(CassUserType* user_type, 9166 const char* name, 9167 size_t name_length, 9168 cass_int32_t months, 9169 cass_int32_t days, 9170 cass_int64_t nanos); 9171 9172 /** 9173 * Sets a "list", "map" or "set" in a user defined type at the 9174 * specified index. 9175 * 9176 * @cassandra{2.1+} 9177 * 9178 * @public @memberof CassUserType 9179 * 9180 * @param[in] user_type 9181 * @param[in] index 9182 * @param[in] value 9183 * @return CASS_OK if successful, otherwise an error occurred. 9184 */ 9185 CASS_EXPORT CassError 9186 cass_user_type_set_collection(CassUserType* user_type, 9187 size_t index, 9188 const CassCollection* value); 9189 9190 /** 9191 * Sets a "list", "map" or "set" in a user defined type at the 9192 * specified name. 9193 * 9194 * @cassandra{2.1+} 9195 * 9196 * @public @memberof CassUserType 9197 * 9198 * @param[in] user_type 9199 * @param[in] name 9200 * @param[in] value 9201 * @return CASS_OK if successful, otherwise an error occurred. 9202 */ 9203 CASS_EXPORT CassError 9204 cass_user_type_set_collection_by_name(CassUserType* user_type, 9205 const char* name, 9206 const CassCollection* value); 9207 9208 /** 9209 * Same as cass_user_type_set_collection_by_name(), but with lengths for string 9210 * parameters. 9211 * 9212 * @cassandra{2.1+} 9213 * 9214 * @public @memberof CassUserType 9215 * 9216 * @param[in] user_type 9217 * @param[in] name 9218 * @param[in] name_length 9219 * @param[in] value 9220 * @return same as cass_user_type_set_collection_by_name() 9221 * 9222 * @see cass_user_type_set_collection_by_name() 9223 */ 9224 CASS_EXPORT CassError 9225 cass_user_type_set_collection_by_name_n(CassUserType* user_type, 9226 const char* name, 9227 size_t name_length, 9228 const CassCollection* value); 9229 9230 /** 9231 * Sets a "tuple" in a user defined type at the specified index. 9232 * 9233 * @cassandra{2.1+} 9234 * 9235 * @public @memberof CassUserType 9236 * 9237 * @param[in] user_type 9238 * @param[in] index 9239 * @param[in] value 9240 * @return CASS_OK if successful, otherwise an error occurred. 9241 */ 9242 CASS_EXPORT CassError 9243 cass_user_type_set_tuple(CassUserType* user_type, 9244 size_t index, 9245 const CassTuple* value); 9246 9247 /** 9248 * Sets a "tuple" in a user defined type at the specified name. 9249 * 9250 * @cassandra{2.1+} 9251 * 9252 * @public @memberof CassUserType 9253 * 9254 * @param[in] user_type 9255 * @param[in] name 9256 * @param[in] value 9257 * @return CASS_OK if successful, otherwise an error occurred. 9258 */ 9259 CASS_EXPORT CassError 9260 cass_user_type_set_tuple_by_name(CassUserType* user_type, 9261 const char* name, 9262 const CassTuple* value); 9263 9264 /** 9265 * Same as cass_user_type_set_tuple_by_name(), but with lengths for string 9266 * parameters. 9267 * 9268 * @cassandra{2.1+} 9269 * 9270 * @public @memberof CassUserType 9271 * 9272 * @param[in] user_type 9273 * @param[in] name 9274 * @param[in] name_length 9275 * @param[in] value 9276 * @return same as cass_user_type_set_tuple_by_name() 9277 * 9278 * @see cass_user_type_set_tuple_by_name() 9279 */ 9280 CASS_EXPORT CassError 9281 cass_user_type_set_tuple_by_name_n(CassUserType* user_type, 9282 const char* name, 9283 size_t name_length, 9284 const CassTuple* value); 9285 9286 /** 9287 * Sets a user defined type in a user defined type at the specified index. 9288 * 9289 * @cassandra{2.1+} 9290 * 9291 * @public @memberof CassUserType 9292 * 9293 * @param[in] user_type 9294 * @param[in] index 9295 * @param[in] value 9296 * @return CASS_OK if successful, otherwise an error occurred. 9297 */ 9298 CASS_EXPORT CassError 9299 cass_user_type_set_user_type(CassUserType* user_type, 9300 size_t index, 9301 const CassUserType* value); 9302 9303 /** 9304 * Sets a user defined type in a user defined type at the specified name. 9305 * 9306 * @cassandra{2.1+} 9307 * 9308 * @public @memberof CassUserType 9309 * 9310 * @param[in] user_type 9311 * @param[in] name 9312 * @param[in] value 9313 * @return CASS_OK if successful, otherwise an error occurred. 9314 */ 9315 CASS_EXPORT CassError 9316 cass_user_type_set_user_type_by_name(CassUserType* user_type, 9317 const char* name, 9318 const CassUserType* value); 9319 9320 /** 9321 * Same as cass_user_type_set_user_type_by_name(), but with lengths for string 9322 * parameters. 9323 * 9324 * @cassandra{2.1+} 9325 * 9326 * @public @memberof CassUserType 9327 * 9328 * @param[in] user_type 9329 * @param[in] name 9330 * @param[in] name_length 9331 * @param[in] value 9332 * @return same as cass_user_type_set_user_type_by_name() 9333 * 9334 * @see cass_user_type_set_user_type_by_name() 9335 */ 9336 CASS_EXPORT CassError 9337 cass_user_type_set_user_type_by_name_n(CassUserType* user_type, 9338 const char* name, 9339 size_t name_length, 9340 const CassUserType* value); 9341 9342 /*********************************************************************************** 9343 * 9344 * Result 9345 * 9346 ***********************************************************************************/ 9347 9348 /** 9349 * Frees a result instance. 9350 * 9351 * This method invalidates all values, rows, and 9352 * iterators that were derived from this result. 9353 * 9354 * @public @memberof CassResult 9355 * 9356 * @param[in] result 9357 */ 9358 CASS_EXPORT void 9359 cass_result_free(const CassResult* result); 9360 9361 /** 9362 * Gets the number of rows for the specified result. 9363 * 9364 * @public @memberof CassResult 9365 * 9366 * @param[in] result 9367 * @return The number of rows in the result. 9368 */ 9369 CASS_EXPORT size_t 9370 cass_result_row_count(const CassResult* result); 9371 9372 /** 9373 * Gets the number of columns per row for the specified result. 9374 * 9375 * @public @memberof CassResult 9376 * 9377 * @param[in] result 9378 * @return The number of columns per row in the result. 9379 */ 9380 CASS_EXPORT size_t 9381 cass_result_column_count(const CassResult* result); 9382 9383 /** 9384 * Gets the column name at index for the specified result. 9385 * 9386 * @public @memberof CassResult 9387 * 9388 * @param[in] result 9389 * @param[in] index 9390 * @param[out] name The column name at the specified index. 9391 * @param[out] name_length 9392 * @return CASS_OK if successful, otherwise error occurred 9393 */ 9394 CASS_EXPORT CassError 9395 cass_result_column_name(const CassResult *result, 9396 size_t index, 9397 const char** name, 9398 size_t* name_length); 9399 9400 /** 9401 * Gets the column type at index for the specified result. 9402 * 9403 * @public @memberof CassResult 9404 * 9405 * @param[in] result 9406 * @param[in] index 9407 * @return The column type at the specified index. CASS_VALUE_TYPE_UNKNOWN 9408 * is returned if the index is out of bounds. 9409 */ 9410 CASS_EXPORT CassValueType 9411 cass_result_column_type(const CassResult* result, 9412 size_t index); 9413 9414 /** 9415 * Gets the column data type at index for the specified result. 9416 * 9417 * @public @memberof CassResult 9418 * 9419 * @param[in] result 9420 * @param[in] index 9421 * @return The column type at the specified index. NULL is returned if the 9422 * index is out of bounds. 9423 */ 9424 CASS_EXPORT const CassDataType* 9425 cass_result_column_data_type(const CassResult* result, size_t index); 9426 9427 /** 9428 * Gets the first row of the result. 9429 * 9430 * @public @memberof CassResult 9431 * 9432 * @param[in] result 9433 * @return The first row of the result. NULL if there are no rows. 9434 */ 9435 CASS_EXPORT const CassRow* 9436 cass_result_first_row(const CassResult* result); 9437 9438 /** 9439 * Returns true if there are more pages. 9440 * 9441 * @cassandra{2.0+} 9442 * 9443 * @public @memberof CassResult 9444 * 9445 * @param[in] result 9446 * @return cass_true if there are more pages 9447 */ 9448 CASS_EXPORT cass_bool_t 9449 cass_result_has_more_pages(const CassResult* result); 9450 9451 /** 9452 * Gets the raw paging state from the result. The paging state is bound to the 9453 * lifetime of the result object. If paging state needs to live beyond the 9454 * lifetime of the result object it must be copied. 9455 * 9456 * <b>Warning:</b> The paging state should not be exposed to or come from 9457 * untrusted environments. The paging state could be spoofed and potentially 9458 * used to gain access to other data. 9459 * 9460 * @cassandra{2.0+} 9461 * 9462 * @public @memberof CassResult 9463 * 9464 * @param[in] result 9465 * @param[out] paging_state 9466 * @param[out] paging_state_size 9467 * @return CASS_OK if successful, otherwise error occurred 9468 * 9469 * @see cass_statement_set_paging_state_token() 9470 */ 9471 CASS_EXPORT CassError 9472 cass_result_paging_state_token(const CassResult* result, 9473 const char** paging_state, 9474 size_t* paging_state_size); 9475 9476 /*********************************************************************************** 9477 * 9478 * Error result 9479 * 9480 ***********************************************************************************/ 9481 9482 /** 9483 * Frees an error result instance. 9484 * 9485 * @public @memberof CassErrorResult 9486 * 9487 * @param[in] error_result 9488 */ 9489 CASS_EXPORT void 9490 cass_error_result_free(const CassErrorResult* error_result); 9491 9492 /** 9493 * Gets error code for the error result. This error code will always 9494 * have an server error source. 9495 * 9496 * @public @memberof CassErrorResult 9497 * 9498 * @param[in] error_result 9499 * @return The server error code 9500 */ 9501 CASS_EXPORT CassError 9502 cass_error_result_code(const CassErrorResult* error_result); 9503 9504 /** 9505 * Gets consistency that triggered the error result of the 9506 * following types: 9507 * 9508 * <ul> 9509 * <li>CASS_ERROR_SERVER_READ_TIMEOUT</li> 9510 * <li>CASS_ERROR_SERVER_WRITE_TIMEOUT</li> 9511 * <li>CASS_ERROR_SERVER_READ_FAILURE</li> 9512 * <li>CASS_ERROR_SERVER_WRITE_FAILURE</li> 9513 * <li>CASS_ERROR_SERVER_UNAVAILABLE</li> 9514 * </ul> 9515 * 9516 * @public @memberof CassErrorResult 9517 * 9518 * @param[in] error_result 9519 * @return The consistency that triggered the error for a read timeout, 9520 * write timeout or an unavailable error result. Undefined for other 9521 * error result types. 9522 */ 9523 CASS_EXPORT CassConsistency 9524 cass_error_result_consistency(const CassErrorResult* error_result); 9525 9526 /** 9527 * Gets the actual number of received responses, received acknowledgments 9528 * or alive nodes for following error result types, respectively: 9529 * 9530 * <ul> 9531 * <li>CASS_ERROR_SERVER_READ_TIMEOUT</li> 9532 * <li>CASS_ERROR_SERVER_WRITE_TIMEOUT</li> 9533 * <li>CASS_ERROR_SERVER_READ_FAILURE</li> 9534 * <li>CASS_ERROR_SERVER_WRITE_FAILURE</li> 9535 * <li>CASS_ERROR_SERVER_UNAVAILABLE</li> 9536 * </ul> 9537 * 9538 * @public @memberof CassErrorResult 9539 * 9540 * @param[in] error_result 9541 * @return The actual received responses for a read timeout, actual received 9542 * acknowledgments for a write timeout or actual alive nodes for a unavailable 9543 * error. Undefined for other error result types. 9544 */ 9545 CASS_EXPORT cass_int32_t 9546 cass_error_result_responses_received(const CassErrorResult* error_result); 9547 9548 /** 9549 * Gets required responses, required acknowledgments or required alive nodes 9550 * needed to successfully complete the request for following error result types, 9551 * respectively: 9552 * 9553 * <ul> 9554 * <li>CASS_ERROR_SERVER_READ_TIMEOUT</li> 9555 * <li>CASS_ERROR_SERVER_WRITE_TIMEOUT</li> 9556 * <li>CASS_ERROR_SERVER_READ_FAILURE</li> 9557 * <li>CASS_ERROR_SERVER_WRITE_FAILURE</li> 9558 * <li>CASS_ERROR_SERVER_UNAVAILABLE</li> 9559 * </ul> 9560 * 9561 * @public @memberof CassErrorResult 9562 * 9563 * @param[in] error_result 9564 * @return The required responses for a read time, required acknowledgments 9565 * for a write timeout or required alive nodes for an unavailable error result. 9566 * Undefined for other error result types. 9567 */ 9568 CASS_EXPORT cass_int32_t 9569 cass_error_result_responses_required(const CassErrorResult* error_result); 9570 9571 /** 9572 * Gets the number of nodes that experienced failures for the following error types: 9573 * 9574 * <ul> 9575 * <li>CASS_ERROR_SERVER_READ_FAILURE</li> 9576 * <li>CASS_ERROR_SERVER_WRITE_FAILURE</li> 9577 * </ul> 9578 * 9579 * @public @memberof CassErrorResult 9580 * 9581 * @param[in] error_result 9582 * @return The number of nodes that failed during a read or write request. 9583 */ 9584 CASS_EXPORT cass_int32_t 9585 cass_error_result_num_failures(const CassErrorResult* error_result); 9586 9587 /** 9588 * Determines whether the actual data was present in the responses from the 9589 * replicas for the following error result types: 9590 * 9591 * <ul> 9592 * <li>CASS_ERROR_SERVER_READ_TIMEOUT</li> 9593 * <li>CASS_ERROR_SERVER_READ_FAILURE</li> 9594 * </ul> 9595 * 9596 * @public @memberof CassErrorResult 9597 * 9598 * @param[in] error_result 9599 * @return cass_true if the data was present in the received responses when the 9600 * read timeout occurred. Undefined for other error result types. 9601 */ 9602 CASS_EXPORT cass_bool_t 9603 cass_error_result_data_present(const CassErrorResult* error_result); 9604 9605 /** 9606 * Gets the write type of a request for the following error result types: 9607 * 9608 * <ul> 9609 * <li>CASS_ERROR_SERVER_WRITE_TIMEOUT</li> 9610 * <li>CASS_ERROR_SERVER_WRITE_FAILURE</li> 9611 * </ul> 9612 * 9613 * @public @memberof CassErrorResult 9614 * 9615 * @param[in] error_result 9616 * @return The type of the write that timed out. Undefined for 9617 * other error result types. 9618 */ 9619 CASS_EXPORT CassWriteType 9620 cass_error_result_write_type(const CassErrorResult* error_result); 9621 9622 /** 9623 * Gets the affected keyspace for the following error result types: 9624 * 9625 * <ul> 9626 * <li>CASS_ERROR_SERVER_ALREADY_EXISTS</li> 9627 * <li>CASS_ERROR_SERVER_FUNCTION_FAILURE</li> 9628 * </ul> 9629 * 9630 * @public @memberof CassErrorResult 9631 * 9632 * @param[in] error_result 9633 * @param[out] keyspace 9634 * @param[out] keyspace_length 9635 * @return CASS_OK if successful, otherwise error occurred 9636 */ 9637 CASS_EXPORT CassError 9638 cass_error_result_keyspace(const CassErrorResult* error_result, 9639 const char** keyspace, 9640 size_t* keyspace_length); 9641 9642 /** 9643 * Gets the affected table for the already exists error 9644 * (CASS_ERROR_SERVER_ALREADY_EXISTS) result type. 9645 * 9646 * @public @memberof CassErrorResult 9647 * 9648 * @param[in] error_result 9649 * @param[out] table 9650 * @param[out] table_length 9651 * @return CASS_OK if successful, otherwise error occurred 9652 */ 9653 CASS_EXPORT CassError 9654 cass_error_result_table(const CassErrorResult* error_result, 9655 const char** table, 9656 size_t* table_length); 9657 9658 /** 9659 * Gets the affected function for the function failure error 9660 * (CASS_ERROR_SERVER_FUNCTION_FAILURE) result type. 9661 * 9662 * @cassandra{2.2+} 9663 * 9664 * @public @memberof CassErrorResult 9665 * 9666 * @param[in] error_result 9667 * @param[out] function 9668 * @param[out] function_length 9669 * @return CASS_OK if successful, otherwise error occurred 9670 */ 9671 CASS_EXPORT CassError 9672 cass_error_result_function(const CassErrorResult* error_result, 9673 const char** function, 9674 size_t* function_length); 9675 9676 /** 9677 * Gets the number of argument types for the function failure error 9678 * (CASS_ERROR_SERVER_FUNCTION_FAILURE) result type. 9679 * 9680 * @cassandra{2.2+} 9681 * 9682 * @public @memberof CassErrorResult 9683 * 9684 * @param[in] error_result 9685 * @return The number of arguments for the affected function. 9686 */ 9687 CASS_EXPORT size_t 9688 cass_error_num_arg_types(const CassErrorResult* error_result); 9689 9690 /** 9691 * Gets the argument type at the specified index for the function failure 9692 * error (CASS_ERROR_SERVER_FUNCTION_FAILURE) result type. 9693 * 9694 * @cassandra{2.2+} 9695 * 9696 * @public @memberof CassErrorResult 9697 * 9698 * @param[in] error_result 9699 * @param[in] index 9700 * @param[out] arg_type 9701 * @param[out] arg_type_length 9702 * @return CASS_OK if successful, otherwise error occurred 9703 */ 9704 CASS_EXPORT CassError 9705 cass_error_result_arg_type(const CassErrorResult* error_result, 9706 size_t index, 9707 const char** arg_type, 9708 size_t* arg_type_length); 9709 9710 /*********************************************************************************** 9711 * 9712 * Iterator 9713 * 9714 ***********************************************************************************/ 9715 9716 /** 9717 * Frees an iterator instance. 9718 * 9719 * @public @memberof CassIterator 9720 * 9721 * @param[in] iterator 9722 */ 9723 CASS_EXPORT void 9724 cass_iterator_free(CassIterator* iterator); 9725 9726 /** 9727 * Gets the type of the specified iterator. 9728 * 9729 * @public @memberof CassIterator 9730 * 9731 * @param[in] iterator 9732 * @return The type of the iterator. 9733 */ 9734 CASS_EXPORT CassIteratorType 9735 cass_iterator_type(CassIterator* iterator); 9736 9737 /** 9738 * Creates a new iterator for the specified result. This can be 9739 * used to iterate over rows in the result. 9740 * 9741 * @public @memberof CassResult 9742 * 9743 * @param[in] result 9744 * @return A new iterator that must be freed. 9745 * 9746 * @see cass_iterator_free() 9747 */ 9748 CASS_EXPORT CassIterator* 9749 cass_iterator_from_result(const CassResult* result); 9750 9751 /** 9752 * Creates a new iterator for the specified row. This can be 9753 * used to iterate over columns in a row. 9754 * 9755 * @public @memberof CassRow 9756 * 9757 * @param[in] row 9758 * @return A new iterator that must be freed. 9759 * 9760 * @see cass_iterator_free() 9761 */ 9762 CASS_EXPORT CassIterator* 9763 cass_iterator_from_row(const CassRow* row); 9764 9765 /** 9766 * Creates a new iterator for the specified collection. This can be 9767 * used to iterate over values in a collection. 9768 * 9769 * @public @memberof CassValue 9770 * 9771 * @param[in] value 9772 * @return A new iterator that must be freed. NULL returned if the 9773 * value is not a collection. 9774 * 9775 * @see cass_iterator_free() 9776 */ 9777 CASS_EXPORT CassIterator* 9778 cass_iterator_from_collection(const CassValue* value); 9779 9780 /** 9781 * Creates a new iterator for the specified map. This can be 9782 * used to iterate over key/value pairs in a map. 9783 * 9784 * @public @memberof CassValue 9785 * 9786 * @param[in] value 9787 * @return A new iterator that must be freed. NULL returned if the 9788 * value is not a map. 9789 * 9790 * @see cass_iterator_free() 9791 */ 9792 CASS_EXPORT CassIterator* 9793 cass_iterator_from_map(const CassValue* value); 9794 9795 /** 9796 * Creates a new iterator for the specified tuple. This can be 9797 * used to iterate over values in a tuple. 9798 * 9799 * @cassandra{2.1+} 9800 * 9801 * @public @memberof CassValue 9802 * 9803 * @param[in] value 9804 * @return A new iterator that must be freed. NULL returned if the 9805 * value is not a tuple. 9806 * 9807 * @see cass_iterator_free() 9808 */ 9809 CASS_EXPORT CassIterator* 9810 cass_iterator_from_tuple(const CassValue* value); 9811 9812 /** 9813 * Creates a new iterator for the specified user defined type. This can be 9814 * used to iterate over fields in a user defined type. 9815 * 9816 * @cassandra{2.1+} 9817 * 9818 * @public @memberof CassValue 9819 * 9820 * @param[in] value 9821 * @return A new iterator that must be freed. NULL returned if the 9822 * value is not a user defined type. 9823 * 9824 * @see cass_iterator_free() 9825 */ 9826 CASS_EXPORT CassIterator* 9827 cass_iterator_fields_from_user_type(const CassValue* value); 9828 9829 /** 9830 * Creates a new iterator for the specified schema metadata. 9831 * This can be used to iterate over keyspace. 9832 * 9833 * @public @memberof CassSchemaMeta 9834 * 9835 * @param[in] schema_meta 9836 * @return A new iterator that must be freed. 9837 * 9838 * @see cass_iterator_get_keyspace_meta() 9839 * @see cass_iterator_free() 9840 */ 9841 CASS_EXPORT CassIterator* 9842 cass_iterator_keyspaces_from_schema_meta(const CassSchemaMeta* schema_meta); 9843 9844 /** 9845 * Creates a new iterator for the specified keyspace metadata. 9846 * This can be used to iterate over tables. 9847 * 9848 * @public @memberof CassKeyspaceMeta 9849 * 9850 * @param[in] keyspace_meta 9851 * @return A new iterator that must be freed. 9852 * 9853 * @see cass_iterator_get_table_meta() 9854 * @see cass_iterator_free() 9855 */ 9856 CASS_EXPORT CassIterator* 9857 cass_iterator_tables_from_keyspace_meta(const CassKeyspaceMeta* keyspace_meta); 9858 9859 /** 9860 * Creates a new iterator for the specified keyspace metadata. 9861 * This can be used to iterate over views. 9862 * 9863 * @cassandra{3.0+} 9864 * 9865 * @public @memberof CassKeyspaceMeta 9866 * 9867 * @param[in] keyspace_meta 9868 * @return A new iterator that must be freed. 9869 * 9870 * @see cass_iterator_get_materialized_view_meta() 9871 * @see cass_iterator_free() 9872 */ 9873 CASS_EXPORT CassIterator* 9874 cass_iterator_materialized_views_from_keyspace_meta(const CassKeyspaceMeta* keyspace_meta); 9875 9876 /** 9877 * Creates a new iterator for the specified keyspace metadata. 9878 * This can be used to iterate over types. 9879 * 9880 * @cassandra{2.1+} 9881 * 9882 * @public @memberof CassKeyspaceMeta 9883 * 9884 * @param[in] keyspace_meta 9885 * @return A new iterator that must be freed. 9886 * 9887 * @see cass_iterator_get_user_type() 9888 * @see cass_iterator_free() 9889 */ 9890 CASS_EXPORT CassIterator* 9891 cass_iterator_user_types_from_keyspace_meta(const CassKeyspaceMeta* keyspace_meta); 9892 9893 /** 9894 * Creates a new iterator for the specified keyspace metadata. 9895 * This can be used to iterate over functions. 9896 * 9897 * @cassandra{2.2+} 9898 * 9899 * @public @memberof CassKeyspaceMeta 9900 * 9901 * @param[in] keyspace_meta 9902 * @return A new iterator that must be freed. 9903 * 9904 * @see cass_iterator_get_function_meta() 9905 * @see cass_iterator_free() 9906 */ 9907 CASS_EXPORT CassIterator* 9908 cass_iterator_functions_from_keyspace_meta(const CassKeyspaceMeta* keyspace_meta); 9909 9910 /** 9911 * Creates a new iterator for the specified keyspace metadata. 9912 * This can be used to iterate over aggregates. 9913 * 9914 * @cassandra{2.2+} 9915 * 9916 * @public @memberof CassKeyspaceMeta 9917 * 9918 * @param[in] keyspace_meta 9919 * @return A new iterator that must be freed. 9920 * 9921 * @see cass_iterator_get_aggregate_meta() 9922 * @see cass_iterator_free() 9923 */ 9924 CASS_EXPORT CassIterator* 9925 cass_iterator_aggregates_from_keyspace_meta(const CassKeyspaceMeta* keyspace_meta); 9926 9927 /** 9928 * Creates a new fields iterator for the specified keyspace metadata. Metadata 9929 * fields allow direct access to the column data found in the underlying 9930 * "keyspaces" metadata table. This can be used to iterate those metadata 9931 * field entries. 9932 * 9933 * @public @memberof CassKeyspaceMeta 9934 * 9935 * @param[in] keyspace_meta 9936 * @return A new iterator that must be freed. 9937 * 9938 * @see cass_iterator_get_meta_field_name() 9939 * @see cass_iterator_get_meta_field_value() 9940 * @see cass_iterator_free() 9941 */ 9942 CASS_EXPORT CassIterator* 9943 cass_iterator_fields_from_keyspace_meta(const CassKeyspaceMeta* keyspace_meta); 9944 9945 /** 9946 * Creates a new iterator for the specified table metadata. 9947 * This can be used to iterate over columns. 9948 * 9949 * @public @memberof CassTableMeta 9950 * 9951 * @param[in] table_meta 9952 * @return A new iterator that must be freed. 9953 * 9954 * @see cass_iterator_get_column_meta() 9955 * @see cass_iterator_free() 9956 */ 9957 CASS_EXPORT CassIterator* 9958 cass_iterator_columns_from_table_meta(const CassTableMeta* table_meta); 9959 9960 /** 9961 * Creates a new iterator for the specified table metadata. 9962 * This can be used to iterate over indexes. 9963 * 9964 * @public @memberof CassTableMeta 9965 * 9966 * @param[in] table_meta 9967 * @return A new iterator that must be freed. 9968 * 9969 * @see cass_iterator_get_index_meta() 9970 * @see cass_iterator_free() 9971 */ 9972 CASS_EXPORT CassIterator* 9973 cass_iterator_indexes_from_table_meta(const CassTableMeta* table_meta); 9974 9975 /** 9976 * Creates a new iterator for the specified materialized view metadata. 9977 * This can be used to iterate over columns. 9978 * 9979 * @cassandra{3.0+} 9980 * 9981 * @public @memberof CassTableMeta 9982 * 9983 * @param[in] table_meta 9984 * @return A new iterator that must be freed. 9985 * 9986 * @see cass_iterator_get_materialized_view_meta() 9987 * @see cass_iterator_free() 9988 */ 9989 CASS_EXPORT CassIterator* 9990 cass_iterator_materialized_views_from_table_meta(const CassTableMeta* table_meta); 9991 9992 /** 9993 * Creates a new fields iterator for the specified table metadata. Metadata 9994 * fields allow direct access to the column data found in the underlying 9995 * "tables" metadata table. This can be used to iterate those metadata 9996 * field entries. 9997 * 9998 * @public @memberof CassTableMeta 9999 * 10000 * @param[in] table_meta 10001 * @return A new iterator that must be freed. 10002 * 10003 * @see cass_iterator_get_meta_field_name() 10004 * @see cass_iterator_get_meta_field_value() 10005 * @see cass_iterator_free() 10006 */ 10007 CASS_EXPORT CassIterator* 10008 cass_iterator_fields_from_table_meta(const CassTableMeta* table_meta); 10009 10010 /** 10011 * Creates a new iterator for the specified materialized view metadata. 10012 * This can be used to iterate over columns. 10013 * 10014 * @cassandra{3.0+} 10015 * 10016 * @public @memberof CassMaterializedViewMeta 10017 * 10018 * @param[in] view_meta 10019 * @return A new iterator that must be freed. 10020 * 10021 * @see cass_iterator_get_column_meta() 10022 * @see cass_iterator_free() 10023 */ 10024 CASS_EXPORT CassIterator* 10025 cass_iterator_columns_from_materialized_view_meta(const CassMaterializedViewMeta* view_meta); 10026 10027 /** 10028 * Creates a new fields iterator for the specified materialized view metadata. 10029 * Metadata fields allow direct access to the column data found in the 10030 * underlying "views" metadata view. This can be used to iterate those metadata 10031 * field entries. 10032 * 10033 * @cassandra{3.0+} 10034 * 10035 * @public @memberof CassMaterializedViewMeta 10036 * 10037 * @param[in] view_meta 10038 * @return A new iterator that must be freed. 10039 * 10040 * @see cass_iterator_get_meta_field_name() 10041 * @see cass_iterator_get_meta_field_value() 10042 * @see cass_iterator_free() 10043 */ 10044 CASS_EXPORT CassIterator* 10045 cass_iterator_fields_from_materialized_view_meta(const CassMaterializedViewMeta* view_meta); 10046 10047 /** 10048 * Creates a new fields iterator for the specified column metadata. Metadata 10049 * fields allow direct access to the column data found in the underlying 10050 * "columns" metadata table. This can be used to iterate those metadata 10051 * field entries. 10052 * 10053 * @public @memberof CassColumnMeta 10054 * 10055 * @param[in] column_meta 10056 * @return A new iterator that must be freed. 10057 * 10058 * @see cass_iterator_get_meta_field_name() 10059 * @see cass_iterator_get_meta_field_value() 10060 * @see cass_iterator_free() 10061 */ 10062 CASS_EXPORT CassIterator* 10063 cass_iterator_fields_from_column_meta(const CassColumnMeta* column_meta); 10064 10065 /** 10066 * Creates a new fields iterator for the specified index metadata. Metadata 10067 * fields allow direct access to the index data found in the underlying 10068 * "indexes" metadata table. This can be used to iterate those metadata 10069 * field entries. 10070 * 10071 * @public @memberof CassIndexMeta 10072 * 10073 * @param[in] index_meta 10074 * @return A new iterator that must be freed. 10075 * 10076 * @see cass_iterator_get_meta_field_name() 10077 * @see cass_iterator_get_meta_field_value() 10078 * @see cass_iterator_free() 10079 */ 10080 CASS_EXPORT CassIterator* 10081 cass_iterator_fields_from_index_meta(const CassIndexMeta* index_meta); 10082 10083 /** 10084 * Creates a new fields iterator for the specified function metadata. Metadata 10085 * fields allow direct access to the column data found in the underlying 10086 * "functions" metadata table. This can be used to iterate those metadata 10087 * field entries. 10088 * 10089 * @cassandra{2.2+} 10090 * 10091 * @public @memberof CassFunctionMeta 10092 * 10093 * @param[in] function_meta 10094 * @return A new iterator that must be freed. 10095 * 10096 * @see cass_iterator_get_meta_field() 10097 * @see cass_iterator_free() 10098 */ 10099 CASS_EXPORT CassIterator* 10100 cass_iterator_fields_from_function_meta(const CassFunctionMeta* function_meta); 10101 10102 /** 10103 * Creates a new fields iterator for the specified aggregate metadata. Metadata 10104 * fields allow direct access to the column data found in the underlying 10105 * "aggregates" metadata table. This can be used to iterate those metadata 10106 * field entries. 10107 * 10108 * @cassandra{2.2+} 10109 * 10110 * @public @memberof CassAggregateMeta 10111 * 10112 * @param[in] aggregate_meta 10113 * @return A new iterator that must be freed. 10114 * 10115 * @see cass_iterator_get_meta_field() 10116 * @see cass_iterator_free() 10117 */ 10118 CASS_EXPORT CassIterator* 10119 cass_iterator_fields_from_aggregate_meta(const CassAggregateMeta* aggregate_meta); 10120 10121 /** 10122 * Advance the iterator to the next row, column or collection item. 10123 * 10124 * @public @memberof CassIterator 10125 * 10126 * @param[in] iterator 10127 * @return false if no more rows, columns or items, otherwise true 10128 */ 10129 CASS_EXPORT cass_bool_t 10130 cass_iterator_next(CassIterator* iterator); 10131 10132 /** 10133 * Gets the row at the result iterator's current position. 10134 * 10135 * Calling cass_iterator_next() will invalidate the previous 10136 * row returned by this method. 10137 * 10138 * @public @memberof CassIterator 10139 * 10140 * @param[in] iterator 10141 * @return A row 10142 */ 10143 CASS_EXPORT const CassRow* 10144 cass_iterator_get_row(const CassIterator* iterator); 10145 10146 /** 10147 * Gets the column value at the row iterator's current position. 10148 * 10149 * Calling cass_iterator_next() will invalidate the previous 10150 * column returned by this method. 10151 * 10152 * @public @memberof CassIterator 10153 * 10154 * @param[in] iterator 10155 * @return A value 10156 */ 10157 CASS_EXPORT const CassValue* 10158 cass_iterator_get_column(const CassIterator* iterator); 10159 10160 /** 10161 * Gets the value at a collection or tuple iterator's current position. 10162 * 10163 * Calling cass_iterator_next() will invalidate the previous 10164 * value returned by this method. 10165 * 10166 * @public @memberof CassIterator 10167 * 10168 * @param[in] iterator 10169 * @return A value 10170 */ 10171 CASS_EXPORT const CassValue* 10172 cass_iterator_get_value(const CassIterator* iterator); 10173 10174 /** 10175 * Gets the key at the map iterator's current position. 10176 * 10177 * Calling cass_iterator_next() will invalidate the previous 10178 * value returned by this method. 10179 * 10180 * @public @memberof CassIterator 10181 * 10182 * @param[in] iterator 10183 * @return A value 10184 */ 10185 CASS_EXPORT const CassValue* 10186 cass_iterator_get_map_key(const CassIterator* iterator); 10187 10188 10189 /** 10190 * Gets the value at the map iterator's current position. 10191 * 10192 * Calling cass_iterator_next() will invalidate the previous 10193 * value returned by this method. 10194 * 10195 * @public @memberof CassIterator 10196 * 10197 * @param[in] iterator 10198 * @return A value 10199 */ 10200 CASS_EXPORT const CassValue* 10201 cass_iterator_get_map_value(const CassIterator* iterator); 10202 10203 /** 10204 * Gets the field name at the user type defined iterator's current position. 10205 * 10206 * Calling cass_iterator_next() will invalidate the previous 10207 * name returned by this method. 10208 * 10209 * @cassandra{2.1+} 10210 * 10211 * @public @memberof CassIterator 10212 * 10213 * @param[in] iterator 10214 * @param[out] name 10215 * @param[out] name_length 10216 * @return CASS_OK if successful, otherwise error occurred 10217 */ 10218 CASS_EXPORT CassError 10219 cass_iterator_get_user_type_field_name(const CassIterator* iterator, 10220 const char** name, 10221 size_t* name_length); 10222 10223 /** 10224 * Gets the field value at the user type defined iterator's current position. 10225 * 10226 * Calling cass_iterator_next() will invalidate the previous 10227 * value returned by this method. 10228 * 10229 * @cassandra{2.1+} 10230 * 10231 * @public @memberof CassIterator 10232 * 10233 * @param[in] iterator 10234 * @return A value 10235 */ 10236 CASS_EXPORT const CassValue* 10237 cass_iterator_get_user_type_field_value(const CassIterator* iterator); 10238 10239 /** 10240 * Gets the keyspace metadata entry at the iterator's current position. 10241 * 10242 * Calling cass_iterator_next() will invalidate the previous 10243 * value returned by this method. 10244 * 10245 * @public @memberof CassIterator 10246 * 10247 * @param[in] iterator 10248 * @return A keyspace metadata entry 10249 */ 10250 CASS_EXPORT const CassKeyspaceMeta* 10251 cass_iterator_get_keyspace_meta(const CassIterator* iterator); 10252 10253 /** 10254 * Gets the table metadata entry at the iterator's current position. 10255 * 10256 * Calling cass_iterator_next() will invalidate the previous 10257 * value returned by this method. 10258 * 10259 * @public @memberof CassIterator 10260 * 10261 * @param[in] iterator 10262 * @return A table metadata entry 10263 */ 10264 CASS_EXPORT const CassTableMeta* 10265 cass_iterator_get_table_meta(const CassIterator* iterator); 10266 10267 /** 10268 * Gets the materialized view metadata entry at the iterator's current position. 10269 * 10270 * Calling cass_iterator_next() will invalidate the previous 10271 * value returned by this method. 10272 * 10273 * @cassandra{3.0+} 10274 * 10275 * @public @memberof CassIterator 10276 * 10277 * @param[in] iterator 10278 * @return A materialized view metadata entry 10279 */ 10280 CASS_EXPORT const CassMaterializedViewMeta* 10281 cass_iterator_get_materialized_view_meta(const CassIterator* iterator); 10282 10283 /** 10284 * Gets the type metadata entry at the iterator's current position. 10285 * 10286 * Calling cass_iterator_next() will invalidate the previous 10287 * value returned by this method. 10288 * 10289 * @cassandra{2.1+} 10290 * 10291 * @public @memberof CassIterator 10292 * 10293 * @param[in] iterator 10294 * @return A type metadata entry 10295 */ 10296 CASS_EXPORT const CassDataType* 10297 cass_iterator_get_user_type(const CassIterator* iterator); 10298 10299 /** 10300 * Gets the function metadata entry at the iterator's current position. 10301 * 10302 * Calling cass_iterator_next() will invalidate the previous 10303 * value returned by this method. 10304 * 10305 * @cassandra{2.2+} 10306 * 10307 * @public @memberof CassIterator 10308 * 10309 * @param[in] iterator 10310 * @return A function metadata entry 10311 */ 10312 CASS_EXPORT const CassFunctionMeta* 10313 cass_iterator_get_function_meta(const CassIterator* iterator); 10314 10315 /** 10316 * Gets the aggregate metadata entry at the iterator's current position. 10317 * 10318 * Calling cass_iterator_next() will invalidate the previous 10319 * value returned by this method. 10320 * 10321 * @cassandra{2.2+} 10322 * 10323 * @public @memberof CassIterator 10324 * 10325 * @param[in] iterator 10326 * @return A aggregate metadata entry 10327 */ 10328 CASS_EXPORT const CassAggregateMeta* 10329 cass_iterator_get_aggregate_meta(const CassIterator* iterator); 10330 10331 /** 10332 * Gets the column metadata entry at the iterator's current position. 10333 * 10334 * Calling cass_iterator_next() will invalidate the previous 10335 * value returned by this method. 10336 * 10337 * @public @memberof CassIterator 10338 * 10339 * @param[in] iterator 10340 * @return A column metadata entry 10341 */ 10342 CASS_EXPORT const CassColumnMeta* 10343 cass_iterator_get_column_meta(const CassIterator* iterator); 10344 10345 /** 10346 * Gets the index metadata entry at the iterator's current position. 10347 * 10348 * Calling cass_iterator_next() will invalidate the previous 10349 * value returned by this method. 10350 * 10351 * @public @memberof CassIterator 10352 * 10353 * @param[in] iterator 10354 * @return A index metadata entry 10355 */ 10356 CASS_EXPORT const CassIndexMeta* 10357 cass_iterator_get_index_meta(const CassIterator* iterator); 10358 10359 /** 10360 * Gets the metadata field name at the iterator's current position. 10361 * 10362 * Calling cass_iterator_next() will invalidate the previous 10363 * value returned by this method. 10364 * 10365 * @public @memberof CassIterator 10366 * 10367 * @param[in] iterator 10368 * @param[out] name 10369 * @param[out] name_length 10370 * @return CASS_OK if successful, otherwise error occurred 10371 */ 10372 CASS_EXPORT CassError 10373 cass_iterator_get_meta_field_name(const CassIterator* iterator, 10374 const char** name, 10375 size_t* name_length); 10376 10377 /** 10378 * Gets the metadata field value at the iterator's current position. 10379 * 10380 * Calling cass_iterator_next() will invalidate the previous 10381 * value returned by this method. 10382 * 10383 * @public @memberof CassIterator 10384 * 10385 * @param[in] iterator 10386 * @return A metadata field value 10387 */ 10388 CASS_EXPORT const CassValue* 10389 cass_iterator_get_meta_field_value(const CassIterator* iterator); 10390 10391 /*********************************************************************************** 10392 * 10393 * Row 10394 * 10395 ***********************************************************************************/ 10396 10397 /** 10398 * Get the column value at index for the specified row. 10399 * 10400 * @public @memberof CassRow 10401 * 10402 * @param[in] row 10403 * @param[in] index 10404 * @return The column value at the specified index. NULL is 10405 * returned if the index is out of bounds. 10406 */ 10407 CASS_EXPORT const CassValue* 10408 cass_row_get_column(const CassRow* row, 10409 size_t index); 10410 10411 10412 /** 10413 * Get the column value by name for the specified row. 10414 * 10415 * @public @memberof CassRow 10416 * 10417 * @param[in] row 10418 * @param[in] name 10419 * @return The column value for the specified name. NULL is 10420 * returned if the column does not exist. 10421 */ 10422 CASS_EXPORT const CassValue* 10423 cass_row_get_column_by_name(const CassRow* row, 10424 const char* name); 10425 10426 /** 10427 * Same as cass_row_get_column_by_name(), but with lengths for string 10428 * parameters. 10429 * 10430 * @public @memberof CassRow 10431 * 10432 * @param[in] row 10433 * @param[in] name 10434 * @param[in] name_length 10435 * @return same as cass_row_get_column_by_name() 10436 * 10437 * @see cass_row_get_column_by_name() 10438 */ 10439 CASS_EXPORT const CassValue* 10440 cass_row_get_column_by_name_n(const CassRow* row, 10441 const char* name, 10442 size_t name_length); 10443 10444 /*********************************************************************************** 10445 * 10446 * Value 10447 * 10448 ***********************************************************************************/ 10449 10450 /** 10451 * Gets the data type of a value. 10452 * 10453 * @public @memberof CassValue 10454 * 10455 * @param[in] value 10456 * @return Returns a reference to the data type of the value. 10457 * Do not free this reference as it is bound to the lifetime of the value. 10458 */ 10459 CASS_EXPORT const CassDataType* 10460 cass_value_data_type(const CassValue* value); 10461 10462 /** 10463 * Gets an int8 for the specified value. 10464 * 10465 * @cassandra{2.2+} 10466 * 10467 * @public @memberof CassValue 10468 * 10469 * @param[in] value 10470 * @param[out] output 10471 * @return CASS_OK if successful, otherwise error occurred 10472 */ 10473 CASS_EXPORT CassError 10474 cass_value_get_int8(const CassValue* value, 10475 cass_int8_t* output); 10476 10477 /** 10478 * Gets an int16 for the specified value. 10479 * 10480 * @cassandra{2.2+} 10481 * 10482 * @public @memberof CassValue 10483 * 10484 * @param[in] value 10485 * @param[out] output 10486 * @return CASS_OK if successful, otherwise error occurred 10487 */ 10488 CASS_EXPORT CassError 10489 cass_value_get_int16(const CassValue* value, 10490 cass_int16_t* output); 10491 10492 /** 10493 * Gets an int32 for the specified value. 10494 * 10495 * @public @memberof CassValue 10496 * 10497 * @param[in] value 10498 * @param[out] output 10499 * @return CASS_OK if successful, otherwise error occurred 10500 */ 10501 CASS_EXPORT CassError 10502 cass_value_get_int32(const CassValue* value, 10503 cass_int32_t* output); 10504 10505 /** 10506 * Gets an uint32 for the specified value. 10507 * 10508 * @cassandra{2.2+} 10509 * 10510 * @public @memberof CassValue 10511 * 10512 * @param[in] value 10513 * @param[out] output 10514 * @return CASS_OK if successful, otherwise error occurred 10515 */ 10516 CASS_EXPORT CassError 10517 cass_value_get_uint32(const CassValue* value, 10518 cass_uint32_t* output); 10519 10520 /** 10521 * Gets an int64 for the specified value. 10522 * 10523 * @public @memberof CassValue 10524 * 10525 * @param[in] value 10526 * @param[out] output 10527 * @return CASS_OK if successful, otherwise error occurred 10528 */ 10529 CASS_EXPORT CassError 10530 cass_value_get_int64(const CassValue* value, 10531 cass_int64_t* output); 10532 10533 /** 10534 * Gets a float for the specified value. 10535 * 10536 * @public @memberof CassValue 10537 * 10538 * @param[in] value 10539 * @param[out] output 10540 * @return CASS_OK if successful, otherwise error occurred 10541 */ 10542 CASS_EXPORT CassError 10543 cass_value_get_float(const CassValue* value, 10544 cass_float_t* output); 10545 10546 /** 10547 * Gets a double for the specified value. 10548 * 10549 * @public @memberof CassValue 10550 * 10551 * @param[in] value 10552 * @param[out] output 10553 * @return CASS_OK if successful, otherwise error occurred 10554 */ 10555 CASS_EXPORT CassError 10556 cass_value_get_double(const CassValue* value, 10557 cass_double_t* output); 10558 10559 /** 10560 * Gets a bool for the specified value. 10561 * 10562 * @public @memberof CassValue 10563 * 10564 * @param[in] value 10565 * @param[out] output 10566 * @return CASS_OK if successful, otherwise error occurred 10567 */ 10568 CASS_EXPORT CassError 10569 cass_value_get_bool(const CassValue* value, 10570 cass_bool_t* output); 10571 10572 /** 10573 * Gets a UUID for the specified value. 10574 * 10575 * @public @memberof CassValue 10576 * 10577 * @param[in] value 10578 * @param[out] output 10579 * @return CASS_OK if successful, otherwise error occurred 10580 */ 10581 CASS_EXPORT CassError 10582 cass_value_get_uuid(const CassValue* value, 10583 CassUuid* output); 10584 10585 /** 10586 * Gets an INET for the specified value. 10587 * 10588 * @public @memberof CassValue 10589 * 10590 * @param[in] value 10591 * @param[out] output 10592 * @return CASS_OK if successful, otherwise error occurred 10593 */ 10594 CASS_EXPORT CassError 10595 cass_value_get_inet(const CassValue* value, 10596 CassInet* output); 10597 10598 /** 10599 * Gets a string for the specified value. 10600 * 10601 * @public @memberof CassValue 10602 * 10603 * @param[in] value 10604 * @param[out] output 10605 * @param[out] output_size 10606 * @return CASS_OK if successful, otherwise error occurred 10607 */ 10608 CASS_EXPORT CassError 10609 cass_value_get_string(const CassValue* value, 10610 const char** output, 10611 size_t* output_size); 10612 10613 /** 10614 * Gets the bytes of the specified value. 10615 * 10616 * @public @memberof CassValue 10617 * 10618 * @param[in] value 10619 * @param[out] output 10620 * @param[out] output_size 10621 * @return CASS_OK if successful, otherwise error occurred 10622 */ 10623 CASS_EXPORT CassError 10624 cass_value_get_bytes(const CassValue* value, 10625 const cass_byte_t** output, 10626 size_t* output_size); 10627 10628 /** 10629 * Gets a decimal for the specified value. 10630 * 10631 * @public @memberof CassValue 10632 * 10633 * @param[in] value 10634 * @param[out] varint 10635 * @param[out] varint_size 10636 * @param[out] scale 10637 * @return CASS_OK if successful, otherwise error occurred 10638 */ 10639 CASS_EXPORT CassError 10640 cass_value_get_decimal(const CassValue* value, 10641 const cass_byte_t** varint, 10642 size_t* varint_size, 10643 cass_int32_t* scale); 10644 10645 /** 10646 * Gets a duration for the specified value. 10647 * 10648 * @cassandra{3.10+} 10649 * 10650 * @public @memberof CassValue 10651 * 10652 * @param[in] value 10653 * @param[out] months 10654 * @param[out] days 10655 * @param[out] nanos 10656 * @return CASS_OK if successful, otherwise error occurred 10657 */ 10658 CASS_EXPORT CassError 10659 cass_value_get_duration(const CassValue* value, 10660 cass_int32_t* months, 10661 cass_int32_t* days, 10662 cass_int64_t* nanos); 10663 10664 /** 10665 * Gets the type of the specified value. 10666 * 10667 * @public @memberof CassValue 10668 * 10669 * @param[in] value 10670 * @return The type of the specified value. 10671 */ 10672 CASS_EXPORT CassValueType 10673 cass_value_type(const CassValue* value); 10674 10675 /** 10676 * Returns true if a specified value is null. 10677 * 10678 * @public @memberof CassValue 10679 * 10680 * @param[in] value 10681 * @return true if the value is null, otherwise false. 10682 */ 10683 CASS_EXPORT cass_bool_t 10684 cass_value_is_null(const CassValue* value); 10685 10686 /** 10687 * Returns true if a specified value is a collection. 10688 * 10689 * @public @memberof CassValue 10690 * 10691 * @param[in] value 10692 * @return true if the value is a collection, otherwise false. 10693 */ 10694 CASS_EXPORT cass_bool_t 10695 cass_value_is_collection(const CassValue* value); 10696 10697 /** 10698 * Returns true if a specified value is a duration. 10699 * 10700 * @public @memberof CassValue 10701 * 10702 * @param[in] value 10703 * @return true if the value is a duration, otherwise false. 10704 */ 10705 CASS_EXPORT cass_bool_t 10706 cass_value_is_duration(const CassValue* value); 10707 10708 /** 10709 * Get the number of items in a collection. Works for all collection types. 10710 * 10711 * @public @memberof CassValue 10712 * 10713 * @param[in] collection 10714 * @return Count of items in a collection. 0 if not a collection. 10715 */ 10716 CASS_EXPORT size_t 10717 cass_value_item_count(const CassValue* collection); 10718 10719 /** 10720 * Get the primary sub-type for a collection. This returns the sub-type for a 10721 * list or set and the key type for a map. 10722 * 10723 * @public @memberof CassValue 10724 * 10725 * @param[in] collection 10726 * @return The type of the primary sub-type. CASS_VALUE_TYPE_UNKNOWN 10727 * returned if not a collection. 10728 */ 10729 CASS_EXPORT CassValueType 10730 cass_value_primary_sub_type(const CassValue* collection); 10731 10732 /** 10733 * Get the secondary sub-type for a collection. This returns the value type for a 10734 * map. 10735 * 10736 * @public @memberof CassValue 10737 * 10738 * @param[in] collection 10739 * @return The type of the primary sub-type. CASS_VALUE_TYPE_UNKNOWN 10740 * returned if not a collection or not a map. 10741 */ 10742 CASS_EXPORT CassValueType 10743 cass_value_secondary_sub_type(const CassValue* collection); 10744 10745 10746 /*********************************************************************************** 10747 * 10748 * UUID 10749 * 10750 ************************************************************************************/ 10751 10752 /** 10753 * Creates a new UUID generator. 10754 * 10755 * <b>Note:</b> This object is thread-safe. It is best practice to create and reuse 10756 * a single object per application. 10757 * 10758 * <b>Note:</b> If unique node information (IP address) is unable to be determined 10759 * then random node information will be generated. 10760 * 10761 * @public @memberof CassUuidGen 10762 * 10763 * @return Returns a UUID generator that must be freed. 10764 * 10765 * @see cass_uuid_gen_free() 10766 * @see cass_uuid_gen_new_with_node() 10767 */ 10768 CASS_EXPORT CassUuidGen* 10769 cass_uuid_gen_new(); 10770 10771 /** 10772 * Creates a new UUID generator with custom node information. 10773 * 10774 * <b>Note:</b> This object is thread-safe. It is best practice to create and reuse 10775 * a single object per application. 10776 * 10777 * @public @memberof CassUuidGen 10778 * 10779 * @return Returns a UUID generator that must be freed. 10780 * 10781 * @see cass_uuid_gen_free() 10782 */ 10783 CASS_EXPORT CassUuidGen* 10784 cass_uuid_gen_new_with_node(cass_uint64_t node); 10785 10786 /** 10787 * Frees a UUID generator instance. 10788 * 10789 * @public @memberof CassUuidGen 10790 * 10791 * @param[in] uuid_gen 10792 */ 10793 CASS_EXPORT void 10794 cass_uuid_gen_free(CassUuidGen* uuid_gen); 10795 10796 /** 10797 * Generates a V1 (time) UUID. 10798 * 10799 * <b>Note:</b> This method is thread-safe 10800 * 10801 * @public @memberof CassUuidGen 10802 * 10803 * @param[in] uuid_gen 10804 * @param[out] output A V1 UUID for the current time. 10805 */ 10806 CASS_EXPORT void 10807 cass_uuid_gen_time(CassUuidGen* uuid_gen, 10808 CassUuid* output); 10809 10810 /** 10811 * Generates a new V4 (random) UUID 10812 * 10813 * <b>Note:</b>: This method is thread-safe 10814 * 10815 * @public @memberof CassUuidGen 10816 * 10817 * @param[in] uuid_gen 10818 * @param output A randomly generated V4 UUID. 10819 */ 10820 CASS_EXPORT void 10821 cass_uuid_gen_random(CassUuidGen* uuid_gen, 10822 CassUuid* output); 10823 10824 /** 10825 * Generates a V1 (time) UUID for the specified time. 10826 * 10827 * <b>Note:</b>: This method is thread-safe 10828 * 10829 * @public @memberof CassUuidGen 10830 * 10831 * @param[in] uuid_gen 10832 * @param[in] timestamp 10833 * @param[out] output A V1 UUID for the specified time. 10834 */ 10835 CASS_EXPORT void 10836 cass_uuid_gen_from_time(CassUuidGen* uuid_gen, 10837 cass_uint64_t timestamp, 10838 CassUuid* output); 10839 10840 /** 10841 * Sets the UUID to the minimum V1 (time) value for the specified time. 10842 * 10843 * @public @memberof CassUuid 10844 * 10845 * @param[in] time 10846 * @param[out] output A minimum V1 UUID for the specified time. 10847 */ 10848 CASS_EXPORT void 10849 cass_uuid_min_from_time(cass_uint64_t time, 10850 CassUuid* output); 10851 10852 /** 10853 * Sets the UUID to the maximum V1 (time) value for the specified time. 10854 * 10855 * @public @memberof CassUuid 10856 * 10857 * @param[in] time 10858 * @param[out] output A maximum V1 UUID for the specified time. 10859 */ 10860 CASS_EXPORT void 10861 cass_uuid_max_from_time(cass_uint64_t time, 10862 CassUuid* output); 10863 10864 /** 10865 * Gets the timestamp for a V1 UUID 10866 * 10867 * @public @memberof CassUuid 10868 * 10869 * @param[in] uuid 10870 * @return The timestamp in milliseconds since the Epoch 10871 * (00:00:00 UTC on 1 January 1970). 0 returned if the UUID 10872 * is not V1. 10873 */ 10874 CASS_EXPORT cass_uint64_t 10875 cass_uuid_timestamp(CassUuid uuid); 10876 10877 /** 10878 * Gets the version for a UUID 10879 * 10880 * @public @memberof CassUuid 10881 * 10882 * @param[in] uuid 10883 * @return The version of the UUID (1 or 4) 10884 */ 10885 CASS_EXPORT cass_uint8_t 10886 cass_uuid_version(CassUuid uuid); 10887 10888 /** 10889 * Returns a null-terminated string for the specified UUID. 10890 * 10891 * @public @memberof CassUuid 10892 * 10893 * @param[in] uuid 10894 * @param[out] output A null-terminated string of length CASS_UUID_STRING_LENGTH. 10895 */ 10896 CASS_EXPORT void 10897 cass_uuid_string(CassUuid uuid, 10898 char* output); 10899 10900 /** 10901 * Returns a UUID for the specified string. 10902 * 10903 * Example: "550e8400-e29b-41d4-a716-446655440000" 10904 * 10905 * @public @memberof CassUuid 10906 * 10907 * @param[in] str 10908 * @param[out] output 10909 */ 10910 CASS_EXPORT CassError 10911 cass_uuid_from_string(const char* str, 10912 CassUuid* output); 10913 10914 /** 10915 * Same as cass_uuid_from_string(), but with lengths for string 10916 * parameters. 10917 * 10918 * @public @memberof CassUuid 10919 * 10920 * @param[in] str 10921 * @param[in] str_length 10922 * @param[out] output 10923 * @return same as cass_uuid_from_string() 10924 * 10925 * @see cass_uuid_from_string() 10926 */ 10927 CASS_EXPORT CassError 10928 cass_uuid_from_string_n(const char* str, 10929 size_t str_length, 10930 CassUuid* output); 10931 10932 /*********************************************************************************** 10933 * 10934 * Timestamp generators 10935 * 10936 ***********************************************************************************/ 10937 10938 /** 10939 * Creates a new server-side timestamp generator. This generator allows Cassandra 10940 * to assign timestamps server-side. 10941 * 10942 * <b>Note:</b> This is the default timestamp generator. 10943 * 10944 * @cassandra{2.1+} 10945 * 10946 * @public @memberof CassTimestampGen 10947 * 10948 * @return Returns a timestamp generator that must be freed. 10949 * 10950 * @see cass_timestamp_gen_free() 10951 */ 10952 CASS_EXPORT CassTimestampGen* 10953 cass_timestamp_gen_server_side_new(); 10954 10955 /** 10956 * Creates a new monotonically increasing timestamp generator with microsecond 10957 * precision. 10958 * 10959 * This implementation guarantees a monotonically increasing timestamp. If the 10960 * timestamp generation rate exceeds one per microsecond or if the clock skews 10961 * into the past the generator will artificially increment the previously 10962 * generated timestamp until the request rate decreases or the clock skew 10963 * is corrected. 10964 * 10965 * By default, this timestamp generator will generate warnings if more than 10966 * 1 second of clock skew is detected. It will print an error every second until 10967 * the clock skew is resolved. These settings can be changed by using 10968 * `cass_timestamp_gen_monotonic_new_with_settings()` to create the generator 10969 * instance. 10970 * 10971 * <b>Note:</b> This generator is thread-safe and can be shared by multiple 10972 * sessions. 10973 * 10974 * @cassandra{2.1+} 10975 * 10976 * @public @memberof CassTimestampGen 10977 * 10978 * @return Returns a timestamp generator that must be freed. 10979 * 10980 * @see cass_timestamp_gen_monotonic_new_with_settings(); 10981 * @see cass_timestamp_gen_free() 10982 */ 10983 CASS_EXPORT CassTimestampGen* 10984 cass_timestamp_gen_monotonic_new(); 10985 10986 /** 10987 * Same as cass_timestamp_gen_monotonic_new(), but with settings for controlling 10988 * warnings about clock skew. 10989 * 10990 * @param warning_threshold_us The amount of clock skew, in microseconds, that 10991 * must be detected before a warning is triggered. A threshold less than 0 can 10992 * be used to disable warnings. 10993 * @param warning_interval_ms The amount of time, in milliseconds, to wait before 10994 * warning again about clock skew. An interval value less than or equal to 0 allows 10995 * the warning to be triggered every millisecond. 10996 * @return Returns a timestamp generator that must be freed. 10997 */ 10998 CASS_EXPORT CassTimestampGen* 10999 cass_timestamp_gen_monotonic_new_with_settings(cass_int64_t warning_threshold_us, 11000 cass_int64_t warning_interval_ms); 11001 11002 /** 11003 * Frees a timestamp generator instance. 11004 * 11005 * @cassandra{2.1+} 11006 * 11007 * @public @memberof CassTimestampGen 11008 * 11009 * @param[in] timestamp_gen 11010 */ 11011 CASS_EXPORT void 11012 cass_timestamp_gen_free(CassTimestampGen* timestamp_gen); 11013 11014 11015 /*********************************************************************************** 11016 * 11017 * Retry policies 11018 * 11019 ***********************************************************************************/ 11020 11021 /** 11022 * Creates a new default retry policy. 11023 * 11024 * This policy retries queries in the following cases: 11025 * <ul> 11026 * <li>On a read timeout, if enough replicas replied but data was not received.</li> 11027 * <li>On a write timeout, if a timeout occurs while writing the distributed batch log</li> 11028 * <li>On unavailable, it will move to the next host</li> 11029 * </ul> 11030 * 11031 * In all other cases the error will be returned. 11032 * 11033 * This policy always uses the query's original consistency level. 11034 * 11035 * @public @memberof CassRetryPolicy 11036 * 11037 * @return Returns a retry policy that must be freed. 11038 * 11039 * @see cass_retry_policy_free() 11040 */ 11041 CASS_EXPORT CassRetryPolicy* 11042 cass_retry_policy_default_new(); 11043 11044 /** 11045 * Creates a new downgrading consistency retry policy. 11046 * 11047 * <b>Important:</b> This policy may attempt to retry requests with a lower 11048 * consistency level. Using this policy can break consistency guarantees. 11049 * 11050 * This policy will retry in the same scenarios as the default policy, but 11051 * it will also retry in the following cases: 11052 * <ul> 11053 * <li>On a read timeout, if some replicas responded but is lower than 11054 * required by the current consistency level then retry with a lower 11055 * consistency level.</li> 11056 * <li>On a write timeout, Retry unlogged batches at a lower consistency level 11057 * if at least one replica responded. For single queries and batch if any 11058 * replicas responded then consider the request successful and swallow the 11059 * error.</li> 11060 * <li>On unavailable, retry at a lower consistency if at lease one replica 11061 * responded.</li> 11062 * </ul> 11063 * 11064 * This goal of this policy is to attempt to save a request if there's any 11065 * chance of success. A writes succeeds as long as there's a single copy 11066 * persisted and a read will succeed if there's some data available even 11067 * if it increases the risk of reading stale data. 11068 * 11069 * @deprecated This still works, but should not be used in new applications. It 11070 * can lead to unexpected behavior when the cluster is in a degraded state. 11071 * Instead, applications should prefer using the lowest consistency level on 11072 * statements that can be tolerated by a specific use case. 11073 * 11074 * @public @memberof CassRetryPolicy 11075 * 11076 * @return Returns a retry policy that must be freed. 11077 * 11078 * @see cass_retry_policy_free() 11079 */ 11080 CASS_EXPORT CASS_DEPRECATED(CassRetryPolicy* 11081 cass_retry_policy_downgrading_consistency_new()); 11082 11083 /** 11084 * Creates a new fallthrough retry policy. 11085 * 11086 * This policy never retries or ignores a server-side failure. The error 11087 * is always returned. 11088 * 11089 * @public @memberof CassRetryPolicy 11090 * 11091 * @return Returns a retry policy that must be freed. 11092 * 11093 * @see cass_retry_policy_free() 11094 */ 11095 CASS_EXPORT CassRetryPolicy* 11096 cass_retry_policy_fallthrough_new(); 11097 11098 /** 11099 * Creates a new logging retry policy. 11100 * 11101 * This policy logs the retry decision of its child policy. Logging is 11102 * done using CASS_LOG_INFO. 11103 * 11104 * @public @memberof CassRetryPolicy 11105 * 11106 * @param[in] child_retry_policy 11107 * @return Returns a retry policy that must be freed. NULL is returned if 11108 * the child_policy is a logging retry policy. 11109 * 11110 * @see cass_retry_policy_free() 11111 */ 11112 CASS_EXPORT CassRetryPolicy* 11113 cass_retry_policy_logging_new(CassRetryPolicy* child_retry_policy); 11114 11115 /** 11116 * Frees a retry policy instance. 11117 * 11118 * @public @memberof CassRetryPolicy 11119 * 11120 * @param[in] policy 11121 */ 11122 CASS_EXPORT void 11123 cass_retry_policy_free(CassRetryPolicy* policy); 11124 11125 /*********************************************************************************** 11126 * 11127 * Custom payload 11128 * 11129 ***********************************************************************************/ 11130 11131 /** 11132 * Creates a new custom payload. 11133 * 11134 * @public @memberof CassCustomPayload 11135 * 11136 * @cassandra{2.2+} 11137 * 11138 * @return Returns a custom payload that must be freed. 11139 * 11140 * @see cass_custom_payload_free() 11141 */ 11142 CASS_EXPORT CassCustomPayload* 11143 cass_custom_payload_new(); 11144 11145 /** 11146 * Frees a custom payload instance. 11147 * 11148 * @cassandra{2.2+} 11149 * 11150 * @public @memberof CassCustomPayload 11151 * 11152 * @param[in] payload 11153 */ 11154 CASS_EXPORT void 11155 cass_custom_payload_free(CassCustomPayload* payload); 11156 11157 /** 11158 * Sets an item to the custom payload. 11159 * 11160 * @cassandra{2.2+} 11161 * 11162 * @public @memberof CassCustomPayload 11163 * 11164 * @param[in] payload 11165 * @param[in] name 11166 * @param[in] value 11167 * @param[in] value_size 11168 */ 11169 CASS_EXPORT void 11170 cass_custom_payload_set(CassCustomPayload* payload, 11171 const char* name, 11172 const cass_byte_t* value, 11173 size_t value_size); 11174 11175 /** 11176 * Same as cass_custom_payload_set(), but with lengths for string 11177 * parameters. 11178 * 11179 * @cassandra{2.2+} 11180 * 11181 * @public @memberof CassCustomPayload 11182 * 11183 * @param[in] payload 11184 * @param[in] name 11185 * @param[in] name_length 11186 * @param[in] value 11187 * @param[in] value_size 11188 */ 11189 CASS_EXPORT void 11190 cass_custom_payload_set_n(CassCustomPayload* payload, 11191 const char* name, 11192 size_t name_length, 11193 const cass_byte_t* value, 11194 size_t value_size); 11195 11196 /** 11197 * Removes an item from the custom payload. 11198 * 11199 * @cassandra{2.2+} 11200 * 11201 * @public @memberof CassCustomPayload 11202 * 11203 * @param[in] payload 11204 * @param[in] name 11205 */ 11206 CASS_EXPORT void 11207 cass_custom_payload_remove(CassCustomPayload* payload, 11208 const char* name); 11209 11210 /** 11211 * Same as cass_custom_payload_set(), but with lengths for string 11212 * parameters. 11213 * 11214 * @cassandra{2.2+} 11215 * 11216 * @public @memberof CassCustomPayload 11217 * 11218 * @param[in] payload 11219 * @param[in] name 11220 * @param[in] name_length 11221 */ 11222 CASS_EXPORT void 11223 cass_custom_payload_remove_n(CassCustomPayload* payload, 11224 const char* name, 11225 size_t name_length); 11226 11227 11228 /*********************************************************************************** 11229 * 11230 * Consistency 11231 * 11232 ***********************************************************************************/ 11233 11234 /** 11235 * Gets the string for a consistency. 11236 * 11237 * @param[in] consistency 11238 * @return A null-terminated string for the consistency. 11239 * Example: "ALL", "ONE", "QUORUM", etc. 11240 */ 11241 CASS_EXPORT const char* 11242 cass_consistency_string(CassConsistency consistency); 11243 11244 /*********************************************************************************** 11245 * 11246 * Write type 11247 * 11248 ***********************************************************************************/ 11249 /** 11250 * Gets the string for a write type. 11251 * 11252 * @param[in] write_type 11253 * @return A null-terminated string for the write type. 11254 * Example: "BATCH", "SIMPLE", "COUNTER", etc. 11255 */ 11256 CASS_EXPORT const char* 11257 cass_write_type_string(CassWriteType write_type); 11258 11259 /*********************************************************************************** 11260 * 11261 * Error 11262 * 11263 ***********************************************************************************/ 11264 11265 /** 11266 * Gets a description for an error code. 11267 * 11268 * @param[in] error 11269 * @return A null-terminated string describing the error. 11270 */ 11271 CASS_EXPORT const char* 11272 cass_error_desc(CassError error); 11273 11274 /*********************************************************************************** 11275 * 11276 * Log 11277 * 11278 ***********************************************************************************/ 11279 11280 /** 11281 * Explicitly wait for the log to flush and deallocate resources. 11282 * This *MUST* be the last call using the library. It is an error 11283 * to call any cass_*() functions after this call. 11284 * 11285 * @deprecated This is no longer useful and does nothing. Expect this to be 11286 * removed in a future release. 11287 */ 11288 CASS_EXPORT CASS_DEPRECATED(void 11289 cass_log_cleanup()); 11290 11291 /** 11292 * Sets the log level. 11293 * 11294 * <b>Note:</b> This needs to be done before any call that might log, such as 11295 * any of the cass_cluster_*() or cass_ssl_*() functions. 11296 * 11297 * <b>Default:</b> CASS_LOG_WARN 11298 * 11299 * @param[in] log_level 11300 */ 11301 CASS_EXPORT void 11302 cass_log_set_level(CassLogLevel log_level); 11303 11304 /** 11305 * Sets a callback for handling logging events. 11306 * 11307 * <b>Note:</b> This needs to be done before any call that might log, such as 11308 * any of the cass_cluster_*() or cass_ssl_*() functions. 11309 * 11310 * <b>Default:</b> An internal callback that prints to stderr 11311 * 11312 * @param[in] data An opaque data object passed to the callback. 11313 * @param[in] callback A callback that handles logging events. This is 11314 * called in a separate thread so access to shared data must be synchronized. 11315 */ 11316 CASS_EXPORT void 11317 cass_log_set_callback(CassLogCallback callback, 11318 void* data); 11319 11320 /** 11321 * Sets the log queue size. 11322 * 11323 * <b>Note:</b> This needs to be done before any call that might log, such as 11324 * any of the cass_cluster_*() or cass_ssl_*() functions. 11325 * 11326 * <b>Default:</b> 2048 11327 * 11328 * @deprecated This is no longer useful and does nothing. Expect this to be 11329 * removed in a future release. 11330 * 11331 * @param[in] queue_size 11332 */ 11333 CASS_EXPORT CASS_DEPRECATED(void 11334 cass_log_set_queue_size(size_t queue_size)); 11335 11336 /** 11337 * Gets the string for a log level. 11338 * 11339 * @param[in] log_level 11340 * @return A null-terminated string for the log level. 11341 * Example: "ERROR", "WARN", "INFO", etc. 11342 */ 11343 CASS_EXPORT const char* 11344 cass_log_level_string(CassLogLevel log_level); 11345 11346 /*********************************************************************************** 11347 * 11348 * Inet 11349 * 11350 ************************************************************************************/ 11351 11352 /** 11353 * Constructs an inet v4 object. 11354 * 11355 * @public @memberof CassInet 11356 * 11357 * @param[in] address An address of size CASS_INET_V4_LENGTH 11358 * @return An inet object. 11359 */ 11360 CASS_EXPORT CassInet 11361 cass_inet_init_v4(const cass_uint8_t* address); 11362 11363 /** 11364 * Constructs an inet v6 object. 11365 * 11366 * @public @memberof CassInet 11367 * 11368 * @param[in] address An address of size CASS_INET_V6_LENGTH 11369 * @return An inet object. 11370 */ 11371 CASS_EXPORT CassInet 11372 cass_inet_init_v6(const cass_uint8_t* address); 11373 11374 /** 11375 * Returns a null-terminated string for the specified inet. 11376 * 11377 * @public @memberof CassInet 11378 * 11379 * @param[in] inet 11380 * @param[out] output A null-terminated string of length CASS_INET_STRING_LENGTH. 11381 */ 11382 CASS_EXPORT void 11383 cass_inet_string(CassInet inet, 11384 char* output); 11385 11386 /** 11387 * Returns an inet for the specified string. 11388 * 11389 * Examples: "127.0.0.1" or "::1" 11390 * 11391 * @public @memberof CassInet 11392 * 11393 * @param[in] str 11394 * @param[out] output 11395 */ 11396 CASS_EXPORT CassError 11397 cass_inet_from_string(const char* str, 11398 CassInet* output); 11399 11400 /** 11401 * Same as cass_inet_from_string(), but with lengths for string 11402 * parameters. 11403 * 11404 * @public @memberof CassInet 11405 * 11406 * @param[in] str 11407 * @param[in] str_length 11408 * @param[out] output 11409 * @return same as cass_inet_from_string() 11410 * 11411 * @see cass_inet_from_string() 11412 */ 11413 CASS_EXPORT CassError 11414 cass_inet_from_string_n(const char* str, 11415 size_t str_length, 11416 CassInet* output); 11417 11418 /*********************************************************************************** 11419 * 11420 * Date/Time 11421 * 11422 ************************************************************************************/ 11423 11424 /** 11425 * Converts a unix timestamp (in seconds) to the Cassandra "date" type. The "date" type 11426 * represents the number of days since the Epoch (1970-01-01) with the Epoch centered at 11427 * the value 2^31. 11428 * 11429 * @cassandra{2.2+} 11430 * 11431 * @param[in] epoch_secs 11432 * @return the number of days since the date -5877641-06-23 11433 */ 11434 CASS_EXPORT cass_uint32_t 11435 cass_date_from_epoch(cass_int64_t epoch_secs); 11436 11437 /** 11438 * Converts a unix timestamp (in seconds) to the Cassandra "time" type. The "time" type 11439 * represents the number of nanoseconds since midnight (range 0 to 86399999999999). 11440 * 11441 * @cassandra{2.2+} 11442 * 11443 * @param[in] epoch_secs 11444 * @return nanoseconds since midnight 11445 */ 11446 CASS_EXPORT cass_int64_t 11447 cass_time_from_epoch(cass_int64_t epoch_secs); 11448 11449 /** 11450 * Combines the Cassandra "date" and "time" types to Epoch time in seconds. 11451 * 11452 * @cassandra{2.2+} 11453 * 11454 * @param[in] date 11455 * @param[in] time 11456 * @return Epoch time in seconds. Negative times are possible if the date 11457 * occurs before the Epoch (1970-1-1). 11458 */ 11459 CASS_EXPORT cass_int64_t 11460 cass_date_time_to_epoch(cass_uint32_t date, 11461 cass_int64_t time); 11462 11463 /*********************************************************************************** 11464 * 11465 * Allocator 11466 * 11467 ************************************************************************************/ 11468 11469 /** 11470 * Set custom allocation functions. 11471 * 11472 * <b>Note:</b> This is not thread-safe. The allocation functions must be set 11473 * before any other library function is called. 11474 * 11475 * <b>Default:</b> The C runtime's malloc(), realloc() and free() 11476 * 11477 * <b>Important:</b> The C runtime's malloc(), realloc() and free() will be 11478 * used by libuv when using versions 1.5 or earlier. 11479 * 11480 * @param[in] malloc_func 11481 * @param[in] realloc_func 11482 * @param[in] free_func 11483 */ 11484 CASS_EXPORT void 11485 cass_alloc_set_functions(CassMallocFunction malloc_func, 11486 CassReallocFunction realloc_func, 11487 CassFreeFunction free_func); 11488 11489 #ifdef __cplusplus 11490 } /* extern "C" */ 11491 #endif 11492 11493 #endif /* __CASS_H_INCLUDED__ */ 11494