A parsed and validated REST request with typed access to its parameters. More...

#include <RESTAPI.h>

Collaboration diagram for cmlabs::RESTRequest:

Public Types
enum	Status { FAILED_EMPTY = 0 , SUCCESS = 1 , FAILED_DESCRIPTION = 2 , FAILED_UNKNOWN_REQUEST = 3 , FAILED_FORMAT = 4 , FAILED_PARAM = 5 , FAILED_AUTH = 6 , SUCCESS_OPTIONS = 7 }
	Parse/validation outcome of the request. More...

Public Member Functions
	RESTRequest (DataMessage *msg)
	Reconstruct a request from a DataMessage previously produced by getStorageMessageCopy().
	RESTRequest ()
	Create an empty request (status FAILED_EMPTY) with fresh internal storage.
virtual	~RESTRequest ()
	Destructor; deletes the internal storage message.
bool	isHTTPCall ()
HTTPRequest *	generateHTTPCallRequest ()
	Generate the outbound HTTPRequest for an HTTP-call request.
std::string	getHTTPCallURL ()
Status	getStatus ()
const char *	getSignature (bool &success)
	Get the request signature (canonical "name(paramtypes)" string from the API definition).
const char *	getOrigin (bool &success)
	Get the request origin (e.g.
uint64	getCreateTime (bool &success)
	Get the creation timestamp (PsyTime µs).
bool	getRequireAuthentication ()
const char *	getErrorString ()
DataMessage *	getStorageMessageCopy ()
Typed parameter getters
Read a named parameter extracted from the request. success is set to false if the key is absent or of the wrong type. Returned pointers reference the internal storage and remain valid for the life of the request (getDataCopy() returns a malloc'ed copy the caller must free).
uint64	getTime (const char *key, bool &success)
const char *	getString (const char *key, bool &success)
int64	getInt (const char *key, bool &success)
double	getDouble (const char *key, bool &success)
const char *	getData (const char *key, uint32 &size, bool &success)
char *	getDataCopy (const char *key, uint32 &size, bool &success)
Filters
Optional query-filter key/values attached to the request (e.g. from URL query parameters). Getters set success false when the key is absent.
const char *	getFilterString (const char *key, bool &success)
int64	getFilterInt (const char *key, bool &success)
float64	getFilterFloat (const char *key, bool &success)
bool	setFilter (const char key, const char val)
bool	setFilter (const char *key, int64 val)
bool	setFilter (const char *key, float64 val)

Public Attributes
enum cmlabs::RESTRequest::Status	status

Protected Member Functions
bool	setStatus (Status status)
bool	setOrigin (const char *origin)
bool	setCreateTime (uint64 created)
bool	setRequestSignature (const char *signature)
bool	setRequireAuthentication (bool auth)
bool	setTime (const char *key, uint64 val)
bool	setInt (const char *key, int64 val)
bool	setDouble (const char *key, double val)
bool	setString (const char key, const char val)
bool	setBinary (const char key, const char data, uint32 size, const char *contentType)
bool	addToErrorString (const char *errorLine)
bool	clearErrorState ()

Protected Attributes
std::string	origin
std::string	signature
uint64	createTime
DataMessage *	storage
bool	requireAuthentication
std::map< std::string, std::string >	filterMap
std::string	errorString
RESTHTTPCall *	httpCall

Friends
class	RESTParser

Detailed Description

A parsed and validated REST request with typed access to its parameters.

Produced by RESTParser::parseRequest(). Parameter values are stored in an internal DataMessage (storage, owned by the request); the getString()/ getInt()/getData() family reads them back by name. Check getStatus() (or the public status member) before using the values; on failure getErrorString() explains why. Filters (getFilterString() etc.) carry optional query-filter key/values. Not thread-safe; use from one thread at a time.

Definition at line 42 of file RESTAPI.h.

Member Enumeration Documentation

◆ Status

enum cmlabs::RESTRequest::Status

Parse/validation outcome of the request.

SUCCESS and SUCCESS_OPTIONS indicate a usable request.

Enumerator
FAILED_EMPTY
SUCCESS
FAILED_DESCRIPTION
FAILED_UNKNOWN_REQUEST
FAILED_FORMAT
FAILED_PARAM
FAILED_AUTH
SUCCESS_OPTIONS

Definition at line 46 of file RESTAPI.h.

Constructor & Destructor Documentation

◆ RESTRequest() [1/2]

cmlabs::RESTRequest::RESTRequest ( DataMessage * msg )

Reconstruct a request from a DataMessage previously produced by getStorageMessageCopy().

Parameters

msg	Source message; contents are copied/adopted into internal storage.

Definition at line 1366 of file RESTAPI.cpp.

References createTime, cmlabs::html::DecodeHTML(), filterMap, cmlabs::DataMessage::getInt(), cmlabs::DataMessage::getString(), getString(), cmlabs::DataMessage::getTime(), httpCall, requireAuthentication, signature, status, storage, and cmlabs::utils::TextMapSplit().

◆ RESTRequest() [2/2]

cmlabs::RESTRequest::RESTRequest ( )

inline

Create an empty request (status FAILED_EMPTY) with fresh internal storage.

Definition at line 83 of file RESTAPI.h.

References createTime, FAILED_EMPTY, httpCall, requireAuthentication, status, and storage.

◆ ~RESTRequest()

cmlabs::RESTRequest::~RESTRequest ( )

virtual

Destructor; deletes the internal storage message.

Definition at line 1382 of file RESTAPI.cpp.

References httpCall, and storage.

Member Function Documentation

◆ addToErrorString()

bool cmlabs::RESTRequest::addToErrorString ( const char * errorLine )

inlineprotected

Definition at line 74 of file RESTAPI.h.

References errorString, and cmlabs::utils::StringFormat().

Referenced by cmlabs::RESTParser::extractArrayParameters(), cmlabs::RESTParser::extractArrayParameters(), cmlabs::RESTParser::extractParameters(), cmlabs::RESTParser::extractParameters(), cmlabs::RESTParser::parseRequest(), cmlabs::RESTParser::parseRequest(), cmlabs::RESTParser::parseRequest(), cmlabs::RESTParser::setParameterValue(), and cmlabs::RESTParser::setParameterValue().

◆ clearErrorState()

bool cmlabs::RESTRequest::clearErrorState ( )

inlineprotected

Definition at line 75 of file RESTAPI.h.

References errorString, FAILED_EMPTY, and status.

Referenced by cmlabs::RESTParser::extractParameters(), cmlabs::RESTParser::extractParameters(), and cmlabs::RESTParser::parseRequest().

◆ generateHTTPCallRequest()

HTTPRequest * cmlabs::RESTRequest::generateHTTPCallRequest ( )

Generate the outbound HTTPRequest for an HTTP-call request.

Returns: New HTTPRequest (caller takes ownership), or NULL if not an HTTP call.

Definition at line 1410 of file RESTAPI.cpp.

References httpCall.

◆ getCreateTime()

uint64 cmlabs::RESTRequest::getCreateTime ( bool & success )

inline

Get the creation timestamp (PsyTime µs).

Parameters

success Set to true if recorded.

Definition at line 108 of file RESTAPI.h.

References createTime.

◆ getData()

const char * cmlabs::RESTRequest::getData	(	const char *	key,
		uint32 &	size,
		bool &	success )

inline

Definition at line 120 of file RESTAPI.h.

References storage.

◆ getDataCopy()

char * cmlabs::RESTRequest::getDataCopy	(	const char *	key,
		uint32 &	size,
		bool &	success )

inline

Definition at line 121 of file RESTAPI.h.

References storage.

Referenced by cmlabs::RESTHTTPCall::generateHTTPRequest().

◆ getDouble()

double cmlabs::RESTRequest::getDouble	(	const char *	key,
		bool &	success )

inline

Definition at line 119 of file RESTAPI.h.

References storage.

◆ getErrorString()

const char * cmlabs::RESTRequest::getErrorString ( )

inline

Returns: Accumulated parse/validation error text (empty when status is SUCCESS).

Definition at line 127 of file RESTAPI.h.

References errorString.

Referenced by cmlabs::RESTParser::UnitTest().

◆ getFilterFloat()

float64 cmlabs::RESTRequest::getFilterFloat	(	const char *	key,
		bool &	success )

inline

Definition at line 135 of file RESTAPI.h.

References cmlabs::utils::Ascii2Float64(), and filterMap.

◆ getFilterInt()

int64 cmlabs::RESTRequest::getFilterInt	(	const char *	key,
		bool &	success )

inline

Definition at line 134 of file RESTAPI.h.

References cmlabs::utils::Ascii2Int64(), and filterMap.

◆ getFilterString()

const char * cmlabs::RESTRequest::getFilterString	(	const char *	key,
		bool &	success )

inline

Definition at line 133 of file RESTAPI.h.

References filterMap.

◆ getHTTPCallURL()

std::string cmlabs::RESTRequest::getHTTPCallURL ( )

Returns: The templated URL of the associated HTTP call, with parameters substituted; empty if none.

Definition at line 1416 of file RESTAPI.cpp.

References httpCall.

◆ getInt()

int64 cmlabs::RESTRequest::getInt	(	const char *	key,
		bool &	success )

inline

Definition at line 118 of file RESTAPI.h.

References storage.

◆ getOrigin()

const char * cmlabs::RESTRequest::getOrigin ( bool & success )

inline

Get the request origin (e.g.

remote address / source identifier).

Parameters

success Set to true if an origin was recorded.

Definition at line 106 of file RESTAPI.h.

References origin.

◆ getRequireAuthentication()

bool cmlabs::RESTRequest::getRequireAuthentication ( )

inline

Returns: true if the API definition requires authentication for this request.

Definition at line 124 of file RESTAPI.h.

Referenced by cmlabs::RESTParser::parseRequest(), and cmlabs::RESTParser::parseRequest().

◆ getSignature()

const char * cmlabs::RESTRequest::getSignature ( bool & success )

inline

Get the request signature (canonical "name(paramtypes)" string from the API definition).

Parameters

success Set to true if a signature is present.

Returns: Signature string (valid while the request lives).

Definition at line 102 of file RESTAPI.h.

References signature.

◆ getStatus()

Status cmlabs::RESTRequest::getStatus ( )

inline

Returns: The parse/validation status of this request.

Definition at line 97 of file RESTAPI.h.

References status.

Referenced by cmlabs::RESTParser::UnitTest().

◆ getStorageMessageCopy()

DataMessage * cmlabs::RESTRequest::getStorageMessageCopy ( )

Returns: A new copy of the internal storage message (caller takes ownership); can later rebuild the request via RESTRequest(DataMessage*).

Definition at line 1389 of file RESTAPI.cpp.

References createTime, cmlabs::html::EncodeHTML(), filterMap, requireAuthentication, cmlabs::DataMessage::setInt(), cmlabs::DataMessage::setString(), cmlabs::DataMessage::setTime(), signature, status, storage, and cmlabs::utils::StringFormat().

◆ getString()

const char * cmlabs::RESTRequest::getString	(	const char *	key,
		bool &	success )

inline

Definition at line 117 of file RESTAPI.h.

References storage.

Referenced by cmlabs::RESTHTTPCall::generateHTTPRequest(), and RESTRequest().

◆ getTime()

uint64 cmlabs::RESTRequest::getTime	(	const char *	key,
		bool &	success )

inline

Definition at line 116 of file RESTAPI.h.

References storage.

◆ isHTTPCall()

bool cmlabs::RESTRequest::isHTTPCall ( )

inline

Returns: true if this request maps to an outbound HTTP call (RESTHTTPCall) rather than a local operation.

Definition at line 88 of file RESTAPI.h.

References httpCall.

◆ setBinary()

bool cmlabs::RESTRequest::setBinary	(	const char *	key,
		const char *	data,
		uint32	size,
		const char *	contentType )

inlineprotected

Definition at line 68 of file RESTAPI.h.

References storage, and cmlabs::utils::StringFormat().

Referenced by cmlabs::RESTParser::extractArrayParameters(), cmlabs::RESTParser::extractArrayParameters(), cmlabs::RESTParser::extractParameters(), cmlabs::RESTParser::extractParameters(), cmlabs::RESTParser::setParameterValue(), and cmlabs::RESTParser::setParameterValue().

◆ setCreateTime()

bool cmlabs::RESTRequest::setCreateTime ( uint64 created )

inlineprotected

Definition at line 60 of file RESTAPI.h.

◆ setDouble()

bool cmlabs::RESTRequest::setDouble	(	const char *	key,
		double	val )

inlineprotected

Definition at line 66 of file RESTAPI.h.

References storage.

Referenced by cmlabs::RESTParser::setParameterValue(), and cmlabs::RESTParser::setParameterValue().

◆ setFilter() [1/3]

bool cmlabs::RESTRequest::setFilter	(	const char *	key,
		const char *	val )

inline

Definition at line 136 of file RESTAPI.h.

References filterMap.

Referenced by cmlabs::RESTParser::parseRequest().

◆ setFilter() [2/3]

bool cmlabs::RESTRequest::setFilter	(	const char *	key,
		float64	val )

inline

Definition at line 138 of file RESTAPI.h.

References filterMap, and cmlabs::utils::StringFormat().

◆ setFilter() [3/3]

bool cmlabs::RESTRequest::setFilter	(	const char *	key,
		int64	val )

inline

Definition at line 137 of file RESTAPI.h.

References filterMap, and cmlabs::utils::StringFormat().

◆ setInt()

bool cmlabs::RESTRequest::setInt	(	const char *	key,
		int64	val )

inlineprotected

Definition at line 65 of file RESTAPI.h.

References storage.

Referenced by cmlabs::RESTParser::parseRequest(), cmlabs::RESTParser::setParameterValue(), and cmlabs::RESTParser::setParameterValue().

◆ setOrigin()

bool cmlabs::RESTRequest::setOrigin ( const char * origin )

inlineprotected

Definition at line 59 of file RESTAPI.h.

References origin.

◆ setRequestSignature()

bool cmlabs::RESTRequest::setRequestSignature ( const char * signature )

inlineprotected

Definition at line 61 of file RESTAPI.h.

References signature.

Referenced by cmlabs::RESTParser::parseRequest(), and cmlabs::RESTParser::parseRequest().

◆ setRequireAuthentication()

bool cmlabs::RESTRequest::setRequireAuthentication ( bool auth )

inlineprotected

Definition at line 62 of file RESTAPI.h.

Referenced by cmlabs::RESTParser::parseRequest().

◆ setStatus()

bool cmlabs::RESTRequest::setStatus ( Status status )

inlineprotected

Definition at line 58 of file RESTAPI.h.

References status.

Referenced by cmlabs::RESTParser::parseRequest(), cmlabs::RESTParser::parseRequest(), and cmlabs::RESTParser::parseRequest().

◆ setString()

bool cmlabs::RESTRequest::setString	(	const char *	key,
		const char *	val )

inlineprotected

Definition at line 67 of file RESTAPI.h.

References storage.

Referenced by cmlabs::RESTParser::parseRequest(), cmlabs::RESTParser::parseRequest(), cmlabs::RESTParser::parseRequest(), cmlabs::RESTParser::setParameterValue(), and cmlabs::RESTParser::setParameterValue().

◆ setTime()

bool cmlabs::RESTRequest::setTime	(	const char *	key,
		uint64	val )

inlineprotected

Definition at line 64 of file RESTAPI.h.

References storage.

◆ RESTParser

friend class RESTParser

friend

Definition at line 43 of file RESTAPI.h.

References RESTParser.

Referenced by RESTParser.

Member Data Documentation

◆ createTime

uint64 cmlabs::RESTRequest::createTime

protected

Definition at line 51 of file RESTAPI.h.

Referenced by getCreateTime(), getStorageMessageCopy(), RESTRequest(), and RESTRequest().

◆ errorString

std::string cmlabs::RESTRequest::errorString

protected

Definition at line 55 of file RESTAPI.h.

Referenced by addToErrorString(), clearErrorState(), and getErrorString().

◆ filterMap

std::map<std::string, std::string> cmlabs::RESTRequest::filterMap

protected

Definition at line 54 of file RESTAPI.h.

Referenced by getFilterFloat(), getFilterInt(), getFilterString(), getStorageMessageCopy(), RESTRequest(), setFilter(), setFilter(), and setFilter().

◆ httpCall

RESTHTTPCall* cmlabs::RESTRequest::httpCall

protected

Definition at line 56 of file RESTAPI.h.

Referenced by generateHTTPCallRequest(), getHTTPCallURL(), isHTTPCall(), cmlabs::RESTParser::parseRequest(), cmlabs::RESTParser::parseRequest(), RESTRequest(), RESTRequest(), and ~RESTRequest().

◆ origin

std::string cmlabs::RESTRequest::origin

protected

Definition at line 49 of file RESTAPI.h.

Referenced by getOrigin(), and setOrigin().

◆ requireAuthentication

bool cmlabs::RESTRequest::requireAuthentication

protected

Definition at line 53 of file RESTAPI.h.

Referenced by getStorageMessageCopy(), RESTRequest(), and RESTRequest().

◆ signature

std::string cmlabs::RESTRequest::signature

protected

Definition at line 50 of file RESTAPI.h.

Referenced by getSignature(), getStorageMessageCopy(), RESTRequest(), and setRequestSignature().

◆ status

enum cmlabs::RESTRequest::Status cmlabs::RESTRequest::status

Referenced by clearErrorState(), getStatus(), getStorageMessageCopy(), RESTRequest(), RESTRequest(), and setStatus().

◆ storage

DataMessage* cmlabs::RESTRequest::storage

protected

Definition at line 52 of file RESTAPI.h.

Referenced by getData(), getDataCopy(), getDouble(), getInt(), getStorageMessageCopy(), getString(), getTime(), RESTRequest(), RESTRequest(), setBinary(), setDouble(), setInt(), setString(), setTime(), and ~RESTRequest().

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

/home/ubuntu/c/partner/psyclone2/CMSDK/include/RESTAPI.h
/home/ubuntu/c/partner/psyclone2/CMSDK/src/RESTAPI.cpp

Public Types

Public Member Functions

Public Attributes

Protected Member Functions

Protected Attributes

Friends

Detailed Description

Member Enumeration Documentation

◆ Status

Constructor & Destructor Documentation

◆ RESTRequest() [1/2]

◆ RESTRequest() [2/2]

◆ ~RESTRequest()

Member Function Documentation

◆ addToErrorString()

◆ clearErrorState()

◆ generateHTTPCallRequest()

◆ getCreateTime()

◆ getData()

◆ getDataCopy()

◆ getDouble()

◆ getErrorString()

◆ getFilterFloat()

◆ getFilterInt()

◆ getFilterString()

◆ getHTTPCallURL()

◆ getInt()

◆ getOrigin()

◆ getRequireAuthentication()

◆ getSignature()

◆ getStatus()

◆ getStorageMessageCopy()

◆ getString()

◆ getTime()

◆ isHTTPCall()

◆ setBinary()

◆ setCreateTime()

◆ setDouble()

◆ setFilter() [1/3]

◆ setFilter() [2/3]

◆ setFilter() [3/3]

◆ setInt()

◆ setOrigin()

◆ setRequestSignature()

◆ setRequireAuthentication()

◆ setStatus()

◆ setString()

◆ setTime()

Friends And Related Symbol Documentation

◆ RESTParser

Member Data Documentation

◆ createTime

◆ errorString

◆ filterMap

◆ httpCall

◆ origin

◆ requireAuthentication

◆ signature

◆ status

◆ storage