Detailed Description

These functions return status information about the handle, the current connection, and the number of nodes found within the cluster.

See also: lcb_cntl() for more functions to retrieve status info

Functions
int	lcb_is_waiting (lcb_t instance)
	Check if instance is blocked in the event loop. More...

Information about Nodes
enum	lcb_GETNODETYPE
	Type of node to retrieve for the lcb_get_node() function. More...

const char *	lcb_get_node (lcb_t instance, lcb_GETNODETYPE type, unsigned index)
	Return a string of `host:port` for a node of the given type. More...

lcb_S32	lcb_get_num_replicas (lcb_t instance)
	Get the number of the replicas in the cluster. More...

lcb_S32	lcb_get_num_nodes (lcb_t instance)
	Get the number of the nodes in the cluster. More...

const char const	lcb_get_server_list (lcb_t instance)
	Get a list of nodes in the cluster. More...

#define	LCB_GETNODE_UNAVAILABLE
	String constant returned by lcb_get_node() when the LCB_NODE_NEVERNULL flag is specified, and no node can be returned.

Modifying Settings
The lcb_cntl() function and its various helpers are the means by which to modify settings within the library
lcb_error_t	lcb_cntl (lcb_t instance, int mode, int cmd, void *arg)
	This function exposes an ioctl/fcntl-like interface to read and write various configuration properties to and from an lcb_t handle. More...

lcb_error_t	lcb_cntl_string (lcb_t instance, const char key, const char value)
	Alternate way to set configuration settings by passing a string key and value. More...

lcb_error_t	lcb_cntl_setu32 (lcb_t instance, int cmd, lcb_U32 arg)
	Convenience function to set a value as an lcb_U32. More...

lcb_U32	lcb_cntl_getu32 (lcb_t instance, int cmd)
	Retrieve an lcb_U32 setting. More...

int	lcb_cntl_exists (int ctl)
	Determine if a specific control code exists. More...

Function Documentation

const char* lcb_get_node	(	lcb_t	instance,
		lcb_GETNODETYPE	type,
		unsigned	index
	)

Return a string of host:port for a node of the given type.

Parameters

instance	the instance from which to retrieve the node
type	the type of node to return
index	the node number if index is out of bounds it will be wrapped around, thus there is never an invalid value for this parameter

Returns: a string in the form of host:port. If LCB_NODE_NEVERNULL was specified as an option in type then the string constant LCB_GETNODE_UNAVAILABLE is returned. Otherwise NULL is returned if the type is unrecognized or the LCB_NODE_CONNECTED option was specified and no connected node could be found or a memory allocation failed.

Note: The index parameter is ignored if type is LCB_NODE_HTCONFIG|LCB_NODE_CONNECTED as there will always be only a single HTTP bootstrap node.

const char *viewnode = lcb_get_node(instance, LCB_NODE_VIEWS, 0);
// Get the connected REST endpoint:
const char *restnode = lcb_get_node(instance, LCB_NODE_HTCONFIG|LCB_NODE_CONNECTED, 0);
if (!restnode) {
  printf("Instance not connected via HTTP!\n");
}

Iterate over all the data nodes:

unsigned ii;
for (ii = 0; ii < lcb_get_num_servers(instance); ii++) {
  const char *kvnode = lcb_get_node(instance, LCB_NODE_DATA, ii);
  if (kvnode) {
    printf("KV node %s exists at index %u\n", kvnode, ii);
  } else {
    printf("No node for index %u\n", ii);
  }
}

Stability

Committed:

lcb_S32 lcb_get_num_replicas ( lcb_t instance )

Get the number of the replicas in the cluster.

Parameters

instance The handle to lcb

Returns: -1 if the cluster wasn't configured yet, and number of replicas otherwise. This may be 0 if there are no replicas.

Stability

Committed:

lcb_S32 lcb_get_num_nodes ( lcb_t instance )

Get the number of the nodes in the cluster.

Parameters

instance The handle to lcb

Returns: -1 if the cluster wasn't configured yet, and number of nodes otherwise.

Stability

Committed:

const char* const* lcb_get_server_list ( lcb_t instance )

Get a list of nodes in the cluster.

Returns: a NULL-terminated list of 0-terminated strings consisting of node hostnames:admin_ports for the entire cluster. The storage duration of this list is only valid until the next call to a libcouchbase function and/or when returning control to libcouchbase' event loop.

const char * const * curp = lcb_get_server_list(instance);
for (; *curp; curp++) {
  printf("Have node %s\n", *curp);
}

Stability

Committed:

int lcb_is_waiting ( lcb_t instance )

Check if instance is blocked in the event loop.

Parameters

instance the instance to run the event loop for.

Returns: non-zero if nobody is waiting for IO interaction uncommitted

lcb_error_t lcb_cntl	(	lcb_t	instance,
		int	mode,
		int	cmd,
		void *	arg
	)

This function exposes an ioctl/fcntl-like interface to read and write various configuration properties to and from an lcb_t handle.

Parameters

instance	The instance to modify
mode	One of LCB_CNTL_GET (to retrieve a setting) or LCB_CNTL_SET (to modify a setting). Note that not all configuration properties support SET.
cmd	The specific command/property to modify. This is one of the LCB_CNTL_* constants defined in this file. Note that it is safe (and even recommanded) to use the raw numeric value (i.e. to be backwards and forwards compatible with libcouchbase versions), as they are not subject to change.

