Objectively
Object oriented framework for C.
Loading...
Searching...
No Matches
RESTClient Struct Reference

#include <RESTClient.h>

Overview

An HTTP REST client backed by URLSession.

RESTClient provides synchronous and asynchronous HTTP verb methods (HEAD, GET, OPTIONS, POST, PATCH, PUT, DELETE) dealing in Data * request and response bodies. JSON marshalling is the caller's responsibility, typically via JSONContext. Every verb accepts an optional headers array for attaching additional request headers.

Definition at line 62 of file RESTClient.h.

Inheritance diagram for RESTClient:
Object

Properties

Object object
 The superclass.
 
URLSession * session
 The URLSession backing this client.
 
- Properties inherited from Object
Class * clazz
 Every instance of Object begins with a pointer to its Class.
 
unsigned int magic
 A header to allow introspection of Object types.
 

Methods

Class * _RESTClient (void)
 The RESTClient archetype.
 
int del (RESTClient *, const char *, const char **, Data **)
 Synchronously performs an HTTP DELETE request.
 
void delAsync (RESTClient *, const char *, const char **, RESTClientCompletion, void *)
 Asynchronously performs an HTTP DELETE request.
 
int get (RESTClient *, const char *, const char **, Data **)
 Synchronously performs an HTTP GET request.
 
void getAsync (RESTClient *, const char *, const char **, RESTClientCompletion, void *)
 Asynchronously performs an HTTP GET request.
 
int head (RESTClient *, const char *, const char **)
 Synchronously performs an HTTP HEAD request.
 
void headAsync (RESTClient *, const char *, const char **, RESTClientCompletion, void *)
 Asynchronously performs an HTTP HEAD request.
 
RESTClient * init (RESTClient *)
 Initializes this RESTClient with the shared URLSession.
 
RESTClient * initWithSession (RESTClient *, URLSession *)
 Initializes this RESTClient with the specified URLSession.
 
int options (RESTClient *, const char *, const char **, Data **)
 Synchronously performs an HTTP OPTIONS request.
 
void optionsAsync (RESTClient *, const char *, const char **, RESTClientCompletion, void *)
 Asynchronously performs an HTTP OPTIONS request.
 
int patch (RESTClient *, const char *, const Data *, const char **, Data **)
 Synchronously performs an HTTP PATCH request.
 
void patchAsync (RESTClient *, const char *, const Data *, const char **, RESTClientCompletion, void *)
 Asynchronously performs an HTTP PATCH request.
 
int post (RESTClient *, const char *, const Data *, const char **, Data **)
 Synchronously performs an HTTP POST request.
 
void postAsync (RESTClient *, const char *, const Data *, const char **, RESTClientCompletion, void *)
 Asynchronously performs an HTTP POST request.
 
int put (RESTClient *, const char *, const Data *, const char **, Data **)
 Synchronously performs an HTTP PUT request.
 
void putAsync (RESTClient *, const char *, const Data *, const char **, RESTClientCompletion, void *)
 Asynchronously performs an HTTP PUT request.
 
RESTClient * sharedInstance (void)
 
- Methods inherited from Object
Class * _Object (void)
 The Object archetype.
 
Object * copy (const Object *self)
 Creates a shallow copy of this Object.
 
void dealloc (Object *self)
 Frees all resources held by this Object.
 
String * description (const Object *self)
 
int hash (const Object *self)
 
Object * init (Object *self)
 Initializes this Object.
 
bool isEqual (const Object *self, const Object *other)
 Tests equality of the other Object.
 
bool isKindOfClass (const Object *self, const Class *clazz)
 Tests for Class hierarchy membership.
 

Protected Attributes

RESTClientInterface * interface [0]
 The interface type.
 
- Protected Attributes inherited from Object
ObjectInterface * interface [0]
 The interface type.
 

Property Details

◆ interface

RESTClientInterface* RESTClient::interface[0]
protected

The interface type.

Definition at line 73 of file RESTClient.h.

◆ object

Object RESTClient::object

The superclass.

Definition at line 67 of file RESTClient.h.

◆ session

URLSession* RESTClient::session

The URLSession backing this client.

Definition at line 78 of file RESTClient.h.

Method Details

◆ _RESTClient()

Class * _RESTClient ( void  )

The RESTClient archetype.

Returns
The RESTClient Class.

Definition at line 361 of file RESTClient.c.

