Find file
Fetching contributors…
Cannot retrieve contributors at this time
74 lines (59 sloc) 3.58 KB
// TDC.h
// TouchDB
// Created by Jens Alfke on 3/5/12.
// Copyright (c) 2012 Couchbase, Inc. All rights reserved.
#ifndef _TDC_
#define _TDC_
#include <sys/types.h>
#include <stdbool.h>
/* Simple ANSI C API to TouchDB. */
/** C structure describing a MIME entity, used for requests and responses.
This structure and the data it points to should be considered read-only.
It should be created only by calling TDCMIMECreate, and freed only by calling TDCMIMEFree. */
typedef struct {
unsigned headerCount;
const char** headerNames;
const char** headerValues;
size_t contentLength;
const void* content;
void* _private;
/** Allocates a TDCMIME structure on the heap, copying the headers and (optionally) the content.
@param headerCount The number of MIME headers.
@param headerNames An array of headerCount pointers to C strings, each a header name. (May be NULL if the headerCount is 0.)
@param headerValues An array of headerCount pointers to C strings, each a header value corresponding to the header name with the same index. (May be NULL if the headerCount is 0.)
@param contentLength The length of the content in bytes.
@param content The content itself (may be NULL if the conten length is 0.)
@param copyContent If true, the content will be copied into a new heap block owned by the TDCMIME structure. If false, the content pointer will be adopted by the TDCMIME and will be freed when the TDCMIME itself is freed (this implies the caller must have used malloc to allocate it.) If allocation fails, the content block is still valid and the caller is responsible for freeing it.
@return The allocated TDCMIME structure, or NULL if memory allocation failed.
TDCMIME* TDCMIMECreate(unsigned headerCount,
const char** headerNames,
const char** headerValues,
size_t contentLength,
const void* content,
bool copyContent);
/** Frees a TDCMIME structure and all the data it points to.
The structure *must* have been allocated by calling TDCMIMECreate.
It is a safe no-op to pass NULL to this function.
@param The TDCMIME pointer to free, or NULL. */
void TDCMIMEFree(TDCMIME* mime);
/** Initializes the TDC API.
This must be called once (and only once), before the first call to TDCSendRequest.
@param dataDirectoryPath The base directory in which TouchDB should store data files. This directory's parent directory must exist and be writeable. */
void TDCInitialize(const char* dataDirectoryPath);
/** Synchronously calls a TouchDB REST API method.
This method is thread-safe: it may be called from any thread and from multiple threads simultaneously. This allows the application to implement asynchronous operations.
@param method The HTTP method -- "GET", "PUT", etc.
@param url The target URL. The scheme and host are ignored. We suggest using "touchdb:///".
@param headersAndBody The request headers and body. TouchDB takes ownership of this; the caller should NOT use, modify or free it after the call.
@param outResponse On return, may be filled in with a pointer to an allocated TDCMIME structure. Caller is responsible for freeing this via TDCMIMEFree. The value may be filled in as NULL if there is no meaningful data to return, as in some error conditions.
@return The HTTP status code of the response. */
int TDCSendRequest(const char* method,
const char* url,
TDCMIME* headersAndBody,
TDCMIME** outResponse);
#endif // _TDC_