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

Functions
Message
Functions

## Functions
NATS_EXTERN void | natsMsgList_Destroy (natsMsgList *list)
| Destroys this list of messages. More...
NATS_EXTERN natsStatus | natsMsg_Create (natsMsg **newMsg, const char *subj, const char *reply, const char *data, int dataLen)
| Creates a natsMsg object. More...
NATS_EXTERN const char * | natsMsg_GetSubject (const natsMsg *msg)
| Returns the subject set in this message. More...
NATS_EXTERN const char * | natsMsg_GetReply (const natsMsg *msg)
| Returns the reply set in this message. More...
NATS_EXTERN const char * | natsMsg_GetData (const natsMsg *msg)
| Returns the message payload. More...
NATS_EXTERN int | natsMsg_GetDataLength (const natsMsg *msg)
| Returns the message length. More...
NATS_EXTERN natsStatus | natsMsgHeader_Set (natsMsg *msg, const char *key, const char *value)
| Set the header entries associated with `key` to the single element `value`. More...
NATS_EXTERN natsStatus | natsMsgHeader_Add (natsMsg *msg, const char *key, const char *value)
| Add `value` to the header associated with `key`. More...
NATS_EXTERN natsStatus | natsMsgHeader_Get (natsMsg *msg, const char *key, const char **value)
| Get the header entry associated with `key`. More...
NATS_EXTERN natsStatus | natsMsgHeader_Values (natsMsg *msg, const char *key, const char ***values, int *count)
| Get all header values associated with `key`. More...
NATS_EXTERN natsStatus | natsMsgHeader_Keys (natsMsg *msg, const char ***keys, int *count)
| Get all header keys. More...
NATS_EXTERN natsStatus | natsMsgHeader_Delete (natsMsg *msg, const char *key)
| Delete the value(s) associated with `key`. More...
NATS_EXTERN bool | natsMsg_IsNoResponders (natsMsg *msg)
| Indicates if this message is a "no responders" message from the server. More...
NATS_EXTERN void | natsMsg_Destroy (natsMsg *msg)
| Destroys the message object. More...

## Detailed Description

NATS Message.

## Function Documentation

## ◆ natsMsgList_Destroy()

NATS_EXTERN void natsMsgList_Destroy | ( | natsMsgList * | list | ) |

This function iterates through the list of all messages and call natsMsg_Destroy for each valid (not set to `NULL`) message. It then frees the array that was allocated to hold pointers to those messages.

Note
  The natsMsgList object itself is not freed since it is expected that users will pass a pointer to a stack object. Should the user create its own object, it will be the user responsibility to free this object.

Parameters

  list | the natsMsgList list of natsMsg objects to destroy.

## ◆ natsMsg_Create()

NATS_EXTERN natsStatus natsMsg_Create | ( | natsMsg ** | newMsg,
|  | const char * | subj,
|  | const char * | reply,
|  | const char * | data,
|  | int | dataLen
| ) |  |

Creates a natsMsg object. This is used by the subscription related calls and by natsConnection_PublishMsg().

Note
  Messages need to be destroyed with natsMsg_Destroy() when no longer needed.

See also
  natsMsg_Destroy()

Parameters

  newMsg | the location where to store the pointer to the newly created natsMsg object.
  subj | the subject this message will be sent to. Cannot be `NULL`.
  reply | the optional reply for this message.
  data | the optional message payload.
  dataLen | the size of the payload.

## ◆ natsMsg_GetSubject()

NATS_EXTERN const char* natsMsg_GetSubject | ( | const natsMsg * | msg | ) |

Returns the subject set on that message.

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

Parameters

  msg | the pointer to the natsMsg object.

## ◆ natsMsg_GetReply()

NATS_EXTERN const char* natsMsg_GetReply | ( | const natsMsg * | msg | ) |

Returns the reply, possibly `NULL`.

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

Parameters

  msg | the pointer to the natsMsg object.

## ◆ natsMsg_GetData()

NATS_EXTERN const char* natsMsg_GetData | ( | const natsMsg * | msg | ) |

Returns the message payload, possibly `NULL`.

Note that although the data sent and received from the server is not `NULL` terminated, the NATS C Client does add a `NULL` byte to the received payload. If you expect the received data to be a "string", then this conveniently allows you to call natsMsg_GetData() without having to copy the returned data to a buffer to add the `NULL` byte at the end.

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

Parameters

  msg | the pointer to the natsMsg object.

## ◆ natsMsg_GetDataLength()

NATS_EXTERN int natsMsg_GetDataLength | ( | const natsMsg * | msg | ) |

Returns the message's payload length, possibly 0.

Parameters

  msg | the pointer to the natsMsg object.

## ◆ natsMsgHeader_Set()

NATS_EXTERN natsStatus natsMsgHeader_Set | ( | natsMsg * | msg,
|  | const char * | key,
|  | const char * | value
| ) |  |

It will replace any existing value associated with `key`.

Warning
  Prior to v3.0.0, the `key` was stored in its canonical form, this is no longer the case. Header keys are now case sensitive.
  Headers are not thread-safe, that is, you must not set/add/get values or delete keys for the same message from different threads. The internal structure of `natsMsg` may possible be altered during this call.

Parameters

  msg | the pointer to the natsMsg object.
  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.

## ◆ natsMsgHeader_Add()

