Couchbase C Client  2.9.4
Asynchronous C Client for Couchbase
Cluster Information

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

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...
 
const char * lcb_get_keynode (lcb_t instance, const void *key, size_t nkey)
 
Get the target server for a given key. 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...
 
void lcb_dump (lcb_t instance, FILE *fp, lcb_U32 flags)
 
Write a textual dump to a file. More...
 

Macros

#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.
 

Enumerations

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

Function Documentation

◆ lcb_get_node()

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
instancethe instance from which to retrieve the node
typethe type of node to return
indexthe 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_get_keynode()

const char* lcb_get_keynode ( lcb_t  instance,
const void *  key,
size_t  nkey 
)


Get the target server for a given key.

Stability
Committed:

This is a convenience function wrapping around the vBucket API which allows you to retrieve the target node (the node which will be contacted) when performing KV operations involving the key.

Parameters
instancethe instance
keythe key to use
nkeythe length of the key
Returns
a string containing the hostname, or NULL on error.

Since this is a convenience function, error details are not contained here in favor of brevity. Use the full vBucket API for more powerful functions.

◆ lcb_get_num_replicas()

lcb_S32 lcb_get_num_replicas ( lcb_t  instance)


Get the number of the replicas in the cluster

Parameters
instanceThe 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_get_num_nodes()

lcb_S32 lcb_get_num_nodes ( lcb_t  instance)


Get the number of the nodes in the cluster

Parameters
instanceThe handle to lcb
Returns
-1 if the cluster wasn't configured yet, and number of nodes otherwise.
Stability
Committed:
Examples:
example/observe/observe.c.

◆ lcb_get_server_list()

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:

◆ lcb_dump()

void lcb_dump ( lcb_t  instance,
FILE *  fp,
lcb_U32  flags 
)


Write a textual dump to a file.

Stability
Volatile:

This function will inspect the various internal structures of the current client handle (indicated by instance) and write the state information to the file indicated by fp.

Parameters
instancethe handle to dump
fpthe file to which the dump should be written
flagsa set of modifiers (of lcb_DUMPFLAGS) indicating what information to dump. Note that a standard set of information is always dumped, but by default more verbose information is hidden, and may be enabled with these flags.

Enumeration Type Documentation

◆ 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.