361 {
362
363 static Class *clazz;
364 static Once once;
365
366 do_once(&once, {
367 clazz = _initialize(&(const ClassDef) {
368 .name = "RESTClient",
369 .superclass = _Object(),
370 .instanceSize = sizeof(RESTClient),
371 .interfaceSize = sizeof(RESTClientInterface),
372 .initialize = initialize,
373 .destroy = destroy,
374 });
375 });
376
377 return clazz;
378}
static void initialize(Class *clazz)
Definition Array.c:710
static void destroy(Class *clazz)
Definition Boole.c:102
Class * _initialize(const ClassDef *def)
Initializes the given Class.
Definition Class.c:151
long Once
The Once type.
Definition Once.h:37
#define do_once(once, block)
Executes the given block at most one time.
Definition Once.h:43
ClassDefs are passed to _initialize via an archetype to initialize a Class.
Definition Class.h:41
The runtime representation of a Class.
Definition Class.h:90
Class * clazz
Every instance of Object begins with a pointer to its Class.
Definition Object.h:55
Class * _Object(void)
The Object archetype.
Definition Object.c:136
An HTTP REST client backed by URLSession.
Definition RESTClient.h:62

◆ del()

int del ( RESTClient *  self,
const char *  url,
const char **  headers,
Data **  data 
)

Synchronously performs an HTTP DELETE request.

Parameters
selfThe RESTClient.
urlThe URL string.
headersA NULL-terminated array of alternating field/value C strings (e.g. { "X-Field", "value", NULL }) to add to the request, or NULL for none.
dataOptionally receives the retained response body. Caller must release.
Returns
The HTTP response status code, or 0 if the transfer failed or was cancelled.

Definition at line 173 of file RESTClient.c.

173 {
174 return request(self, HTTP_DELETE, url, NULL, headers, data);
175}
static Data * data(void)
Definition Data.c:286
static int request(RESTClient *self, HTTPMethod method, const char *url_string, const Data *body, const char **headers, Data **out_data)
Definition RESTClient.c:62
@ HTTP_DELETE
Definition URLRequest.h:50

◆ delAsync()

void delAsync ( RESTClient *  self,
const char *  url,
const char **  headers,
RESTClientCompletion  completion,
void *  userData 
)

Asynchronously performs an HTTP DELETE request.

Parameters
selfThe RESTClient.
urlThe URL string.
headersA NULL-terminated array of alternating field/value C strings (e.g. { "X-Field", "value", NULL }) to add to the request, or NULL for none.
completionThe completion handler.
userDataUser data passed through to completion.

Definition at line 181 of file RESTClient.c.

182 {
183 requestAsync(self, HTTP_DELETE, url, NULL, headers, completion, userData);
184}
static void requestAsync(RESTClient *self, HTTPMethod method, const char *url_string, const Data *body, const char **headers, RESTClientCompletion completion, void *userData)
Definition RESTClient.c:111

◆ get()

int get ( RESTClient *  self,
const char *  url,
const char **  headers,
Data **  data 
)

Synchronously performs an HTTP GET request.

Parameters
selfThe RESTClient.
urlThe URL string.
headersA NULL-terminated array of alternating field/value C strings (e.g. { "X-Field", "value", NULL }) to add to the request, or NULL for none.
dataOptionally receives the retained response body. Caller must release.
Returns
The HTTP response status code, or 0 if the transfer failed or was cancelled.

Definition at line 190 of file RESTClient.c.

190 {
191 return request(self, HTTP_GET, url, NULL, headers, data);
192}
@ HTTP_GET
Definition URLRequest.h:46

◆ getAsync()

void getAsync ( RESTClient *  self,
const char *  url,
const char **  headers,
RESTClientCompletion  completion,
void *  userData 
)

Asynchronously performs an HTTP GET request.

Parameters
selfThe RESTClient.
urlThe URL string.
headersA NULL-terminated array of alternating field/value C strings (e.g. { "X-Field", "value", NULL }) to add to the request, or NULL for none.
completionThe completion handler.
userDataUser data passed through to completion.

Definition at line 198 of file RESTClient.c.

199 {
200 requestAsync(self, HTTP_GET, url, NULL, headers, completion, userData);
201}

◆ head()

int head ( RESTClient *  self,
const char *  url,
const char **  headers 
)

Synchronously performs an HTTP HEAD request.

