Couchbase C Client
2.5.6
|
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... | |
lcb_error_t lcb_http3 | ( | lcb_t | instance, |
const void * | cookie, | ||
const lcb_CMDHTTP * | cmd | ||
) |
instance | the library handle |
cookie | cookie to be associated with the request |
cmd | the command |
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
instance | The handle to lcb |
request | The request handle |
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 |
|
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.
|
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. | |
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.
#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
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