NATS C Client with JetStream and Streaming support 3.9.0-beta The nats.io C Client, Supported by Synadia Communications Inc.

Functions
microRequest
EXPERIMENTAL - Microservices » Functions

## Functions
NATS_EXTERN microError * | microRequest_AddHeader (microRequest *req, const char *key, const char *value)
| Adds a header to the underlying NATS request message. More...
NATS_EXTERN microError * | microRequest_DeleteHeader (microRequest *req, const char *key)
| Deletes a header from the underlying NATS request message. More...
NATS_EXTERN natsConnection * | microRequest_GetConnection (microRequest *req)
| Returns the connection associated with the request. More...
NATS_EXTERN const char * | microRequest_GetData (microRequest *req)
| Returns the data in the the request, as a byte array. More...
NATS_EXTERN int | microRequest_GetDataLength (microRequest *req)
| Returns the number of data bytes in the the request. More...
NATS_EXTERN void * | microRequest_GetEndpointState (microRequest *req)
| Returns the pointer to the user-provided endpoint state, if the request is associated with an endpoint. More...
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. More...
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. More...
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. More...
NATS_EXTERN natsMsg * | microRequest_GetMsg (microRequest *req)
| Get the NATS message underlying the request. More...
NATS_EXTERN const char * | microRequest_GetReply (microRequest *req)
| Returns the reply subject set in this message. More...
NATS_EXTERN microService * | microRequest_GetService (microRequest *req)
| Returns the pointer to the microservice associated with the request. More...
NATS_EXTERN void * | microRequest_GetServiceState (microRequest *req)
| Returns the pointer to the user-provided service state. More...
NATS_EXTERN const char * | microRequest_GetSubject (microRequest *req)
| Returns the subject of the request message. More...
NATS_EXTERN microError * | microRequest_Respond (microRequest *req, const char *data, size_t len)
| Respond to a request, on the same NATS connection. More...
NATS_EXTERN microError * | microRequest_RespondError (microRequest *req, microError *err)
| Respond to a request with a simple error. More...
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. More...
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. More...

## 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);
}
...
microRequest_RespondCustom
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.

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