Using the actual value may be useful in ensuring your application will still compile with an older libcouchbase version (though you may get a runtime error (see return) if the command is not supported

Parameters

arg The argument passed to the configuration handler. The actual type of this pointer is dependent on the command in question. Typically for GET operations, the value of 'arg' is set to the current configuration value; and for SET operations, the current configuration is updated with the contents of *arg.

Returns: LCB_NOT_SUPPORTED if the code is unrecognized LCB_EINVAL if there was a problem with the argument (typically for SET) other error codes depending on the command.

Stability

Committed:

See also: lcb_cntl_setu32(); lcb_cntl_string()

lcb_error_t lcb_cntl_string	(	lcb_t	instance,
		const char *	key,
		const char *	value
	)

Alternate way to set configuration settings by passing a string key and value.

This may be used to provide a simple interface from a command line or higher level language to allow the setting of specific key-value pairs.

The format for the value is dependent on the option passed, the following value types exist:

Timeout. A timeout value can either be specified as fractional seconds ("1.5" for 1.5 seconds), or in microseconds ("1500000").
Number. This is any valid numerical value. This may be signed or unsigned depending on the setting.
Boolean. This specifies a boolean. A true value is either a positive numeric value (i.e. "1") or the string "true". A false value is a zero (i.e. "0") or the string "false".
Float. This is like a Number, but also allows fractional specification, e.g. "2.4".

Code	Name	Type
LCB_CNTL_OP_TIMEOUT	`"operation_timeout"`	Timeout
LCB_CNTL_VIEW_TIMEOUT	`"view_timeout"`	Timeout
LCB_CNTL_DURABILITY_TIMEOUT	`"durability_timeout"`	Timeout
LCB_CNTL_DURABILITY_INTERVAL	`"durability_interval"`	Timeout
LCB_CNTL_HTTP_TIMEOUT	`"http_timeout"`	Timeout
LCB_CNTL_RANDOMIZE_BOOTSTRAP_HOSTS	`"randomize_nodes"`	Boolean
LCB_CNTL_CONFERRTHRESH	`"error_thresh_count"`	Number (Positive)
LCB_CNTL_CONFDELAY_THRESH	`"error_thresh_delay"`	Timeout
LCB_CNTL_CONFIGURATION_TIMEOUT	`"config_total_timeout"`	Timeout
LCB_CNTL_CONFIG_NODE_TIMEOUT	`"config_node_timeout"`	Timeout
LCB_CNTL_CONFIGCACHE	`"config_cache"`	Path
LCB_CNTL_DETAILED_ERRCODES	`"detailed_errcodes"`	Boolean
LCB_CNTL_HTCONFIG_URLTYPE	`"http_urlmode"`	Number (values are the constant values)
LCB_CNTL_RETRY_BACKOFF	`"retry_backoff"`	Float
LCB_CNTL_HTTP_POOLSIZE	`"http_poolsize"`	Number
LCB_CNTL_VBGUESS_PERSIST	`"vbguess_persist"`	Boolean

Stability

Committed:

Note, the actual API call is considered committed and will not disappear, however the existence of the various string settings are dependendent on the actual settings they map to. It is recommended that applications use the numerical lcb_cntl() as the string names are subject to change.

See also: lcb_cntl(); lcb-cntl-settings

lcb_error_t lcb_cntl_setu32	(	lcb_t	instance,
		int	cmd,
		lcb_U32	arg
	)

Convenience function to set a value as an lcb_U32.

Parameters

instance
cmd	setting to modify
arg	the new value

Returns: see lcb_cntl() for details

Stability

Committed:

lcb_U32 lcb_cntl_getu32	(	lcb_t	instance,
		int	cmd
	)

Retrieve an lcb_U32 setting.

Parameters

instance
cmd	setting to retrieve

Returns: the value.

Warning: This function does not return an error code. Ensure that the cntl is correct for this version, or use lcb_cntl() directly.

Stability

Committed:

int lcb_cntl_exists ( int ctl )

Determine if a specific control code exists.

Parameters

ctl	the code to check for

Returns: 0 if it does not exist, nonzero if it exists.

Enumeration Type Documentation

enum lcb_GETNODETYPE

Type of node to retrieve for the lcb_get_node() function.

Enumerator
LCB_NODE_HTCONFIG	Get an HTTP configuration (Rest API) node.
LCB_NODE_DATA	Get a data (memcached) node.
LCB_NODE_VIEWS	Get a view (CAPI) node.
LCB_NODE_CONNECTED	Only return a node which is connected, or a node which is known to be up.
LCB_NODE_NEVERNULL	Specifying this flag adds additional semantics which instruct the library to search additional resources to return a host, and finally, if no host can be found, return the string constant LCB_GETNODE_UNAVAILABLE.
LCB_NODE_HTCONFIG_CONNECTED	Equivalent to `LCB_NODE_HTCONFIG\|LCB_NODE_CONNECTED`
LCB_NODE_HTCONFIG_ANY	Equivalent to `LCB_NODE_HTCONFIG\|LCB_NODE_NEVERNULL`. When this is passed, some additional attempts may be made by the library to return any kind of host, including searching the initial list of hosts passed to the lcb_create() function.

Detailed Description

Functions

Information about Nodes

Modifying Settings

Function Documentation

Enumeration Type Documentation