Parameters
selfThe RESTClient.
urlThe URL string.
headersA NULL-terminated array of alternating field/value C strings (e.g. { "X-Field", "value", NULL }) to add to the request, or NULL for none.
Returns
The HTTP response status code, or 0 if the transfer failed or was cancelled.

Definition at line 207 of file RESTClient.c.

207 {
208 return request(self, HTTP_HEAD, url, NULL, headers, NULL);
209}
@ HTTP_HEAD
Definition URLRequest.h:44

◆ headAsync()

void headAsync ( RESTClient *  self,
const char *  url,
const char **  headers,
RESTClientCompletion  completion,
void *  userData 
)

Asynchronously performs an HTTP HEAD request.

Parameters
selfThe RESTClient.
urlThe URL string.
headersA NULL-terminated array of alternating field/value C strings (e.g. { "X-Field", "value", NULL }) to add to the request, or NULL for none.
completionThe completion handler.
userDataUser data passed through to completion.

Definition at line 215 of file RESTClient.c.

216 {
217 requestAsync(self, HTTP_HEAD, url, NULL, headers, completion, userData);
218}

◆ init()

RESTClient * init ( RESTClient *  self)

Initializes this RESTClient with the shared URLSession.

Parameters
selfThe RESTClient.
Returns
The initialized RESTClient, or NULL on error.

Definition at line 224 of file RESTClient.c.

224 {
225 return $(self, initWithSession, $$(URLSession, sharedInstance));
226}
RESTClient * initWithSession(RESTClient *, URLSession *)
Initializes this RESTClient with the specified URLSession.
Definition RESTClient.c:232
RESTClient * sharedInstance(void)
Definition Log.c:212
A management context for loading resources via URLs.
Definition URLSession.h:59

◆ initWithSession()

RESTClient * initWithSession ( RESTClient *  self,
URLSession *  session 
)

Initializes this RESTClient with the specified URLSession.

Parameters
selfThe RESTClient.
sessionThe URLSession.
Returns
The initialized RESTClient, or NULL on error.

Definition at line 232 of file RESTClient.c.

232 {
233
234 self = (RESTClient *) super(Object, self, init);
235 if (self) {
236 assert(session);
237 self->session = retain(session);
238 }
239 return self;
240}
ident retain(ident obj)
Atomically increment the given Object's reference count.
Definition Class.c:372
#define super(type, obj, method,...)
Object is the root Class of The Objectively Class hierarchy.
Definition Object.h:46
URLSession * session
The URLSession backing this client.
Definition RESTClient.h:78
RESTClient * init(RESTClient *)
Initializes this RESTClient with the shared URLSession.
Definition RESTClient.c:224

◆ options()

int options ( RESTClient *  self,
const char *  url,
const char **  headers,
Data **  data 
)

Synchronously performs an HTTP OPTIONS request.

Parameters
selfThe RESTClient.
urlThe URL string.
headersA NULL-terminated array of alternating field/value C strings (e.g. { "X-Field", "value", NULL }) to add to the request, or NULL for none.
dataOptionally receives the retained response body. Caller must release.
Returns
The HTTP response status code, or 0 if the transfer failed or was cancelled.

Definition at line 246 of file RESTClient.c.

246 {
247 return request(self, HTTP_OPTIONS, url, NULL, headers, data);
248}
@ HTTP_OPTIONS
Definition URLRequest.h:45

◆ optionsAsync()

void optionsAsync ( RESTClient *  self,
const char *  url,
const char **  headers,
RESTClientCompletion  completion,
void *  userData 
)

Asynchronously performs an HTTP OPTIONS request.

Parameters
selfThe RESTClient.
urlThe URL string.
headersA NULL-terminated array of alternating field/value C strings (e.g. { "X-Field", "value", NULL }) to add to the request, or NULL for none.
completionThe completion handler.
userDataUser data passed through to completion.

Definition at line 254 of file RESTClient.c.

255 {
256 requestAsync(self, HTTP_OPTIONS, url, NULL, headers, completion, userData);
257}

◆ patch()

int patch ( RESTClient *  self,
const char *  url,
const Data *  body,
const char **  headers,
Data **  data 
)

Synchronously performs an HTTP PATCH request.

Parameters
selfThe RESTClient.
urlThe URL string.
bodyThe request body, or NULL.
headersA NULL-terminated array of alternating field/value C strings (e.g. { "X-Field", "value", NULL }) to add to the request, or NULL for none.
dataOptionally receives the retained response body. Caller must release.
Returns
The HTTP response status code, or 0 if the transfer failed or was cancelled.

