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

Functions
Management
Functions » Connection

## Functions
NATS_EXTERN natsStatus | natsConnection_Connect (natsConnection **nc, natsOptions *options)
| Connects to a `NATS Server` using the provided options. More...
natsStatus | natsConnection_Reconnect (natsConnection *nc)
| Drops the current connection, reconnects including re-subscribing. More...
NATS_EXTERN void | natsConnection_ProcessReadEvent (natsConnection *nc)
| Process a read event when using external event loop. More...
NATS_EXTERN void | natsConnection_ProcessWriteEvent (natsConnection *nc)
| Process a write event when using external event loop. More...
NATS_EXTERN natsStatus | natsConnection_ConnectTo (natsConnection **nc, const char *urls)
| Connects to a `NATS Server` using any of the URL from the given list. More...
NATS_EXTERN bool | natsConnection_IsClosed (natsConnection *nc)
| Test if connection has been closed. More...
NATS_EXTERN bool | natsConnection_IsReconnecting (natsConnection *nc)
| Test if connection is reconnecting. More...
NATS_EXTERN bool | natsConnection_IsDraining (natsConnection *nc)
| Test if connection is draining. More...
NATS_EXTERN natsConnStatus | natsConnection_Status (natsConnection *nc)
| Returns the current state of the connection. More...
NATS_EXTERN int | natsConnection_Buffered (natsConnection *nc)
| Returns the number of bytes to be sent to the server. More...
NATS_EXTERN natsStatus | natsConnection_Flush (natsConnection *nc)
| Flushes the connection. More...
NATS_EXTERN natsStatus | natsConnection_FlushTimeout (natsConnection *nc, int64_t timeout)
| Flushes the connection with a given timeout. More...
NATS_EXTERN int64_t | natsConnection_GetMaxPayload (natsConnection *nc)
| Returns the maximum message payload. More...
NATS_EXTERN natsStatus | natsConnection_GetStats (natsConnection *nc, natsStatistics *stats)
| Gets the connection statistics. More...
NATS_EXTERN natsStatus | natsConnection_GetConnectedUrl (natsConnection *nc, char *buffer, size_t bufferSize)
| Gets the URL of the currently connected server. More...
NATS_EXTERN natsStatus | natsConnection_GetConnectedServerId (natsConnection *nc, char *buffer, size_t bufferSize)
| Gets the server Id. More...
NATS_EXTERN natsStatus | natsConnection_GetServers (natsConnection *nc, char ***servers, int *count)
| Returns the list of server URLs known to this connection. More...
NATS_EXTERN natsStatus | natsConnection_GetDiscoveredServers (natsConnection *nc, char ***servers, int *count)
| Returns the list of discovered server URLs. More...
NATS_EXTERN natsStatus | natsConnection_GetLastError (natsConnection *nc, const char **lastError)
| Gets the last connection error. More...
NATS_EXTERN natsStatus | natsConnection_GetClientID (natsConnection *nc, uint64_t *cid)
| Gets the current client ID assigned by the server. More...
NATS_EXTERN natsStatus | natsConnection_Drain (natsConnection *nc)
| Drains the connection with default timeout. More...
NATS_EXTERN natsStatus | natsConnection_DrainTimeout (natsConnection *nc, int64_t timeout)
| Drains the connection with given timeout. More...
NATS_EXTERN natsStatus | natsConnection_Sign (natsConnection *nc, const unsigned char *message, int messageLen, unsigned char sig[64])
| Signs any 'message' using the connection's user credentials. More...
NATS_EXTERN natsStatus | natsConnection_GetClientIP (natsConnection *nc, char **ip)
| Returns the client's IP address as reported by the server. More...
NATS_EXTERN natsStatus | natsConnection_GetRTT (natsConnection *nc, int64_t *rtt)
| Returns the round trip time between this client and the server. More...
NATS_EXTERN natsStatus | natsConnection_HasHeaderSupport (natsConnection *nc)
| Returns if the connection to current server supports headers. More...
NATS_EXTERN natsStatus | natsConnection_GetLocalIPAndPort (natsConnection *nc, char **ip, int *port)
| Returns the connection local IP and port. More...
NATS_EXTERN void | natsConnection_Close (natsConnection *nc)
| Closes the connection. More...
NATS_EXTERN void | natsConnection_Destroy (natsConnection *nc)
| Destroys the connection object. More...

## Detailed Description

Functions related to connection management.

## Function Documentation

## ◆ natsConnection_Connect()

NATS_EXTERN natsStatus natsConnection_Connect | ( | natsConnection ** | nc,
|  | natsOptions * | options
| ) |  |

Attempts to connect to a `NATS Server` with multiple options.