NATS_EXTERN natsStatus natsMsgHeader_Add | ( | natsMsg * | msg,
|  | const char * | key,
|  | const char * | value
| ) |  |

It will append to any existing values associated with `key`.

Warning
  Prior to v3.0.0, the `key` was stored in its canonical form, this is no longer the case. Header keys are now case sensitive.
  Headers are not thread-safe, that is, you must not set/add/get values or delete keys for the same message from different threads. The internal structure of `natsMsg` may possible be altered during this call.

Parameters

  msg | the pointer to the natsMsg object.
  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.

## ◆ natsMsgHeader_Get()

NATS_EXTERN natsStatus natsMsgHeader_Get | ( | natsMsg * | msg,
|  | const char * | key,
|  | const char ** | value
| ) |  |

If more than one entry for the `key` is available, the first is returned. The returned value is owned by the library and MUST not be freed or altered.

Warning
  Prior to v3.0.0, the `key` was stored in its canonical form, this is no longer the case. Header keys are now case sensitive.
  Headers are not thread-safe, that is, you must not set/add/get values or delete keys for the same message from different threads. The internal structure of `natsMsg` may possible be altered during this call.

Parameters

  msg | the pointer to the natsMsg object.
  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
  NATS_NOT_FOUND if `key` is not present in the headers.

## ◆ natsMsgHeader_Values()

NATS_EXTERN natsStatus natsMsgHeader_Values | ( | natsMsg * | msg,
|  | const char * | key,
|  | const char *** | values,
|  | int * | count
| ) |  |

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

const char* *values = NULL;
int count = 0;
s = natsMsgHeader_Values(msg, "My-Key", &values, &count);
if (s == NATS_OK)
{
// do something with the values
// then free the array of pointers.
free((void*) values);
}
natsMsgHeader_Values
NATS_EXTERN natsStatus natsMsgHeader_Values(natsMsg *msg, const char *key, const char ***values, int *count)
Get all header values associated with key.
NATS_OK
@ NATS_OK
Success.
Definition: status.h:51

Warning
  Prior to v3.0.0, the `key` was stored in its canonical form, this is no longer the case. Header keys are now case sensitive.
  Headers are not thread-safe, that is, you must not set/add/get values or delete keys for the same message from different threads. The internal structure of `natsMsg` may possible be altered during this call.

Parameters

  msg | the pointer to the natsMsg object.
  key | the key for which the values are requested.
  values | the memory location where the library will store the pointer to the array of values.
  count | the memory location where the library will store the number of values returned.

Returns
  NATS_NOT_FOUND if `key` is not present in the headers.

## ◆ natsMsgHeader_Keys()

NATS_EXTERN natsStatus natsMsgHeader_Keys | ( | natsMsg * | msg,
|  | 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.

const char* *keys = NULL;
int count = 0;
s = natsMsgHeader_Keys(msg, &keys, &count);
if (s == NATS_OK)
{
// do something with the keys
// then free the array of pointers.
free((void*) keys);
}
natsMsgHeader_Keys
NATS_EXTERN natsStatus natsMsgHeader_Keys(natsMsg *msg, const char ***keys, int *count)
Get all header keys.

Warning
  Headers are not thread-safe, that is, you must not set/add/get values or delete keys for the same message from different threads. The internal structure of `natsMsg` may possible be altered during this call.

Parameters

  msg | the pointer to the natsMsg object.
  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
  NATS_NOT_FOUND if no key is present.

## ◆ natsMsgHeader_Delete()

NATS_EXTERN natsStatus natsMsgHeader_Delete | ( | natsMsg * | msg,
|  | const char * | key
| ) |  |

Warning
  Prior to v3.0.0, the `key` was stored in its canonical form, this is no longer the case. Header keys are now case sensitive.
  Headers are not thread-safe, that is, you must not set/add/get values or delete keys for the same message from different threads. The internal structure of `natsMsg` may possible be altered during this call.

Parameters

  msg | the pointer to the natsMsg object.
  key | the key to delete from the headers map.

Returns
  NATS_NOT_FOUND if `key` is not present in the headers.

## ◆ natsMsg_IsNoResponders()

NATS_EXTERN bool natsMsg_IsNoResponders | ( | natsMsg * | msg | ) |

Starting with the NATS Server v2.2.0+ and the C client v2.2.0+ releases, which introduced support for message headers and the "no responders" feature, if a request is received by the server and there are no subscriptions on the request's subject, the server sends a message with no payload but with a header "Status" with value "503".

The call natsConnection_Request() and its variants intercept this special message and instead of returning it to the user, they return NATS_NO_RESPONDERS.

If a synchronous subscription is created on a subject used as a reply subject to a natsConnection_PublishRequest call (and its variants), natsSubscription_NextMsg also detects this message and returns NATS_NO_RESPONDERS (but it was not from release v2.2.0 to v2.4.1).

For asynchronous subscriptions, the user may want to know that the request failed because there are no responders. For that reason, the message is passed to the message callback, and this function can be used to detect that this is a "no responders" message from the server and act accordingly.

Parameters

  msg | the pointer to the natsMsg object.

Returns
  `true` if this message is a "no responders" message from the server, that is, has no payload and the "Status" header with "503" as the value.

## ◆ natsMsg_Destroy()

NATS_EXTERN void natsMsg_Destroy | ( | natsMsg * | msg | ) |

Destroys the message, freeing memory.

Parameters

  msg | the pointer to the natsMsg object to destroy.