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.

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_error_t lcb_http3	(	lcb_t	instance,
		const void *	cookie,
		const lcb_CMDHTTP *	cmd
	)

Stability

Committed:

Issue an HTTP API request.

Parameters

instance	the library handle
cookie	cookie to be associated with the request
cmd	the 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.

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

instance	The handle to lcb
request	The 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

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.

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

void* cookie

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

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.

Macro Definition Documentation

#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

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

enum 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