This call is cloning the natsOptions object. Once this call returns, changes made to the `options` will not have an effect to this connection. The `options` can however be changed prior to be passed to another natsConnection_Connect() call if desired.

See also
  natsOptions
  natsConnection_Destroy()

Parameters

  nc | the location where to store the pointer to the newly created natsConnection object.
  options | the options to use for this connection. If `NULL` this call is equivalent to natsConnection_ConnectTo() with NATS_DEFAULT_URL.

## ◆ natsConnection_Reconnect()

natsStatus natsConnection_Reconnect | ( | natsConnection * | nc | ) |

Causes the client to drop the connection to the current server and to initiate the standard reconnection process. This means that all subscriptions and consumers will be resubscribed and their work resumed after successful reconnect where all reconnect options are respected.

Parameters

  nc | the pointer to the natsConnection object.

## ◆ natsConnection_ProcessReadEvent()

NATS_EXTERN void natsConnection_ProcessReadEvent | ( | natsConnection * | nc | ) |

When using an external event loop, and the callback indicating that the socket is ready for reading, this call will read data from the socket and process it.

Parameters

  nc | the pointer to the natsConnection object.

Warning
  This API is reserved for external event loop adapters.

## ◆ natsConnection_ProcessWriteEvent()

NATS_EXTERN void natsConnection_ProcessWriteEvent | ( | natsConnection * | nc | ) |

When using an external event loop, and the callback indicating that the socket is ready for writing, this call will write data to the socket.

Parameters

  nc | the pointer to the natsConnection object.

Warning
  This API is reserved for external event loop adapters.

## ◆ natsConnection_ConnectTo()

NATS_EXTERN natsStatus natsConnection_ConnectTo | ( | natsConnection ** | nc,
|  | const char * | urls
| ) |  |

Attempts to connect to a `NATS Server`.

This call supports multiple comma separated URLs. If more than one is specified, it behaves as if you were using a natsOptions object and called natsOptions_SetServers() with the equivalent array of URLs. The list is randomized before the connect sequence starts.

See also
  natsConnection_Destroy()
  natsOptions_SetServers()

Parameters

  nc | the location where to store the pointer to the newly created natsConnection object.
  urls | the URL to connect to, or the list of URLs to chose from. If `NULL` this call is equivalent to natsConnection_ConnectTo() with NATS_DEFAULT_URL

## ◆ natsConnection_IsClosed()

NATS_EXTERN bool natsConnection_IsClosed | ( | natsConnection * | nc | ) |

Tests if connection has been closed.

Parameters

  nc | the pointer to the natsConnection object.

## ◆ natsConnection_IsReconnecting()

NATS_EXTERN bool natsConnection_IsReconnecting | ( | natsConnection * | nc | ) |

Tests if connection is reconnecting.

Parameters

  nc | the pointer to the natsConnection object.

## ◆ natsConnection_IsDraining()

NATS_EXTERN bool natsConnection_IsDraining | ( | natsConnection * | nc | ) |

Tests if connection is draining.

Parameters

  nc | the pointer to the natsConnection object.

## ◆ natsConnection_Status()

NATS_EXTERN natsConnStatus natsConnection_Status | ( | natsConnection * | nc | ) |

Returns the current state of the connection.

See also
  natsConnStatus

Parameters

  nc | the pointer to the natsConnection object.

## ◆ natsConnection_Buffered()

NATS_EXTERN int natsConnection_Buffered | ( | natsConnection * | nc | ) |

When calling any of the publish functions, data is not necessarily immediately sent to the server. Some buffering occurs, allowing for better performance. This function indicates if there is any data not yet transmitted to the server.

Parameters

  nc | the pointer to the natsConnection object.

Returns
  the number of bytes to be sent to the server, or -1 if the connection is closed.

## ◆ natsConnection_Flush()

NATS_EXTERN natsStatus natsConnection_Flush | ( | natsConnection * | nc | ) |

Performs a round trip to the server and return when it receives the internal reply.

Note that if this call occurs when the connection to the server is lost, the `PING` will not be echoed even if the library can connect to a new (or the same) server. Therefore, in such situation, this call will fail with the status NATS_CONNECTION_DISCONNECTED.

If the connection is closed while this call is in progress, then the status NATS_CONN_STATUS_CLOSED would be returned instead.

Parameters

  nc | the pointer to the natsConnection object.

## ◆ natsConnection_FlushTimeout()

NATS_EXTERN natsStatus natsConnection_FlushTimeout | ( | natsConnection * | nc,
|  | int64_t | timeout
| ) |  |

Performs a round trip to the server and return when it receives the internal reply, or if the call times-out (timeout is expressed in milliseconds).