Definition at line 263 of file RESTClient.c.

263 {
264 return request(self, HTTP_PATCH, url, body, headers, data);
265}
@ HTTP_PATCH
Definition URLRequest.h:49

◆ patchAsync()

void patchAsync ( RESTClient *  self,
const char *  url,
const Data *  body,
const char **  headers,
RESTClientCompletion  completion,
void *  userData 
)

Asynchronously performs an HTTP PATCH request.

Parameters
selfThe RESTClient.
urlThe URL string.
bodyThe request body, or NULL.
headersA NULL-terminated array of alternating field/value C strings (e.g. { "X-Field", "value", NULL }) to add to the request, or NULL for none.
completionThe completion handler.
userDataUser data passed through to completion.

Definition at line 271 of file RESTClient.c.

272 {
273 requestAsync(self, HTTP_PATCH, url, body, headers, completion, userData);
274}

◆ post()

int post ( RESTClient *  self,
const char *  url,
const Data *  body,
const char **  headers,
Data **  data 
)

Synchronously performs an HTTP POST request.

Parameters
selfThe RESTClient.
urlThe URL string.
bodyThe request body, or NULL.
headersA NULL-terminated array of alternating field/value C strings (e.g. { "X-Field", "value", NULL }) to add to the request, or NULL for none.
dataOptionally receives the retained response body. Caller must release.
Returns
The HTTP response status code, or 0 if the transfer failed or was cancelled.

Definition at line 280 of file RESTClient.c.

280 {
281 return request(self, HTTP_POST, url, body, headers, data);
282}
@ HTTP_POST
Definition URLRequest.h:47

◆ postAsync()

void postAsync ( RESTClient *  self,
const char *  url,
const Data *  body,
const char **  headers,
RESTClientCompletion  completion,
void *  userData 
)

Asynchronously performs an HTTP POST request.

Parameters
selfThe RESTClient.
urlThe URL string.
bodyThe request body, or NULL.
headersA NULL-terminated array of alternating field/value C strings (e.g. { "X-Field", "value", NULL }) to add to the request, or NULL for none.
completionThe completion handler.
userDataUser data passed through to completion.

Definition at line 288 of file RESTClient.c.

289 {
290 requestAsync(self, HTTP_POST, url, body, headers, completion, userData);
291}

◆ put()

int put ( RESTClient *  self,
const char *  url,
const Data *  body,
const char **  headers,
Data **  data 
)

Synchronously performs an HTTP PUT request.

Parameters
selfThe RESTClient.
urlThe URL string.
bodyThe request body, or NULL.
headersA NULL-terminated array of alternating field/value C strings (e.g. { "X-Field", "value", NULL }) to add to the request, or NULL for none.
dataOptionally receives the retained response body. Caller must release.
Returns
The HTTP response status code, or 0 if the transfer failed or was cancelled.

Definition at line 297 of file RESTClient.c.

297 {
298 return request(self, HTTP_PUT, url, body, headers, data);
299}
@ HTTP_PUT
Definition URLRequest.h:48

◆ putAsync()

void putAsync ( RESTClient *  self,
const char *  url,
const Data *  body,
const char **  headers,
RESTClientCompletion  completion,
void *  userData 
)

Asynchronously performs an HTTP PUT request.

Parameters
selfThe RESTClient.
urlThe URL string.
bodyThe request body, or NULL.
headersA NULL-terminated array of alternating field/value C strings (e.g. { "X-Field", "value", NULL }) to add to the request, or NULL for none.
completionThe completion handler.
userDataUser data passed through to completion.

Definition at line 305 of file RESTClient.c.

306 {
307 requestAsync(self, HTTP_PUT, url, body, headers, completion, userData);
308}

◆ sharedInstance()

RESTClient * sharedInstance ( void  )
Returns
The shared RESTClient instance, backed by the shared URLSession.

Definition at line 212 of file Log.c.

212 {
213
214 static Once once;
215
216 do_once(&once, {
218 });
219
220 return _sharedInstance;
221}
#define alloc(type)
Allocate and initialize and instance of type.
Definition Class.h:226
static Log * _sharedInstance
Definition Log.c:206
A Log4J-inspired log appender.
Definition Log.h:61

The documentation for this struct was generated from the following files: