Functions
NATS_EXTERN microError *	microRequest_AddHeader (microRequest req, const char key, const char *value)
	Adds a header to the underlying NATS request message.

NATS_EXTERN microError *	microRequest_DeleteHeader (microRequest req, const char key)
	Deletes a header from the underlying NATS request message.

NATS_EXTERN natsConnection *	microRequest_GetConnection (microRequest *req)
	Returns the connection associated with the request.

NATS_EXTERN const char *	microRequest_GetData (microRequest *req)
	Returns the data in the the request, as a byte array.

NATS_EXTERN int	microRequest_GetDataLength (microRequest *req)
	Returns the number of data bytes in the the request.

NATS_EXTERN void *	microRequest_GetEndpointState (microRequest *req)
	Returns the pointer to the user-provided endpoint state, if the request is associated with an endpoint.

NATS_EXTERN microError *	microRequest_GetHeaderKeys (microRequest req, const char *keys, int count)
	Gets the list of all header keys in the NATS message underlying the request.

NATS_EXTERN microError *	microRequest_GetHeaderValue (microRequest req, const char key, const char **value)
	Get the header entry associated with `key` from the NATS message underlying the request.

NATS_EXTERN microError *	microRequest_GetHeaderValues (microRequest req, const char key, const char **values, int count)
	Get all header values associated with `key` from the NATS message underlying the request.

NATS_EXTERN natsMsg *	microRequest_GetMsg (microRequest *req)
	Get the NATS message underlying the request.

NATS_EXTERN const char *	microRequest_GetReply (microRequest *req)
	Returns the reply subject set in this message.

NATS_EXTERN microService *	microRequest_GetService (microRequest *req)
	Returns the pointer to the microservice associated with the request.

NATS_EXTERN void *	microRequest_GetServiceState (microRequest *req)
	Returns the pointer to the user-provided service state.

NATS_EXTERN const char *	microRequest_GetSubject (microRequest *req)
	Returns the subject of the request message.

NATS_EXTERN microError *	microRequest_Respond (microRequest req, const char data, size_t len)
	Respond to a request, on the same NATS connection.

NATS_EXTERN microError *	microRequest_RespondError (microRequest req, microError err)
	Respond to a request with a simple error.

NATS_EXTERN microError *	microRequest_RespondCustom (microRequest req, microError err, const char *data, size_t len)
	Respond to a message, with an OK or an error.

NATS_EXTERN microError *	microRequest_SetHeader (microRequest req, const char key, const char *value)
	Add `value` to the header associated with `key` in the NATS message underlying the request.

Detailed Description

Functions that operate with microRequest.

Function Documentation

◆ microRequest_AddHeader()

NATS_EXTERN microError * microRequest_AddHeader	(	microRequest *	req,
		const char *	key,
		const char *	value )

Parameters

req	the request.
key	the key under which the `value` will be stored. It can't ne `NULL` or empty.
value	the string to add to the values associated with the given `key`. The value can be `NULL` or empty string.

Returns: a microError if an error occurred.

See also: natsMsgHeader_Add, microRequest_DeleteHeader, microRequest_GetHeaderKeys, microRequest_GetHeaderValue, microRequest_GetHeaderValues

◆ microRequest_DeleteHeader()

NATS_EXTERN microError * microRequest_DeleteHeader	(	microRequest *	req,
		const char *	key )

Parameters

req	the request.
key	the key to delete from the headers map.

Returns: a microError if an error occurred.

See also: natsMsgHeader_Delete, microRequest_AddHeader

◆ microRequest_GetConnection()

NATS_EXTERN natsConnection * microRequest_GetConnection ( microRequest * req )

Parameters

req	the request.

Returns: a natsConnection associated with the request. In fact, it's the connection associated with the service, so by the time the request handler is invoked the connection state may be different from when it was received.

◆ microRequest_GetData()

NATS_EXTERN const char * microRequest_GetData ( microRequest * req )

Note: The request owns the data, so it should not be freed other than with microRequest_Destroy.; The data is not NULL terminated. Use microRequest_GetDataLength to obtain the number of bytes.

Parameters

req	the request.

Returns: a pointer to the request's data.

See also: natsMsg_GetData, microRequest_GetDataLength

◆ microRequest_GetDataLength()

NATS_EXTERN int microRequest_GetDataLength ( microRequest * req )

Parameters

req	the request.

Returns: the number of data bytes in the request.

See also: natsMsg_GetDataLength, microRequest_GetData

◆ microRequest_GetEndpointState()

NATS_EXTERN void * microRequest_GetEndpointState ( microRequest * req )

Parameters

req	the request.

Returns: the state pointer provided in microEndpointConfig.

See also: microEndpointConfig, micro_endpoint_config_s

◆ microRequest_GetHeaderKeys()

NATS_EXTERN microError * microRequest_GetHeaderKeys	(	microRequest *	req,
		const char ***	keys,
		int *	count )

The returned strings are own by the library and MUST not be freed or altered. However, the returned array keys MUST be freed by the user.

Parameters

req	the request.
keys	the memory location where the library will store the pointer to the array of keys.
count	the memory location where the library will store the number of keys returned.

Returns: a microError if an error occurred.

See also: natsMsgHeader_Keys, microRequest_GetHeaderValue, microRequest_GetHeaderValues

◆ microRequest_GetHeaderValue()

NATS_EXTERN microError * microRequest_GetHeaderValue	(	microRequest *	req,
		const char *	key,
		const char **	value )

Parameters

req	the request.
key	the key for which the value is requested.
value	the memory location where the library will store the pointer to the first value (if more than one is found) associated with the `key`.

Returns: a microError if an error occurred.

See also: natsMsgHeader_Get, microRequest_GetHeaderValue, microRequest_GetHeaderValues

◆ microRequest_GetHeaderValues()

NATS_EXTERN microError * microRequest_GetHeaderValues	(	microRequest *	req,
		const char *	key,
		const char ***	values,
		int *	count )

Parameters

req	the request.
key	the key for which the values are requested.
values	the memory location where the library will store the pointer to the array value (if more than one is found) associated with the `key`.
count	the memory location where the library will store the number of values returned.

Returns: a microError if an error occurred.

See also: natsMsgHeader_Values, microRequest_GetHeaderValue, microRequest_GetHeaderKeys

◆ microRequest_GetMsg()

NATS_EXTERN natsMsg * microRequest_GetMsg ( microRequest * req )

Parameters

req	the request.

Returns: the pointer to natsMsg.

◆ microRequest_GetReply()

NATS_EXTERN const char * microRequest_GetReply ( microRequest * req )

Returns the reply, possibly NULL.

Warning: The string belongs to the message and must not be freed. Copy it if needed.

Parameters

req	the request.

◆ microRequest_GetService()

NATS_EXTERN microService * microRequest_GetService ( microRequest * req )

Parameters

req	the request.

Returns: the microservice pointer.

◆ microRequest_GetServiceState()

NATS_EXTERN void * microRequest_GetServiceState ( microRequest * req )

Parameters

req	the request.

Returns: the state pointer provided in microServiceConfig.

See also: microServiceConfig, micro_service_config_s

◆ microRequest_GetSubject()

NATS_EXTERN const char * microRequest_GetSubject ( microRequest * req )

Warning: The string belongs to the message and must not be freed. Copy it if needed.

Parameters

req	the request.

◆ microRequest_Respond()

NATS_EXTERN microError * microRequest_Respond	(	microRequest *	req,
		const char *	data,
		size_t	len )

Parameters

req	the request.
data	the response data.
len	the length of the response data.

Returns: an error, if any.

◆ microRequest_RespondError()

NATS_EXTERN microError * microRequest_RespondError	(	microRequest *	req,
		microError *	err )

If err is NULL, RespondError does nothing.

Note: microRequest_RespondError is called automatially if the handler returns an error. Usually, there is no need for a handler to use this function directly. If the request

Parameters

req	the request.
err	the error to include in the response header. If `NULL`, no error.

Returns: an error, if any.

◆ microRequest_RespondCustom()

NATS_EXTERN microError * microRequest_RespondCustom	(	microRequest *	req,
		microError *	err,
		const char *	data,
		size_t	len )

If err is NULL, RespondErrorWithData is equivalent to Respond. If err is not NULL, the response will include the error in the response header, and err will be freed.

The following example illustrates idiomatic usage in a request handler. Since this handler handles its own error responses, the only error it might return would be a failure to send the response.

err = somefunc();
if (err != NULL) {
    return microRequest_RespondCustom(req, err, error_data, data_len);
}
...

Or, if the request handler has its own cleanup logic:

if (err = somefunc(), err != NULL)
    goto CLEANUP;
...
 
CLEANUP:
if (err != NULL) {
    return microRequest_RespondCustom(req, err, error_data, data_len);
}
return NULL;

Parameters

req	the request.
err	the error to include in the response header. If `NULL`, no error.
data	the response data.
len	the length of the response data.

Note

Returns: an error, if any.

◆ microRequest_SetHeader()

NATS_EXTERN microError * microRequest_SetHeader	(	microRequest *	req,
		const char *	key,
		const char *	value )

Parameters

req	the request.
key	the key under which the `value` will be stored. It can't ne `NULL` or empty.
value	the string to store under the given `key`. The value can be `NULL` or empty string.

Returns: a microError if an error occurred.

See also: natsMsgHeader_Set