See possible failure case described in natsConnection_Flush().

Parameters

  nc | the pointer to the natsConnection object.
  timeout | in milliseconds, is the time allowed for the flush to complete before NATS_TIMEOUT error is returned.

## ◆ natsConnection_GetMaxPayload()

NATS_EXTERN int64_t natsConnection_GetMaxPayload | ( | natsConnection * | nc | ) |

Returns the maximum message payload accepted by the server. The information is gathered from the `NATS Server` when the connection is first established.

Parameters

  nc | the pointer to the natsConnection object.

Returns
  the maximum message payload.

## ◆ natsConnection_GetStats()

NATS_EXTERN natsStatus natsConnection_GetStats | ( | natsConnection * | nc,
|  | natsStatistics * | stats
| ) |  |

Copies in the provided statistics structure, a snapshot of the statistics for this connection.

Parameters

  nc | the pointer to the natsConnection object.
  stats | the pointer to a natsStatistics object in which statistics will be copied.

## ◆ natsConnection_GetConnectedUrl()

NATS_EXTERN natsStatus natsConnection_GetConnectedUrl | ( | natsConnection * | nc,
|  | char * | buffer,
|  | size_t | bufferSize
| ) |  |

Copies in the given buffer, the connected server's Url. If the buffer is too small, an error is returned.

Parameters

  nc | the pointer to the natsConnection object.
  buffer | the buffer in which the URL is copied.
  bufferSize | the size of the buffer.

## ◆ natsConnection_GetConnectedServerId()

NATS_EXTERN natsStatus natsConnection_GetConnectedServerId | ( | natsConnection * | nc,
|  | char * | buffer,
|  | size_t | bufferSize
| ) |  |

Copies in the given buffer, the connected server's Id. If the buffer is too small, an error is returned.

Parameters

  nc | the pointer to the natsConnection object.
  buffer | the buffer in which the server id is copied.
  bufferSize | the size of the buffer.

## ◆ natsConnection_GetServers()

NATS_EXTERN natsStatus natsConnection_GetServers | ( | natsConnection * | nc,
|  | char *** | servers,
|  | int * | count
| ) |  |

Returns the list of known servers, including additional servers discovered after a connection has been established (with servers version 0.9.2 and above).

No credential information is included in any of the server URLs returned by this call.
If you want to use any of these URLs to connect to a server that requires authentication, you will need to use natsOptions_SetUserInfo or natsOptions_SetToken.

Note
  The user is responsible for freeing the memory of the returned array.

Parameters

  nc | the pointer to the natsConnection object.
  servers | the location where to store the pointer to the array of server URLs.
  count | the location where to store the number of elements of the returned array.

## ◆ natsConnection_GetDiscoveredServers()

NATS_EXTERN natsStatus natsConnection_GetDiscoveredServers | ( | natsConnection * | nc,
|  | char *** | servers,
|  | int * | count
| ) |  |

Unlike natsConnection_GetServers, this function only returns the list of servers that have been discovered after the a connection has been established (with servers version 0.9.2 and above).

No credential information is included in any of the server URLs returned by this call.
If you want to use any of these URLs to connect to a server that requires authentication, you will need to use natsOptions_SetUserInfo or natsOptions_SetToken.

Note
  The user is responsible for freeing the memory of the returned array.

Parameters

  nc | the pointer to the natsConnection object.
  servers | the location where to store the pointer to the array of server URLs.
  count | the location where to store the number of elements of the returned array.

## ◆ natsConnection_GetLastError()

NATS_EXTERN natsStatus natsConnection_GetLastError | ( | natsConnection * | nc,
|  | const char ** | lastError
| ) |  |

Returns the last known error as a 'natsStatus' and the location to the null-terminated error string.

Warning
  The returned string is owned by the connection object and must not be freed.

Parameters

  nc | the pointer to the natsConnection object.
  lastError | the location where the pointer to the connection's last error string is copied.

## ◆ natsConnection_GetClientID()

NATS_EXTERN natsStatus natsConnection_GetClientID | ( | natsConnection * | nc,
|  | uint64_t * | cid
| ) |  |

Returns the client ID assigned by the server to which the client is currently connected to.

Note
  The value may change if the client reconnects.

This function returns NATS_NO_SERVER_SUPPORT if the server's version is less than 1.2.0.

Parameters

  nc | the pointer to the natsConnection object.
  cid | the location where to store the client ID.

## ◆ natsConnection_Drain()

NATS_EXTERN natsStatus natsConnection_Drain | ( | natsConnection * | nc | ) |

Drain will put a connection into a drain state. All subscriptions will immediately be put into a drain state. Upon completion, the publishers will be drained and can not publish any additional messages. Upon draining of the publishers, the connection will be closed. Use the natsOptions_SetClosedCB() option to know when the connection has moved from draining to closed.

This call uses a default drain timeout of 30 seconds.

Warning
  This function does not block waiting for the draining operation to complete.

See also
  natsOptions_SetClosedCB
  natsConnection_DrainTimeout

Parameters

  nc | the pointer to the natsConnection object.

## ◆ natsConnection_DrainTimeout()

NATS_EXTERN natsStatus natsConnection_DrainTimeout | ( | natsConnection * | nc,
|  | int64_t | timeout
| ) |  |

Identical to natsConnection_Drain but the timeout can be specified here.

The value is expressed in milliseconds. Zero or negative value means that the operation will not timeout.

Warning
  This function does not block waiting for the draining operation to complete.

See also
  natsOptions_SetClosedCB
  natsConnection_Drain

Parameters

  nc | the pointer to the natsConnection object.
  timeout | the allowed time for a drain operation to complete, expressed in milliseconds.

## ◆ natsConnection_Sign()

NATS_EXTERN natsStatus natsConnection_Sign | ( | natsConnection * | nc,
|  | const unsigned char * | message,
|  | int | messageLen,
|  | unsigned char | sig[64]
| ) |  |

The connection must have been created with the natsOptions_SetUserCredentialsFromFiles.

This call will sign the given message with the private key extracted through the user credentials file(s).

Parameters

  nc | the pointer to the natsConnection object.
  message | the byte array to sign.
  messageLen | the length of the given byte array.
  sig | an array of 64 bytes in which the signature will be copied.

## ◆ natsConnection_GetClientIP()

NATS_EXTERN natsStatus natsConnection_GetClientIP | ( | natsConnection * | nc,
|  | char ** | ip
| ) |  |

When a connection is created to the server, the server identifies the connection's remote IP address and return it back to the client.

Note
  The user is responsible to free memory allocated to store the client IP address.
  This is supported on servers >= version 2.1.6. Calling natsConnection_GetClientIP() with server below this version will return the NATS_NO_SERVER_SUPPORT error.

See also
  natsConnection_GetLocalIPAndPort to get the local IP and port instead.

Parameters

  nc | the pointer to the natsConnection object.
  ip | the memory location where to store the client's IP string. The user is responsible from freeing this memory.

## ◆ natsConnection_GetRTT()

NATS_EXTERN natsStatus natsConnection_GetRTT | ( | natsConnection * | nc,
|  | int64_t * | rtt
| ) |  |

The value returned is in nanoseconds.

Note
  If the library is currently trying to reconnect, this call will return NATS_CONNECTION_DISCONNECTED.

Parameters

  nc | the pointer to the natsConnection object.
  rtt | the memory location where to store the rtt.

## ◆ natsConnection_HasHeaderSupport()

NATS_EXTERN natsStatus natsConnection_HasHeaderSupport | ( | natsConnection * | nc | ) |

Returns NATS_OK if the server this client is currently connected to supports headers, NATS_NO_SERVER_SUPPORT otherwise.

Parameters

  nc | the pointer to the natsConnection object.

## ◆ natsConnection_GetLocalIPAndPort()

NATS_EXTERN natsStatus natsConnection_GetLocalIPAndPort | ( | natsConnection * | nc,
|  | char ** | ip,
|  | int * | port
| ) |  |

Unlike natsConnection_GetClientIP, this function returns the connection's local IP and port.

Note
  The user is responsible for freeing the memory allocated for the returned IP string.

Parameters

  nc | the pointer of the natsConnection object.
  ip | the memory location where to store the local IP string. The user is responsible from freeing this memory.
  port | the memory location where to store the local port.

Returns
  NATS_OK on success.
  NATS_CONNECTION_DISCONNECTED if disconnected.
  NATS_CONNECTION_CLOSED is connection is closed.
  NATS_SYS_ERROR if a system error getting the IP and port occurred.
  NATS_NO_MEMORY if the library was unable to allocate memory for the returned IP string.

## ◆ natsConnection_Close()

NATS_EXTERN void natsConnection_Close | ( | natsConnection * | nc | ) |

Closes the connection to the server. This call will release all blocking calls, such as natsConnection_Flush() and natsSubscription_NextMsg(). The connection object is still usable until the call to natsConnection_Destroy().

Parameters

  nc | the pointer to the natsConnection object.

## ◆ natsConnection_Destroy()

NATS_EXTERN void natsConnection_Destroy | ( | natsConnection * | nc | ) |

Destroys the connection object, freeing up memory. If not already done, this call first closes the connection to the server.

Parameters

  nc | the pointer to the natsConnection object.