Couchbase C Client  2.7.7
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) 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
 If specified, the lcb_CMDHTTP::cas field becomes the timeout for this specific request.
 
#define LCB_CMDHTTP_F_NOUPASS
 Do not inject authentication header into the request.
 

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.

◆ 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

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. More...
 
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. More...
 
short htstatus
 HTTP status code. More...
 
const char *const * headers
 List of key-value headers. More...
 
const void * body
 If LCB_CMDHTTP_F_STREAM is true, contains the current chunk of response content. More...
 
lcb_SIZE nbody
 Length of buffer in body.
 

Field Documentation

◆ cookie

void* cookie

Application-defined pointer passed as the cookie parameter when scheduling the command.

◆ rflags

lcb_U16 rflags

Response specific flags.

see lcb_RESPFLAGS

◆ htstatus

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)

◆ headers

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.

◆ body

const void* body

If LCB_CMDHTTP_F_STREAM is true, contains the current chunk of response content.

Otherwise, contains the entire response body.

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

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_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