Couchbase C Client  2.10.7
Asynchronous C Client for Couchbase
HTTP Client

Detailed Description

Access Couchbase HTTP APIs.

The low-level HTTP client may be used to access various HTTP-based Couchbase APIs.

Note that existing higher level APIs can be used for N1QL queries (see N1QL/Analytics) and MapReduce view queries (see Views (Map-Reduce))

Functions

lcb_error_t lcb_http3 (lcb_t instance, const void *cookie, const lcb_CMDHTTP *cmd)
 
void lcb_cancel_http_request (lcb_t instance, lcb_http_request_t request)
 Cancel ongoing HTTP request. More...
 

Macros

#define LCB_CMDHTTP_F_STREAM
 Command flag for HTTP to indicate that the callback is to be invoked multiple times for each new chunk of incoming data. More...
 
#define LCB_CMDHTTP_F_CASTMO
 
#define LCB_CMDHTTP_F_NOUPASS
 

Enumerations

enum  lcb_http_type_t
 The type of HTTP request to execute. More...
 
enum  lcb_http_method_t
 HTTP Request method enumeration These just enumerate the various types of HTTP request methods supported. More...
 

Function Documentation

◆ lcb_http3()

lcb_error_t lcb_http3 ( lcb_t  instance,
const void *  cookie,
const lcb_CMDHTTP cmd 
)
Stability
Committed:
Issue an HTTP API request.
Parameters
instancethe library handle
cookiecookie to be associated with the request
cmdthe command
Returns
LCB_SUCCESS if the request was scheduled successfully.
Simple Response
void http_callback(lcb_t, int, const lcb_RESPBASE *rb)
{
const lcb_RESPHTTP *resp = (const lcb_RESPHTTP *)rb;
if (resp->rc != LCB_SUCCESS) {
printf("I/O Error for HTTP: %s\n", lcb_strerror(NULL, resp->rc));
return;
}
printf("Got HTTP Status: %d\n", resp->htstatus);
printf("Got paylod: %.*s\n", (int)resp->nbody, resp->body);
const char **hdrp = resp->headers;
while (*hdrp != NULL) {
printf("%s: %s\n", hdrp[0], hdrp[1]);
hdrp += 2;
}
}
Streaming Response
If the LCB_CMDHTTP_F_STREAM flag is set in lcb_CMDHTTP::cmdflags then the response callback is invoked multiple times as data arrives off the socket.
void http_strm_callback(lcb_t, int, const lcb_RESPBASE *rb)
{
const lcb_RESPHTTP *resp = (const lcb_RESPHTTP *)resp;
if (resp->rflags & LCB_RESP_F_FINAL) {
if (resp->rc != LCB_SUCCESS) {
// ....
}
const char **hdrp = resp->headers;
// ...
} else {
handle_body(resp->body, resp->nbody);
}
}
Connection Reuse
The library will attempt to reuse connections for frequently contacted hosts. By default the library will keep one idle connection to each host for a maximum of 10 seconds. The number of open idle HTTP connections can be controlled with LCB_CNTL_HTTP_POOLSIZE.
Examples
example/subdoc/subdoc-xattrs.c.

◆ lcb_cancel_http_request()

void lcb_cancel_http_request ( lcb_t  instance,
lcb_http_request_t  request 
)

Cancel ongoing HTTP request.

This API will stop the current request. Any pending callbacks will not be invoked any any pending data will not be delivered. Useful for a long running request which is no longer needed

Parameters
instanceThe handle to lcb
requestThe request handle
Stability
Committed:
Example
lcb_CMDHTTP htcmd = { 0 };
populate_htcmd(&htcmd); // dummy function
lcb_http_request_t reqhandle;
htcmd.reqhandle = &reqhandle;
lcb_http3(instance, cookie, &htcmd);
do_stuff();
lcb_cancel_http_request(instance, reqhandle);

Data Structure Documentation

◆ lcb_CMDHTTP

struct lcb_CMDHTTP

Structure for performing an HTTP request.

Note that the key and nkey fields indicate the path for the API

Examples
example/subdoc/subdoc-xattrs.c.
Data Fields
lcb_U32 cmdflags Common flags for the command.

These modify the command itself. Currently the lower 16 bits of this field are reserved, and the higher 16 bits are used for individual commands.

lcb_U32 exptime Specify the expiration time.

This is either an absolute Unix time stamp or a relative offset from now, in seconds. If the value of this number is greater than the value of thirty days in seconds, then it is a Unix timestamp. This field is used in mutation operations (lcb_store3()) to indicate the lifetime of the item. It is used in lcb_get3() with the lcb_CMDGET::lock option to indicate the lock expiration itself.

lcb_U64 cas The known CAS of the item.

This is passed to mutation to commands to ensure the item is only changed if the server-side CAS value matches the one specified here. For other operations (such as lcb_CMDENDURE) this is used to ensure that the item has been persisted/replicated to a number of servers with the value specified here.

lcb_KEYBUF key The key for the document itself.

This should be set via LCB_CMD_SET_KEY()

lcb_KEYBUF _hashkey
Stability
Volatile:
lcb_http_type_t type Type of request to issue.

LCB_HTTP_TYPE_VIEW will issue a request against a random node's view API. LCB_HTTP_TYPE_MANAGEMENT will issue a request against a random node's administrative API, and LCB_HTTP_TYPE_RAW will issue a request against an arbitrary host.

lcb_http_method_t method HTTP Method to use.
const char * body If the request requires a body (e.g.

PUT or POST) then it will go here. Be sure to indicate the length of the body too.

