1 /* -*- Mode: C; tab-width: 4; c-basic-offset: 4; indent-tabs-mode: nil -*- */ 2 /* 3 * Copyright 2017 Couchbase, Inc. 4 * 5 * Licensed under the Apache License, Version 2.0 (the "License"); 6 * you may not use this file except in compliance with the License. 7 * You may obtain a copy of the License at 8 * 9 * http://www.apache.org/licenses/LICENSE-2.0 10 * 11 * Unless required by applicable law or agreed to in writing, software 12 * distributed under the License is distributed on an "AS IS" BASIS, 13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 * See the License for the specific language governing permissions and 15 * limitations under the License. 16 */ 17 18 19 /** 20 * @file 21 * @brief Command codes for libcouchbase. 22 * 23 * @details 24 * These codes may be passed to 'lcb_cntl'. 25 * 26 * Note that the constant values are also public API; thus allowing forwards 27 * and backwards compatibility. 28 */ 29 30 #ifndef LCB_CNTL_H 31 #define LCB_CNTL_H 32 33 #ifdef __cplusplus 34 extern "C" { 35 #endif 36 37 38 /** 39 * @ingroup lcb-cntl 40 * @defgroup lcb-cntl-settings Setting List 41 * @brief Adjust tunables for the client 42 * @details 43 * 44 * The constants in this file are used to control the behavior of the library. 45 * All of the operations above may be passed as the `cmd` parameter to the 46 * lcb_cntl() function, thus: 47 * 48 * @code{.c} 49 * char something; 50 * lcb_error_t rv; 51 * rv = lcb_cntl(instance, LCB_CNTL_GET, LCB_CNTL_FOO, &something); 52 * @endcode 53 * 54 * will retrieve the setting of `LCB_CNTL_FOO` into `something`. 55 * 56 * You may also use the lcb_cntl_string() function, which operates on 57 * strings and can set various configuration properties fairly simply. Note 58 * however that string names are subject to change, and not all configuration 59 * directives have a string alias: 60 * 61 * @code{.c} 62 * rv = lcb_cntl_string("operation_timeout", "5.0"); 63 * @endcode 64 * 65 * Of the commands listed below, some will be read-only (i.e. you may only 66 * _read_ the setting using the @ref LCB_CNTL_GET `mode`), some will be write-only 67 * (i.e. you may only _modify_ the setting, and use @ref LCB_CNTL_SET for the `mode`) 68 * and some will be both readable and writable. 69 * 70 * Along the documentation of each specific command, there is a table displaying 71 * the modes supported and the expected pointer type to be passed as the `arg` 72 * value into lcb_cntl(). Note that some read-write commands require different 73 * pointer types depending on whether the `mode` is retrieval or storage. 74 * 75 * 76 * @section lcb-time-info Timeout and Time Value Settings 77 * 78 * There are various settings on the library that control behavior with 79 * respect to wall clock time. 80 * 81 * Timeout settings control how long the library will wait for a certain event 82 * before proceeding to the next course of action (which may either be to try 83 * a different operation or fail the current one, depending on the specific 84 * timeout). 85 * 86 * Other settings may configure how often the library proactively polls for 87 * a configuration update, retries various interally retried operations and 88 * so forth. 89 * 90 * Time values are specified in _microseconds_ stored within an `lcb_U32`. 91 * 92 * When specified as an argument to lcb_cntl_string() or through the connection 93 * string, it will be parsed from a string float value where the integer-part 94 * is in seconds and the fractional-part is in fractions of a second. 95 * 96 * Note that timeouts in libcouchbase are implemented via an event loop 97 * scheduler. As such their accuracy and promptness is limited by how 98 * often the event loop is invoked and how much wall time is spent in 99 * each of their handlers. Specifically if you issue long running blocking 100 * calls within any of the handlers (and this means any of the library's 101 * callbacks) then the timeout accuracy will be impacted. 102 * 103 * Further behavior is dependent on the event loop plugin itself and how 104 * it schedules timeouts. 105 * 106 * 107 * @par Configuration Stability Attributes 108 * Configuration parameters are still subject to the API classification used 109 * in @ref lcb_attributes. For _deprecated_ control commands, lcb_cntl() will 110 * either perform the operation, _or_ consider it a no-op, _or_ return an error 111 * code. 112 */ 113 114 /** 115 * @addtogroup lcb-cntl-settings 116 * @{ 117 */ 118 119 /** 120 * @name Modes 121 * Modes for the lcb_cntl() `mode` argument 122 * @{ 123 */ 124 #define LCB_CNTL_SET 0x01 /**< @brief Modify a setting */ 125 #define LCB_CNTL_GET 0x00 /**< @brief Retrieve a setting */ 126 /**@}*/ 127 128 /** 129 * @brief Operation Timeout 130 * 131 * The operation timeout is the maximum amount of time the library will wait 132 * for an operation to receive a response before invoking its callback with 133 * a failure status. 134 * 135 * An operation may timeout if: 136 * 137 * * A server is taking too long to respond 138 * * An updated cluster configuration has not been promptly received 139 * 140 * @code{.c} 141 * lcb_U32 tmo = 3500000; 142 * lcb_cntl(instance, LCB_CNTL_SET, LCB_CNTL_OP_TIMEOUT, &tmo); 143 * @endcode 144 * 145 * @cntl_arg_both{lcbU32*} 146 * @committed 147 * @see lcb-time-info 148 */ 149 #define LCB_CNTL_OP_TIMEOUT 0x00 150 151 /** 152 * @brief Views Timeout 153 * This is the I/O timeout for HTTP requests issues with LCB_HTTP_TYPE_VIEWS 154 * 155 * @cntl_arg_both{lcb_U32*} 156 * @committed 157 */ 158 #define LCB_CNTL_VIEW_TIMEOUT 0x01 159 160 /** 161 * @brief N1QL Timeout 162 * This is the I/O timeout for N1QL queries, issued via lcb_n1ql_query() 163 * 164 * @cntl_arg_both{lcb_U32*} 165 * @committed 166 */ 167 #define LCB_CNTL_N1QL_TIMEOUT 0x3D 168 169 /** 170 * @brief Get the name of the bucket 171 * This returns the name of the bucket this instance is connected to, or `NULL` 172 * if not yet connected to a bucket 173 * 174 * @cntl_arg_getonly{`const char*`} 175 * @committed 176 */ 177 #define LCB_CNTL_BUCKETNAME 0x30 178 179 /** 180 * @brief Get the bucket type. 181 * This returns the bucket type - which is either of the following: 182 * 183 * * LCB_BTYPE_UNSPEC 184 * * LCB_BTYPE_COUCHBASE 185 * * LCB_BTYPE_EPHEMERAL 186 * * LCB_BTYPE_MEMCACHED 187 * 188 * @see https://developer.couchbase.com/documentation/server/current/architecture/core-data-access-buckets.html 189 * 190 * @cntl_arg_getonly{lcb_BTYPE*} 191 */ 192 #define LCB_CNTL_BUCKETTYPE 0x48 193 194 /** 195 * @brief Get the handle type. 196 * This returns the handle type - which is either LCB_TYPE_CLUSTER or 197 * LCB_TYPE_BUCKET 198 * 199 * @cntl_arg_getonly{lcb_type_t*} 200 */ 201 #define LCB_CNTL_HANDLETYPE 0x04 202 203 /**@brief Get the vBucket handle. 204 * Obtains the current cluster configuration from the client. 205 * 206 * @cntl_arg_getonly{lcbvb_CONFIG**} 207 */ 208 #define LCB_CNTL_VBCONFIG 0x05 209 210 /**@brief Get the iops implementation instance 211 * 212 * @cntl_arg_getonly{lcb_io_opt_t*} 213 * @uncommitted 214 */ 215 #define LCB_CNTL_IOPS 0x06 216 217 218 /** @brief Structure containing mapping information for a key */ 219 typedef struct lcb_cntl_vbinfo_st { 220 int version; 221 222 union { 223 /** v0 */ 224 struct { 225 const void *key; /**< **Input** Key */ 226 lcb_SIZE nkey; /**< **Input** Length of key */ 227 int vbucket; /**< **Output** Mapped vBucket */ 228 int server_index; /**< **Output** Server index for vBucket */ 229 } v0; 230 } v; 231 } lcb_cntl_vbinfo_t; 232 233 /** 234 * @brief Get the vBucket ID for a given key, based on the current configuration 235 * 236 * @cntl_arg_getonly{lcb_cntl_vbinfo_t*} 237 * @committed 238 */ 239 #define LCB_CNTL_VBMAP 0x07 240 241 242 /** 243 * Modes for handling IPv6 in the IO layer. 244 */ 245 typedef enum { 246 LCB_IPV6_DISABLED = 0x00, /**< disable IPv6 */ 247 LCB_IPV6_ONLY = 0x1, /**< enforce only IPv6 */ 248 LCB_IPV6_ALLOW = 0x02 /**< use both IPv6 and IPv4 */ 249 } lcb_ipv6_t; 250 251 /** 252 * @brief IPv4/IPv6 selection policy 253 * 254 * Setting which controls whether hostname lookups should prefer IPv4 or IPv6 255 * 256 * Use `ipv6` in the connection string (e.g. "ipv6=allow" or "ipv6=only") 257 * 258 * @cntl_arg_both{lcb_ipv6_t*} 259 * @committed 260 */ 261 #define LCB_CNTL_IP6POLICY 0x0b 262 263 /** 264 * @brief Configuration error threshold. 265 * 266 * This number indicates how many 267 * network/mapping/not-my-vbucket errors are received before a configuration 268 * update is requested again. 269 * 270 * @cntl_arg_both{lcb_SIZE*} 271 */ 272 #define LCB_CNTL_CONFERRTHRESH 0x0c 273 274 /** 275 * @brief Default timeout for lcb_durability_poll() 276 * @ingroup lcb-time-info 277 * 278 * This is the time the client will 279 * spend sending repeated probes to a given key's vBucket masters and replicas 280 * before they are deemed not to have satisfied the durability requirements 281 * 282 * @cntl_arg_both{lcb_U32*} 283 * @committed 284 */ 285 #define LCB_CNTL_DURABILITY_TIMEOUT 0x0d 286 287 /** 288 * @brief Polling grace interval for lcb_durability_poll() 289 * 290 * This is the time the client will wait between repeated probes to 291 * a given server. 292 * 293 * @cntl_arg_both{lcb_U32*} 294 * @committed 295 */ 296 #define LCB_CNTL_DURABILITY_INTERVAL 0x0e 297 298 /** 299 * @brief Timeout for otherwise unspecified HTTP requests 300 * 301 * Examples of these kinds of HTTP requests might be cluster management, 302 * user management, etc. 303 * 304 * @cntl_arg_both{lcb_U32*} 305 * @committed 306 */ 307 #define LCB_CNTL_HTTP_TIMEOUT 0x0f 308 309 /** 310 * @brief Print verbose plugin load information to console 311 * 312 * This modifies a static, global setting regarding whether to 313 * print verbose information when trying to dynamically load an IO plugin. 314 * The information printed can be useful in determining why a plugin failed 315 * to load. This setting can also be controlled via the 316 * "LIBCOUCHBASE_DLOPEN_DEBUG" environment variable (and if enabled from the 317 * environment, will override the setting mentioned here). 318 * 319 * @cntl_arg_both{int*} 320 * 321 * @note Pass NULL to lcb_cntl for the 'instance' parameter. 322 * @volatile 323 */ 324 #define LCB_CNTL_IOPS_DLOPEN_DEBUG 0x11 325 326 /**@brief Initial bootstrap timeout. 327 * This is how long the client will wait to obtain the initial configuration. 328 * 329 * @cntl_arg_both{lcb_U32*} 330 * @committed*/ 331 #define LCB_CNTL_CONFIGURATION_TIMEOUT 0x12 332 333 /** 334 * @brief Randomize order of bootstrap nodes. 335 * 336 * This controls whether the connection attempts for configuration retrievals 337 * should be done in the supplied order or whether they should be randomized. 338 * 339 * For the initial connection the supplied order is the list of hosts provided 340 * in the lcb_create_st structure. For subsequent connections this is the 341 * order of nodes as received by the server. 342 * 343 * @cntl_arg_both{int*} 344 * @committed 345 */ 346 #define LCB_CNTL_RANDOMIZE_BOOTSTRAP_HOSTS 0x14 347 348 /** 349 * @brief Determine if file-based configuration has been loaded 350 * 351 * If the configuration cache is in use, the argument pointer 352 * will be set to a true value. If the configuration cache was not used, 353 * the argument pointer will be set to false. 354 * 355 * A false value may indicates that the client will need to load the 356 * configuration from the network. This may be caused by the following: 357 * - The configuration cache did not exist or was empty 358 * - The configuration cache contained stale information 359 * 360 * @cntl_arg_getonly{int*} 361 * @uncommitted 362 */ 363 #define LCB_CNTL_CONFIG_CACHE_LOADED 0x15 364 365 /** 366 * @brief Force a specific SASL mechanism 367 * 368 * Force a specific SASL mechanism to use for authentication. This 369 * can allow a user to ensure a certain level of security and have the 370 * connection fail if the desired mechanism is not available. 371 * 372 * When setting this value, the arg parameter shall be a 373 * `NUL`-terminated string or a `NULL` pointer (to unset). When retrieving 374 * this value, the parameter shall be set to a `char **`. Note that this 375 * value (in LCB_CNTL_GET) is valid only until the next call to a 376 * libcouchbase API, after which it may have been freed. 377 * 378 * @cntl_arg_get_and_set{char**, char*} 379 */ 380 #define LCB_CNTL_FORCE_SASL_MECH 0x16 381 382 /** 383 * @brief Maximum number of HTTP redirects to follow 384 * Set how many redirects the library should follow for the single request. 385 * Set to -1 to remove limit at all. 386 * 387 * @cntl_arg_both{int*} 388 * @uncommitted 389 */ 390 #define LCB_CNTL_MAX_REDIRECTS 0x17 391 392 /** 393 * @name Logging 394 * 395 * Verbose logging may be enabled by default using the environment variable 396 * `LCB_LOGLEVEL` and setting it to a number > 1; higher values produce more 397 * verbose output. The maximum level is `5`. 398 * 399 * You may also install your own logger using lcb_cntl() and the 400 * @ref LCB_CNTL_LOGGER constant. Note that 401 * the logger functions will not be called rapidly from within hot paths. 402 * @{ 403 */ 404 405 /** 406 * @brief Logging Levels 407 * @committed 408 */ 409 typedef enum { 410 LCB_LOG_TRACE = 0, /**< the most verbose level */ 411 LCB_LOG_DEBUG, /**< diagnostic information, required to investigate problems */ 412 LCB_LOG_INFO, /**< useful notices, not often */ 413 LCB_LOG_WARN, /**< error notifications */ 414 LCB_LOG_ERROR, /**< error messages, usually the library have to re-initialize connection instance */ 415 LCB_LOG_FATAL, /**< fatal errors, the library cannot proceed */ 416 LCB_LOG_MAX /**< internal value for total number of levels */ 417 } lcb_log_severity_t; 418 419 struct lcb_logprocs_st; 420 421 /** 422 * @brief Logger callback 423 * 424 * 425 * This callback is invoked for each logging message emitted 426 * @param procs the logging structure provided 427 * @param iid instance id 428 * @param subsys a string describing the module which emitted the message 429 * @param severity one of the LCB_LOG_* severity constants. 430 * @param srcfile the source file which emitted this message 431 * @param srcline the line of the file for the message 432 * @param fmt a printf format string 433 * @param ap a va_list for vprintf 434 */ 435 typedef void (*lcb_logging_callback)(struct lcb_logprocs_st *procs, 436 unsigned int iid, const char *subsys, int severity, const char *srcfile, 437 int srcline, const char *fmt, va_list ap); 438 439 /** 440 * @brief Logging context 441 * @volatile 442 * 443 * This structure defines the logging handlers. Currently there is only 444 * a single field defined which is the default callback for the loggers. 445 * This API may change. 446 */ 447 typedef struct lcb_logprocs_st { 448 int version; 449 union { struct { lcb_logging_callback callback; } v0; } v; 450 } lcb_logprocs; 451 452 /** 453 * @brief Access the lcb_logprocs structure 454 * @uncommitted 455 * 456 * The lcb_logoprocs structure passed must not be freed until the instance 457 * is completely destroyed. This will only happen once the destruction 458 * callback is called (see lcb_set_destroy_callback()). 459 * 460 * @cntl_arg_get_and_set{lcb_logprocs**,lcb_logprocs*}*/ 461 #define LCB_CNTL_LOGGER 0x18 462 463 /** 464 * Helper to express printf spec for sensitive data. Usage: 465 * 466 * printf("Logged as " LCB_LOG_SPEC("%s") " user", LCB_LOG_UD(instance, doc->username)); 467 */ 468 #define LCB_LOG_SPEC(fmt) "%s" fmt "%s" 469 470 #define LCB_LOG_UD_OTAG "<ud>" 471 #define LCB_LOG_UD_CTAG "</ud>" 472 /** 473 * User data is data that is stored into Couchbase by the application user account. 474 * 475 * - Key and value pairs in JSON documents, or the key exclusively 476 * - Application/Admin usernames that identify the human person 477 * - Names and email addresses asked during product registration and alerting 478 * - Usernames 479 * - Document xattrs 480 * - Query statements included in the log file collected by support that leak 481 * the document fields (Select floor_price from stock). 482 */ 483 #define LCB_LOG_UD(instance, val) \ 484 lcb_is_redacting_logs(instance) ? LCB_LOG_UD_OTAG : "", val, lcb_is_redacting_logs(instance) ? LCB_LOG_UD_CTAG : "" 485 486 #define LCB_LOG_MD_OTAG "<md>" 487 #define LCB_LOG_MD_CTAG "</md>" 488 /** 489 * Metadata is logical data needed by Couchbase to store and process user data. 490 * 491 * - Cluster name 492 * - Bucket names 493 * - DDoc/view names 494 * - View code 495 * - Index names 496 * - Mapreduce Design Doc Name and Definition (IP) 497 * - XDCR Replication Stream Names 498 * - And other couchbase resource specific meta data 499 */ 500 #define LCB_LOG_MD(instance, val) \ 501 lcb_is_redacting_logs(instance) ? LCB_LOG_MD_OTAG : "", val, lcb_is_redacting_logs(instance) ? LCB_LOG_MD_CTAG : "" 502 503 #define LCB_LOG_SD_OTAG "<sd>" 504 #define LCB_LOG_SD_CTAG "</sd>" 505 /** 506 * System data is data from other parts of the system Couchbase interacts with over the network. 507 * 508 * - IP addresses 509 * - IP tables 510 * - Hosts names 511 * - Ports 512 * - DNS topology 513 */ 514 #define LCB_LOG_SD(instance, val) \ 515 lcb_is_redacting_logs(instance) ? LCB_LOG_SD_OTAG : "", val, lcb_is_redacting_logs(instance) ? LCB_LOG_SD_CTAG : "" 516 /**@}*/ 517 518 519 /** 520 * @brief Refresh Throttling 521 * 522 * Modify the amount of time (in microseconds) before the 523 * @ref LCB_CNTL_CONFERRTHRESH will forcefully be set to its maximum 524 * number forcing a configuration refresh. 525 * 526 * Note that if you expect a high number of timeouts in your operations, you 527 * should set this to a high number (along with `CONFERRTHRESH`). If you 528 * are using the default timeout setting, then this value is likely optimal. 529 * 530 * @cntl_arg_both{lcb_U32*} 531 * @see LCB_CNTL_CONFERRTHRESH 532 */ 533 #define LCB_CNTL_CONFDELAY_THRESH 0x19 534 535 /** 536 * @brief Get the transport used to fetch cluster configuration. 537 * @cntl_arg_getonly{lcb_config_transport_t*} 538 * @uncommitted 539 */ 540 #define LCB_CNTL_CONFIG_TRANSPORT 0x1A 541 542 /** 543 * @brief Per-node configuration timeout. 544 * 545 * The per-node configuration timeout sets the amount of time to wait 546 * for each node within the bootstrap/configuration process. This interval 547 * is a subset of the @ref LCB_CNTL_CONFIGURATION_TIMEOUT 548 * option mentioned above and is intended 549 * to ensure that the bootstrap process does not wait too long for a given 550 * node. Nodes that are physically offline may never respond and it may take 551 * a long time until they are detected as being offline. 552 * See CCBC-261 and CCBC-313 for more reasons. 553 * 554 * @note the `CONFIGURATION_TIMEOUT` should be higher than this number. 555 * No check is made to ensure that this is the case, however. 556 * 557 * @cntl_arg_both{lcb_U32*} 558 * @see LCB_CNTL_CONFIGURATION_TIMEOUT 559 * @committed 560 */ 561 #define LCB_CNTL_CONFIG_NODE_TIMEOUT 0x1B 562 563 /** 564 * @brief Idling/Persistence for HTTP bootstrap 565 * 566 * By default the behavior of the library for HTTP bootstrap is to keep the 567 * stream open at all times (opening a new stream on a different host if the 568 * existing one is broken) in order to proactively receive configuration 569 * updates. 570 * 571 * The default value for this setting is -1. Changing this to another number 572 * invokes the following semantics: 573 * 574 * - The configuration stream is not kept alive indefinitely. It is kept open 575 * for the number of seconds specified in this setting. The socket is closed 576 * after a period of inactivity (indicated by this setting). 577 * 578 * - If the stream is broken (and no current refresh was requested by the 579 * client) then a new stream is not opened. 580 * 581 * @cntl_arg_both{lcb_U32*} 582 * @volatile 583 */ 584 #define LCB_CNTL_HTCONFIG_IDLE_TIMEOUT 0x1C 585 586 /** 587 * @brief Get the current SCM changeset for the library binary 588 * @cntl_arg_getonly{char**} 589 */ 590 #define LCB_CNTL_CHANGESET 0x1F 591 592 /** 593 * @brief File used for the configuration cache. 594 * 595 * The configuration 596 * cache allows to bootstrap from a cluster without using the initial 597 * bootstrap connection, considerably reducing latency. If the file passed 598 * does not exist, the normal bootstrap process is performed and the file 599 * is written to with the current information. File will be updated as 600 * the configuration in the cluster changes. Multiple instances may race 601 * to update the file, and that is the intended behavior. 602 * 603 * @note The leading directories for the file must exist, otherwise the file 604 * will never be created. 605 * 606 * @note Configuration cache is not supported for memcached buckets 607 * @cntl_arg_get_and_set{char**, char*} 608 * @uncommitted 609 * @see LCB_CNTL_CONFIG_CACHE_LOADED 610 */ 611 #define LCB_CNTL_CONFIGCACHE 0x21 612 613 /** 614 * @brief File used for read-only configuration cache 615 * 616 * This is identical to the @ref LCB_CNTL_CONFIGCACHE directive, except that 617 * it guarantees that the library will never overwrite or otherwise modify 618 * the path specified. 619 * 620 * @see LCB_CNTL_CONFIGCACHE 621 */ 622 #define LCB_CNTL_CONFIGCACHE_RO 0x36 623 624 /** 625 * SSL options 626 * 627 * @committed 628 */ 629 typedef enum { 630 LCB_SSL_ENABLED = 1 << 0, /**< Use SSL */ 631 LCB_SSL_NOVERIFY = 1 << 1, /**< Don't verify certificates */ 632 LCB_SSL_NOGLOBALINIT = 1 << 2 /**< Do not call SSL's global init functions */ 633 } lcb_SSLOPTS; 634 635 /** 636 * @brief Get SSL Mode 637 * 638 * Retrieve the SSL mode currently in use by the library. This is a read-only 639 * setting. To set the SSL mode at the library, specify the appropriate values 640 * within the connection string. See @ref lcb_create_st3 for details. 641 * 642 * @cntl_arg_getonly{`int*` (value is one of @ref lcb_SSLOPTS)} 643 * @committed 644 */ 645 #define LCB_CNTL_SSL_MODE 0x22 646 647 /** 648 * @brief Get SSL Certificate path 649 * 650 * Retrieve the path to the CA certificate (if any) being used. 651 * 652 * @cntl_arg_getonly{`char**`} 653 * @see LCB_CNTL_SSL_MODE 654 * @committed 655 */ 656 #define LCB_CNTL_SSL_CERT 0x23 657 658 /** 659 * @brief Get SSL private key path 660 * 661 * Retrieve the path to the private key (if any) being used. 662 * When key specified, the library will use it to authenticate on the services, 663 * skipping all other authentication mechanisms (SASL, HTTP Basic auth, etc) 664 * 665 * @cntl_arg_getonly{`char**`} 666 * @see LCB_CNTL_SSL_MODE 667 * @see https://developer.couchbase.com/documentation/server/5.0/security/security-certs-auth.html 668 * @committed 669 */ 670 #define LCB_CNTL_SSL_KEY 0x4b 671 672 /** 673 * @brief Get SSL trust store path 674 * 675 * Trust store might be NULL, in this case the library expects it to be concatenated with certificate. 676 * 677 * @cntl_arg_getonly{`char**`} 678 * @see LCB_CNTL_SSL_MODE 679 * @see https://developer.couchbase.com/documentation/server/5.0/security/security-certs-auth.html 680 * @committed 681 */ 682 #define LCB_CNTL_SSL_TRUSTSTORE 0x4d 683 684 /** 685 * Alias for @ref LCB_CNTL_SSL_CERT for backward compatibility. 686 * @deprecated 687 */ 688 #define LCB_CNTL_SSL_CACERT LCB_CNTL_SSL_CERT 689 690 /** 691 * @brief Select retry mode to manipulate 692 */ 693 typedef enum { 694 LCB_RETRY_ON_TOPOCHANGE = 0, /**< Select retry for topology */ 695 LCB_RETRY_ON_SOCKERR, /**< Select retry for network errors */ 696 LCB_RETRY_ON_VBMAPERR, /**< Select retry for NOT_MY_VBUCKET responses */ 697 698 /** Retry when there is no node for the item. This case is special as the 699 * `cmd` setting is treated as a boolean rather than a bitmask*/ 700 LCB_RETRY_ON_MISSINGNODE, 701 LCB_RETRY_ON_MAX /**<< maximum index */ 702 } lcb_RETRYMODEOPTS; 703 704 typedef enum { 705 /**Don't retry any commands. A command which has been forwarded to 706 * a server and a not-my-vbucket has been received in response for it 707 * will result in a failure.*/ 708 LCB_RETRY_CMDS_NONE = 0, 709 710 /**Only retry simple retrieval operations (excludes touch, 711 * get-and-touch, and get-locked) which may be retried many numbers of times 712 * without risking unintended data manipulation. */ 713 LCB_RETRY_CMDS_GET = 0x01, 714 715 /**Retry operations which may potentially fail because they have been 716 * accepted by a previous server, but will not silently corrupt data. 717 * Such commands include mutation operations containing a CAS.*/ 718 LCB_RETRY_CMDS_SAFE = 0x03, /* Includes 'GET', plus a new flag (e.g. 0x02|0x01) */ 719 720 /**Retry all commands, disregarding any potential unintended receipt of 721 * errors or data mutation.*/ 722 LCB_RETRY_CMDS_ALL = 0x07 /* e.g. 0x01|0x03| NEW FLAG: 0x04 */ 723 } lcb_RETRYCMDOPTS; 724 725 /**@brief Create a retry setting value 726 * @param mode the mode to set (@see lcb_RETRYMODEOPTS) 727 * @param policy the policy determining which commands should be retried 728 * (@see lcb_RETRYCMDOPTS) 729 * @return a value which can be assigned to an `lcb_U32` and passed to 730 * the @ref LCB_CNTL_RETRYMODE setting 731 */ 732 #define LCB_RETRYOPT_CREATE(mode, policy) (((mode) << 16) | policy) 733 734 /** Get mode from retry setting value */ 735 #define LCB_RETRYOPT_GETMODE(u) ((u) >> 16) 736 /** Get policy from retry setting value */ 737 #define LCB_RETRYOPT_GETPOLICY(u) ((u)&0xffff) 738 739 /** 740 * @volatile 741 * 742 * @brief Set retry policies 743 * 744 * This function sets the retry behavior. The retry behavior is the action the 745 * library should take when a command has failed because of a failure which 746 * may be a result of environmental and/or topology issues. In such cases it 747 * may be possible to retry the command internally and have it succeed a second 748 * time without propagating an error back to the application. 749 * 750 * The behavior consists of a _mode_ and _command_ selectors. The _command_ 751 * selector indicates which commands should be retried (and which should be 752 * propagated up to the user) whereas the _mode_ indicates under which 753 * circumstances should the _command_ policy be used. 754 * 755 * Disable retries anywhere: 756 * @code{.c} 757 * for (int ii = 0; ii < LCB_RETRY_ON_MAX; ++ii) { 758 * lcb_U32 val = LCB_RETRYOPT_CREATE(ii, LCB_RETRY_CMDS_NONE); 759 * lcb_error_t err = lcb_cntl(instance, LCB_CNTL_SET, LCB_CNTL_RETRYMODE, &val); 760 * } 761 * @endcode 762 * 763 * Only retry simple GET operations when retry is needed because of topology 764 * changes: 765 * @code{.c} 766 * lcb_U32 val = LCB_RETRYOPT_CREATE(LCB_RETRY_ON_TOPOCHANGE, LCB_RETRY_CMDS_GET); 767 * lcb_cntl(instance, LCB_CNTL_SET, LCB_CNTL_RETRYMODE, &val); 768 * @endcode 769 * 770 * Determine the behavior of the library when a `NOT_MY_VBUCKET` is received: 771 * @code{.c} 772 * lcb_U32 val = LCB_RETRYOPT_CREATE(LCB_RETRY_ON_VBMAPERR, 0); 773 * lcb_cntl(instance, LCB_CNTL_GET, LCB_CNTL_RETRYMODE, &val); 774 * lcb_U32 policy = LCB_RETRYOPT_GETPOLICY(val); 775 * @endcode 776 * 777 * @cntl_arg_both{`lcb_U32 *`} 778 */ 779 #define LCB_CNTL_RETRYMODE 0x24 780 781 /** 782 * @brief Enumeration representing various URL forms to use for the configuration 783 * stream */ 784 typedef enum { 785 /** `/pools/default/b[s]/$bucket`: Introduced in Couchbase Server 2.5 */ 786 LCB_HTCONFIG_URLTYPE_25PLUS = 0x01, 787 788 /** `/pools/default/buckets[Streaming]/$bucket`. */ 789 LCB_HTCONFIG_URLTYPE_COMPAT = 0x02, 790 791 /** Try `25PLUS` first and fallback to `COMPAT` */ 792 LCB_HTCONFIG_URLTYPE_TRYALL = 0x03 793 } lcb_HTCONFIG_URLTYPE; 794 795 /** 796 * @brief Set the URL selection mode. 797 * 798 * The URL type can be a mask of the #lcb_HTCONFIG_URLTYPE constants which 799 * indicate which URLs the HTTP provider should use. 800 * 801 * The default is to use the `25PLUS` URI first, and fallback on the compat uri 802 * if the terse one fails with an HTTP 404 (Not Found). The new-style URI is 803 * considered more efficient on cluster resources and can help the cluster 804 * maintain many more streaming connections than the compat version, however 805 * it is only available in Couchbase Server 2.5 and greater. 806 * 807 * This setting is only used when CCCP is disabled. This will typically be for 808 * older clusters or for memcached buckets. 809 * @cntl_arg_both{`int*` (value is one of @ref lcb_HTCONFIG_URLTYPE)} 810 811 * @volatile Primarily here to support tests and buggy HTTP servers/proxies 812 * which do not like to maintain a connection upon receipt of a 404. 813 */ 814 #define LCB_CNTL_HTCONFIG_URLTYPE 0x25 815 816 /** 817 * Determines whether to run the event loop internally within lcb_destroy() 818 * until no more I/O resources remain for the library. This is usually only 819 * necessary if you are creating a lot of instances and/or are using memory 820 * leak analysis tools. 821 * 822 * @cntl_arg_both{`int*` (as a boolean)} 823 * @see lcb_destroy_async() and lcb_set_destroy_callback() 824 * @volatile 825 */ 826 #define LCB_CNTL_SYNCDESTROY 0x28 827 828 /** 829 * Sets the logging level for the console logger. If a logger is already 830 * initialized (either from the environment, or via lcb_cntl_logger() then 831 * this operation does nothing. 832 * 833 * This is mainly useful for applications which want to proxy the built in 834 * logging options via command line options and the like, rather than setting 835 * it from the environment. 836 * 837 * The argument passed to lcb_cntl() is an integer of 0 until 838 * `LCB_LOG_MAX`, though the actual type is of `lcb_U32` rather than 839 * an enum type #lcb_log_severity_t. 840 * 841 * @cntl_arg_setonly{const lcb_U32 *} 842 * @see LCB_CNTL_LOGGER 843 */ 844 #define LCB_CNTL_CONLOGGER_LEVEL 0x29 845 846 /** 847 * 848 * Sets the output file (as a `FILE*`) for the console logger. Note that 849 * any existing file pointer will be cleared (but not `fclose()`d. 850 * 851 * If used with lcb_cntl_string(), (using the `console_log_file` parameter), 852 * the third argument is taken as the _name_ of a file. Note that the user 853 * is responsible for closing the file. 854 * 855 * This setting does not require a library handle and therefore the first 856 * argument to lcb_cntl() should be `NULL`. 857 * 858 * 859 * @cntl_arg_get_and_set{`FILE**`, `FILE*`} 860 * @see LCB_CNTL_LOGGER 861 * @see LCB_CNTL_CONLOGGER_LEVEL 862 */ 863 #define LCB_CNTL_CONLOGGER_FP 0x3B 864 865 /** 866 * Sets the behavior for reporting network errors. By default network errors 867 * are returned as `LCB_NETWORK_ERROR` return codes for compatibility reasons. 868 * More detailed error codes may be available by enabling this option which will 869 * return appropriate error codes which have a category of 870 * @ref LCB_ERRTYPE_NETWORK 871 * 872 * Using this option means your programming model is centered around the various 873 * LCB_EIF* macros (see <libcouchbase/error.h>) rather than individual codes. 874 * 875 * @cntl_arg_both{int * (As a boolean)} 876 */ 877 #define LCB_CNTL_DETAILED_ERRCODES 0x2A 878 879 /** 880 * 881 * Sets the interval at which the retry queue will attempt to resend a failed 882 * operation. When an operation fails and the retry policy (see 883 * @ref LCB_CNTL_RETRYMODE) allows the operation to be retried, it shall be 884 * placed into a queue, and then be retried within a given interval. 885 * 886 * Setting a high value will be friendlier on the network but also potentially 887 * increase latency, while setting this to a low value may cause unnecessary 888 * network traffic for operations which are not yet ready to be retried. 889 * 890 * @cntl_arg_both{lcb_U32* (microseconds)} 891 * 892 * @see LCB_CNTL_RETRY_BACKOFF 893 */ 894 #define LCB_CNTL_RETRY_INTERVAL 0x2C 895 896 /** 897 * 898 * When an operation has been retried more than once and it has still not 899 * succeeded, the library will attempt to back off for the operation by 900 * scheduling it to be retried in `LCB_CNTL_RETRY_INTEVAL * ${n}` microseconds, 901 * where `${n}` is the factor controlled by this setting. 902 * 903 * @cntl_arg_both{float*} 904 */ 905 #define LCB_CNTL_RETRY_BACKOFF 0x2D 906 907 /** 908 * Whether commands are retried immediately upon receipt of not-my-vbucket 909 * replies. 910 * 911 * Since version 2.4.8, packets by default are retried immediately on a 912 * different node if it had previously failed with a not-my-vbucket 913 * response, and is thus not subject to the @ref LCB_CNTL_RETRY_INTERVAL 914 * and @ref LCB_CNTL_RETRY_BACKOFF settings. Disabling this setting will 915 * restore the older behavior. This may be used in case there are problems 916 * with the default heuristic/retry algorithm. 917 * 918 * @volatile 919 */ 920 #define LCB_CNTL_RETRY_NMV_IMM 0x37 921 922 /** 923 * Set the maximum pool size for pooled http (view request) sockets. This should 924 * be set to 1 (the default) unless you plan to execute concurrent view requests. 925 * You may set this to 0 to disable pooling 926 * 927 * @cntl_arg_both{lcb_SIZE} 928 * @volatile 929 */ 930 #define LCB_CNTL_HTTP_POOLSIZE 0x2E 931 932 /** 933 * Determine whether or not a new configuration should be received when an error 934 * is received over the HTTP API (i.e. via lcb_make_http_request(). 935 * 936 * The default value is true, however you may wish to disable this if you are 937 * expectedly issuing a lot of requests which may result in an error. 938 * 939 * @cntl_arg_both{int (as boolean)} 940 * @uncommitted 941 */ 942 #define LCB_CNTL_HTTP_REFRESH_CONFIG_ON_ERROR 0x2F 943 944 /** 945 * Set the behavior of the lcb_sched_leave() API call. By default the 946 * lcb_sched_leave() will also set up the necessary requirements for flushing 947 * to the network. If this option is off then an explicit call to 948 * lcb_sched_flush() must be performed instead. 949 * 950 * @cntl_arg_both{int (as boolean)} 951 * @volatile 952 */ 953 #define LCB_CNTL_SCHED_IMPLICIT_FLUSH 0x31 954 955 /** 956 * 957 * Request the server to return an additional 16 bytes of data for each 958 * mutation operation. This extra information may help with more reliable 959 * durability polling, but will also increase the size of the response packet. 960 * 961 * This should be set on the instance before issuing lcb_connect(). While this 962 * may also be set after lcb_connect() is called, it will currently only take 963 * effect when a server reconnects (which itself may be undefined). 964 * 965 * @cntl_arg_both{int (as boolean)} 966 */ 967 #define LCB_CNTL_FETCH_MUTATION_TOKENS 0x34 968 969 /** 970 * This setting determines whether the lcb_durability_poll() function will 971 * transparently attempt to use mutation token functionality (rather than checking 972 * the CAS). This option is most useful for older code which does 973 * explicitly use mutation tokens but would like to use its benefits when 974 * ensuring durability constraints are satisfied. 975 * 976 * This option is enabled by default. Users may wish to disable this if they 977 * are performing durability operations against items stored from different 978 * client instances, as this will make use of a client-global state which is 979 * derived on a per-vBucket basis. This means that the last mutation performed 980 * on a given vBucket for the client will be used, which in some cases may be 981 * older or newer than the mutations passed to the lcb_durability_poll() 982 * function. 983 * 984 * @cntl_arg_both{int (as boolean)} 985 * @volatile 986 */ 987 #define LCB_CNTL_DURABILITY_MUTATION_TOKENS 0x35 988 989 /** 990 * This read-only property determines if the mutation token mechanism is supported 991 * on the cluster itself. This will only be accurate once a single operation 992 * has been performed on the cluster - or in other words, once a connection 993 * to a data node has been established for the purposes of normal operations. 994 * 995 * @cntl_arg_getonly{int (as boolean)} 996 * @uncommitted 997 */ 998 #define LCB_CNTL_MUTATION_TOKENS_SUPPORTED 0x38 999 1000 1001 /** 1002 * This setting determines if calls to lcb_wait() and lcb_wait3() will reset 1003 * the timeout of pending operations to the time that lcb_wait() was called, 1004 * rather than having the operation maintain the time of the call which 1005 * scheduled it. If the time between lcb_store3() and family and the lcb_wait() 1006 * functions is long, it is recommended to disable this setting in order to 1007 * avoid prematurely having operations time out. 1008 * 1009 * @cntl_arg_both{int (as boolean)} 1010 * @uncommitted 1011 * 1012 * Use `"readj_wait_tmo"` for the string version 1013 */ 1014 #define LCB_CNTL_RESET_TIMEOUT_ON_WAIT 0x3A 1015 1016 /** 1017 * Clears the internal prepared statement cache for N1QL 1018 * 1019 * This does not take any arguments, and is valid only on @ref LCB_CNTL_SET 1020 * @uncommitted 1021 */ 1022 #define LCB_CNTL_N1QL_CLEARACHE 0x3E 1023 1024 /** 1025 * Sets additional text for negotiation. This allows wrappers or applications 1026 * to add additional identifying information which can then be seen in the 1027 * server logs. 1028 * 1029 * @cntl_arg_get_and_set{`const char**`, `const char*`} 1030 * 1031 * Use `"client_string"` for the string version 1032 */ 1033 #define LCB_CNTL_CLIENT_STRING 0x3F 1034 1035 typedef const char *lcb_BUCKETCRED[2]; 1036 1037 /** 1038 * Set credentials for a bucket. This is used for N1QL and CBFT APIs to allow 1039 * access to multiple buckets. It can also be used to set the password 1040 * of the current bucket when reconnecting (in case it changes). 1041 * 1042 * The format for the credentials is an array of two nul-terminated strings, 1043 * the first refers to the bucket and the second refers to the password. 1044 */ 1045 #define LCB_CNTL_BUCKET_CRED 0x40 1046 1047 /** 1048 * Set the amount of time the client should wait before retrying a 1049 * not-my-vbucket response packet. The default is 100ms. The value should 1050 * be specified in microseconds. 1051 * 1052 * Use `"retry_nmv_interval"` with lcb_cntl_string() 1053 * 1054 * @cntl_arg_both{lcb_U32*} 1055 */ 1056 #define LCB_CNTL_RETRY_NMV_INTERVAL 0x41 1057 1058 /** 1059 * Limit the number of bytes to be read (and thereby processed) during I/O 1060 * read operations. This setting may be useful when the network is faster than 1061 * processing resources. 1062 * 1063 * @note This setting only works for event-style I/O plugins. This means it 1064 * has no effect on completion style plugins such as libuv or Windows IOCP 1065 * 1066 * @cntl_arg_both{lcb_U32*} 1067 */ 1068 #define LCB_CNTL_READ_CHUNKSIZE 0x42 1069 1070 /** 1071 * Enable/Disable the Error Map feature. This is disabled by default. 1072 * Works only on servers which support error map 1073 * 1074 * Use `enable_errmap` in the connection string 1075 * 1076 * @cntl_arg_both{int* (as boolean)} 1077 */ 1078 #define LCB_CNTL_ENABLE_ERRMAP 0x43 1079 1080 /** 1081 * Enable/Disable sending the SELECT_BUCKET command after authentication. 1082 * This is useful to test auth, and should not be set by end-users. 1083 * 1084 * Note that even if this feature is enabled (the default), the client will 1085 * only send `SELECT_BUCKET` if the server indicates that it is supported 1086 * during negotiation. 1087 * 1088 * Use `select_bucket` in the connection string 1089 * 1090 * @cntl_arg_both{int* (as boolean)} 1091 */ 1092 #define LCB_CNTL_SELECT_BUCKET 0x44 1093 1094 /** 1095 * Enable/Disable setting the `TCP_KEEPALIVE` option on created sockets. 1096 * This is enabled by default for I/O backends which support it. 1097 * 1098 * The keepalive interval will be set to the operating system default. 1099 * 1100 * @cntl_arg_both{int* (as boolean)} 1101 */ 1102 #define LCB_CNTL_TCP_KEEPALIVE 0x45 1103 1104 /** 1105 * Set the amount of time to wait in between polling for a new configuration. 1106 * This will have no effect if connected to a Memcached buckets, or using 1107 * HTTP or File-based configurations (see the `bootstrap_on` connection 1108 * string option). 1109 * 1110 * This option facilitates 'fast failover' - in that the client can preemptively 1111 * check for any cluster topology updates before encountering an error. 1112 * 1113 * @cntl_arg_both{lcb_U32*} 1114 * 1115 * The value for this option is a time value. See the top of this header 1116 * in respect to how to specify this. 1117 * 1118 * Using a value of `0` disables this feature. 1119 * 1120 * You can also use `config_poll_interval` in the connection string. 1121 * 1122 * @note 1123 * Background polling is implemented in the library's non-blocking event loop. 1124 * Synchronous clients (i.e. those using `lcb_wait()`) will only be able to 1125 * poll as often as the library's event loop is active. If the library is 1126 * suspended, that is, if not inside an `lcb_wait()` call, the library will 1127 * be unable to do any kind of background polling. 1128 */ 1129 #define LCB_CNTL_CONFIG_POLL_INTERVAL 0x46 1130 1131 /** 1132 * From version 2.7.4, the C library sends a HELLO command before 1133 * authentication. This works on all modern server versions, but may cause 1134 * disconnects on more ancient variants (Couchbase 2.x for example). 1135 * 1136 * This setting will disable the sending of the HELLO command (which older 1137 * servers don't understand anyway). To disable the sending of hello, set this 1138 * value to false. 1139 * 1140 * @cntl_arg_both{int* (as boolean)} 1141 * @committed 1142 * 1143 * You can also use `send_hello=false` in the connection string. 1144 */ 1145 #define LCB_CNTL_SEND_HELLO 0x47 1146 1147 /** 1148 * Once redaction is enabled, anything at ERROR, WARN and INFO will wrap 1149 * sensitive information with special tags, for further processing with the goal 1150 * to remove or encrypt that information. DEBUG or TRACE level logging are 1151 * expected to have specific info. 1152 * 1153 * Use `log_redaction` in the connection string 1154 * 1155 * @cntl_arg_both{int* (as boolean)} 1156 * @committed 1157 */ 1158 #define LCB_CNTL_LOG_REDACTION 0x4c 1159 1160 /** 1161 * Activate/deactivate end-to-end tracing. 1162 * 1163 * Use `enable_tracing` in the connection string 1164 * 1165 * @cntl_arg_both{int* (as boolean)} 1166 * @see lcb-tracing-api 1167 * @committed 1168 */ 1169 #define LCB_CNTL_ENABLE_TRACING 0x4e 1170 1171 typedef enum { 1172 LCBTRACE_THRESHOLD_KV = 0, 1173 LCBTRACE_THRESHOLD_N1QL, 1174 LCBTRACE_THRESHOLD_VIEW, 1175 LCBTRACE_THRESHOLD_FTS, 1176 LCBTRACE_THRESHOLD_ANALYTICS, 1177 LCBTRACE_THRESHOLD__MAX 1178 } lcbtrace_THRESHOLDOPTS; 1179 1180 /** 1181 * Flush interval for orphaned spans queue in default tracer. 1182 * 1183 * This is the time the tracer will wait between repeated attempts 1184 * to flush most recent orphaned spans. 1185 * 1186 * Use `tracing_orphaned_queue_flush_interval` in the connection string 1187 * 1188 * @code{.c} 1189 * lcb_U32 tmo = 10000000; // 10 seconds in microseconds 1190 * lcb_cntl(instance, LCB_CNTL_SET, LCB_CNTL_TRACING_ORPHANED_QUEUE_FLUSH_INTERVAL, &tmo); 1191 * @endcode 1192 * 1193 * @code{.c} 1194 * rv = lcb_cntl_string("tracing_orphaned_queue_flush_interval", "10.0"); 1195 * @endcode 1196 * 1197 * @cntl_arg_both{lcb_U32*} 1198 * @committed 1199 */ 1200 #define LCB_CNTL_TRACING_ORPHANED_QUEUE_FLUSH_INTERVAL 0x4f 1201 1202 /** 1203 * Size of orphaned spans queue in default tracer. 1204 * 1205 * Queues in default tracer has fixed size, and it will remove information about older spans, 1206 * when the limit will be reached before flushing time. 1207 * 1208 * Use `tracing_orphaned_queue_size` in the connection string 1209 * 1210 * @cntl_arg_both{lcb_U32*} 1211 * @committed 1212 */ 1213 #define LCB_CNTL_TRACING_ORPHANED_QUEUE_SIZE 0x50 1214 1215 /** 1216 * Flush interval for spans with total time over threshold in default tracer. 1217 * 1218 * This is the time the tracer will wait between repeated attempts 1219 * to flush threshold queue. 1220 * 1221 * Use `tracing_threshold_queue_flush_interval` in the connection string 1222 * 1223 * @code{.c} 1224 * lcb_U32 tmo = 10000000; // 10 seconds in microseconds 1225 * lcb_cntl(instance, LCB_CNTL_SET, LCB_CNTL_TRACING_THRESHOLD_QUEUE_FLUSH_INTERVAL, &tmo); 1226 * @endcode 1227 * 1228 * @code{.c} 1229 * rv = lcb_cntl_string("tracing_threshold_queue_flush_interval", "10.0"); 1230 * @endcode 1231 * 1232 * @cntl_arg_both{lcb_U32*} 1233 * @committed 1234 */ 1235 #define LCB_CNTL_TRACING_THRESHOLD_QUEUE_FLUSH_INTERVAL 0x51 1236 1237 /** 1238 * Size of threshold queue in default tracer. 1239 * 1240 * Queues in default tracer has fixed size, and it will remove information about older spans, 1241 * when the limit will be reached before flushing time. 1242 * 1243 * Use `tracing_threshold_queue_size` in the connection string 1244 * 1245 * @cntl_arg_both{lcb_U32*} 1246 * @committed 1247 */ 1248 #define LCB_CNTL_TRACING_THRESHOLD_QUEUE_SIZE 0x52 1249 1250 /** 1251 * Minimum time for the tracing span of KV service to be considered by threshold tracer. 1252 * 1253 * Use `tracing_threshold_kv` in the connection string 1254 * 1255 * @cntl_arg_both{lcb_U32*} 1256 * @committed 1257 */ 1258 #define LCB_CNTL_TRACING_THRESHOLD_KV 0x53 1259 1260 /** 1261 * Minimum time for the tracing span of N1QL service to be considered by threshold tracer. 1262 * 1263 * Use `tracing_threshold_n1ql` in the connection string 1264 * 1265 * @cntl_arg_both{lcb_U32*} 1266 * @committed 1267 */ 1268 #define LCB_CNTL_TRACING_THRESHOLD_N1QL 0x54 1269 1270 /** 1271 * Minimum time for the tracing span of VIEW service to be considered by threshold tracer. 1272 * 1273 * Use `tracing_threshold_view` in the connection string 1274 * 1275 * @cntl_arg_both{lcb_U32*} 1276 * @committed 1277 */ 1278 #define LCB_CNTL_TRACING_THRESHOLD_VIEW 0x55 1279 1280 /** 1281 * Minimum time for the tracing span of FTS service to be considered by threshold tracer. 1282 * 1283 * Use `tracing_threshold_fts` in the connection string 1284 * 1285 * @cntl_arg_both{lcb_U32*} 1286 * @committed 1287 */ 1288 #define LCB_CNTL_TRACING_THRESHOLD_FTS 0x56 1289 1290 /** 1291 * Minimum time for the tracing span of ANALYTICS service to be considered by threshold tracer. 1292 * 1293 * Use `tracing_threshold_analytics` in the connection string 1294 * 1295 * @cntl_arg_both{lcb_U32*} 1296 * @committed 1297 */ 1298 #define LCB_CNTL_TRACING_THRESHOLD_ANALYTICS 0x57 1299 1300 /** 1301 * Options for how to handle compression 1302 * 1303 * @committed 1304 */ 1305 typedef enum { 1306 /** Do not perform compression in any direction. Data which is received 1307 * compressed via the server will be indicated as such by having the 1308 * `LCB_VALUE_F_SNAPPYCOMP` flag set in the lcb_GETRESPv0::datatype field */ 1309 LCB_COMPRESS_NONE = 0x00, 1310 1311 /** 1312 * Decompress incoming data, if the data has been compressed at the server. 1313 * If this is set, the `datatype` field in responses will always be stripped 1314 * of the `LCB_VALUE_F_SNAPPYCOMP` flag. 1315 */ 1316 LCB_COMPRESS_IN = 1 << 0, 1317 1318 /** 1319 * Compress outgoing data. Note that if the `datatype` field contains the 1320 * `LCB_VALUE_F_SNAPPYCOMP` flag, then the data will never be compressed 1321 * as it is assumed that it is already compressed. 1322 */ 1323 LCB_COMPRESS_OUT = 1 << 1, 1324 1325 1326 LCB_COMPRESS_INOUT = (LCB_COMPRESS_IN|LCB_COMPRESS_OUT), 1327 1328 /** 1329 * By default the library will send a HELLO command to the server to 1330 * determine whether compression is supported or not. Because commands may 1331 * be pipelined prior to the scheduing of the HELLO command it is possible 1332 * that the first few commands may not be compressed when schedule due to 1333 * the library not yet having negotiated settings with the server. Setting 1334 * this flag will force the client to assume that all servers support 1335 * compression despite a HELLO not having been intially negotiated. 1336 */ 1337 LCB_COMPRESS_FORCE = 1 << 2 1338 } lcb_COMPRESSOPTS; 1339 1340 /** 1341 * @brief Control how the library handles compression and deflation to and from 1342 * the server. 1343 * 1344 * Starting in Couchbase Server 3.0, compression can optionally be applied to 1345 * incoming and outcoming data. For incoming (i.e. `GET` requests) the data 1346 * may be received in compressed format and then allow the client to inflate 1347 * the data upon receipt. For outgoing (i.e. `SET` requests) the data may be 1348 * compressed on the client side and then be stored and recognized on the 1349 * server itself. 1350 * 1351 * The default behavior is to transparently handle compression for both incoming 1352 * and outgoing data. 1353 * 1354 * Note that if the lcb_STORECMDv0::datatype field is set with compression 1355 * flags, the data will _never_ be compressed by the library as this is an 1356 * indication that it is _already_ compressed. 1357 * 1358 * @cntl_arg_both{`int*` (value is one of @ref lcb_COMPRESSOPTS)} 1359 * @committed 1360 */ 1361 #define LCB_CNTL_COMPRESSION_OPTS 0x26 1362 1363 /** 1364 * Minimum size of the document payload to be compressed when compression enabled. 1365 * 1366 * Use `compression_min_size` in the connection string 1367 * 1368 * @cntl_arg_both{lcb_U32*} 1369 * @committed 1370 */ 1371 #define LCB_CNTL_COMPRESSION_MIN_SIZE 0x58 1372 1373 /** 1374 * Minimum compression ratio (compressed / original) of the compressed payload to allow sending it to cluster. 1375 * 1376 * Use `compression_min_ratio` in the connection string 1377 * 1378 * @cntl_arg_both{lcb_U32*} 1379 * @committed 1380 */ 1381 #define LCB_CNTL_COMPRESSION_MIN_RATIO 0x59 1382 1383 1384 /** 1385 * Select type of network (alternative addresses). 1386 * 1387 * Use `network` in the connection string 1388 * 1389 * @cntl_arg_get_and_set{`const char**`, `const char*`} 1390 * 1391 * @uncommitted 1392 */ 1393 #define LCB_CNTL_NETWORK 0x5b 1394 1395 /** 1396 * The amount of time the pool should wait before closing idle connections. 1397 * 1398 * Use `http_pool_timeout` in the connection string 1399 * 1400 * @cntl_arg_both{lcb_U32*} 1401 * @committed 1402 */ 1403 #define LCB_CNTL_HTTP_POOL_TIMEOUT 0x5d 1404 1405 /** 1406 * This is not a command, but rather an indicator of the last item. 1407 * @internal 1408 */ 1409 #define LCB_CNTL__MAX 0x5f 1410 1411 /**@}*/ 1412 1413 #ifdef __cplusplus 1414 } 1415 #endif 1416 1417 #include "cntl-private.h" 1418 1419 #endif /* LCB_CNTL_H */ 1420