lcb_SIZE nbody Length of the body for the request.
lcb_http_request_t * reqhandle If non-NULL, will be assigned a handle which may be used to subsequently cancel the request.
const char * content_type For views, set this to application/json
const char * username Username to authenticate with, if left empty, will use the credentials passed to lcb_create()
const char * password Password to authenticate with, if left empty, will use the credentials passed to lcb_create()
const char * host If set, this must be a string in the form of http://host:port.

Should only be used for raw requests.

◆ lcb_RESPHTTP

struct lcb_RESPHTTP

Structure for HTTP responses.

Note that rc being LCB_SUCCESS does not always indicate that the HTTP request itself was successful. It only indicates that the outgoing request was submitted to the server and the client received a well-formed HTTP response. Check the #hstatus field to see the actual HTTP-level status code received.

Data Fields
void * cookie Application-defined pointer passed as the cookie parameter when scheduling the command.


const void * key Key for request.
lcb_SIZE nkey Size of key.
lcb_CAS cas CAS for response (if applicable)
lcb_error_t rc Status code.
lcb_U16 version ABI version for response.
lcb_U16 rflags Response specific flags.

see lcb_RESPFLAGS

short htstatus HTTP status code.

The value is only valid if rc is LCB_SUCCESS (if rc is not LCB_SUCCESS then this field may be 0 as the response may have not been read/sent)

const char *const * headers List of key-value headers.

This field itself may be NULL. The list is terminated by a NULL pointer to indicate no more headers.

const void * body If LCB_CMDHTTP_F_STREAM is true, contains the current chunk of response content.

Otherwise, contains the entire response body.

lcb_SIZE nbody Length of buffer in body.
lcb_http_request_t _htreq
Stability
Internal:

Macro Definition Documentation

◆ LCB_CMDHTTP_F_STREAM

#define LCB_CMDHTTP_F_STREAM

Command flag for HTTP to indicate that the callback is to be invoked multiple times for each new chunk of incoming data.

Once the entire body have been received, the callback will be invoked once more with the LCB_RESP_F_FINAL flag (in lcb_RESPHTTP::rflags) and an empty content.

To use streaming requests, this flag should be set in the lcb_CMDHTTP::cmdflags field

◆ LCB_CMDHTTP_F_CASTMO

#define LCB_CMDHTTP_F_CASTMO
Stability
Internal:
If specified, the lcb_CMDHTTP::cas field becomes the timeout for this specific request.

◆ LCB_CMDHTTP_F_NOUPASS

#define LCB_CMDHTTP_F_NOUPASS
Stability
Internal:
Do not inject authentication header into the request.

Enumeration Type Documentation

◆ lcb_http_type_t

The type of HTTP request to execute.

Enumerator
LCB_HTTP_TYPE_VIEW 

Execute a request against the bucket.

The handle must be of LCB_TYPE_BUCKET and must be connected.

LCB_HTTP_TYPE_MANAGEMENT 

Execute a management API request.

The credentials used will match those passed during the instance creation time. Thus is the instance type is LCB_TYPE_BUCKET then only bucket-level credentials will be used.

LCB_HTTP_TYPE_RAW 

Execute an arbitrary request against a host and port.

LCB_HTTP_TYPE_N1QL 

Execute an N1QL Query.

LCB_HTTP_TYPE_FTS 

Search a fulltext index.

LCB_HTTP_TYPE_CBAS 

Execute an Analytics Query.

LCB_HTTP_TYPE_PING 

Special pseudo-type, for ping endpoints in various services.

Behaves like RAW (the lcb_ping3() function will setup custom path), but supports Keep-Alive

◆ lcb_http_method_t

HTTP Request method enumeration These just enumerate the various types of HTTP request methods supported.

Refer to the specific cluster or view API to see which method is appropriate for your request

lcb_RESPHTTP::rflags
lcb_U16 rflags
Response specific flags.
Definition: couchbase.h:2787
lcb_strerror
const char * lcb_strerror(lcb_t instance, lcb_error_t error)
Get a textual descrtiption for the given error code.
lcb_http3
lcb_error_t lcb_http3(lcb_t instance, const void *cookie, const lcb_CMDHTTP *cmd)
lcb_RESPHTTP::body
const void * body
If LCB_CMDHTTP_F_STREAM is true, contains the current chunk of response content.
Definition: couchbase.h:2799
lcb_RESPHTTP::headers
const char *const * headers
List of key-value headers.
Definition: couchbase.h:2795
lcb_RESPHTTP::htstatus
short htstatus
HTTP status code.
Definition: couchbase.h:2791
lcb_RESPHTTP::rc
lcb_error_t rc
Status code.
Definition: couchbase.h:2787
lcb_CMDHTTP::reqhandle
lcb_http_request_t * reqhandle
If non-NULL, will be assigned a handle which may be used to subsequently cancel the request.
Definition: couchbase.h:2760
lcb_RESPHTTP::nbody
lcb_SIZE nbody
Length of buffer in body.
Definition: couchbase.h:2801
lcb_t
struct lcb_st * lcb_t
Definition: couchbase.h:41
lcb_cancel_http_request
void lcb_cancel_http_request(lcb_t instance, lcb_http_request_t request)
Cancel ongoing HTTP request.
LCB_SUCCESS
@ LCB_SUCCESS
Success.
Definition: error.h:478
lcb_RESPHTTP
Structure for HTTP responses.
Definition: couchbase.h:2786
lcb_RESPBASE
Base response structure for callbacks.
Definition: couchbase.h:625
lcb_CMDHTTP
Structure for performing an HTTP request.
Definition: couchbase.h:2742
LCB_RESP_F_FINAL
@ LCB_RESP_F_FINAL
No more responses are to be received for this request.
Definition: couchbase.h:658