Loading...
Searching...
No Matches
Management
Functions » Streaming Connection

## Functions

NATS_EXTERN natsStatus | stanConnection_Connect (stanConnection **sc, const char *clusterID, const char *clientID, stanConnOptions *options)
| Connects to a `NATS Streaming Server` using the provided options.
NATS_EXTERN natsStatus | stanConnection_GetNATSConnection (stanConnection *sc, natsConnection **nc)
| Returns the underlying NATS Connection.
NATS_EXTERN void | stanConnection_ReleaseNATSConnection (stanConnection *sc)
| Releases the NATS Connection.
NATS_EXTERN natsStatus | stanConnection_Close (stanConnection *sc)
| Closes the connection.
NATS_EXTERN natsStatus | stanConnection_Destroy (stanConnection *sc)
| Destroys the connection object.

## Detailed Description

Functions related to connection management.

## Function Documentation

## stanConnection_Connect()

NATS_EXTERN natsStatus stanConnection_Connect | ( | stanConnection ** | sc,
|  | const char * | clusterID,
|  | const char * | clientID,
|  | stanConnOptions * | options
| ) |  |

Attempts to connect to a `NATS Streaming Server`.

This call is cloning the stanConnOptions object, if given. 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 stanConnection_Connect() call if desired.

Note
  The Streaming connection does not honor the NATS Connection option natsOptions_SetRetryOnFailedConnect(). If you pass NATS Options with this option enabled, no error is returned, but if the connection cannot be established "right away", the connect call will return an error.

Warning
  If connecting to a NATS Server v2.2.0+ and there is no Streaming server listening on the connect request subject, this call will return NATS_NO_RESPONDERS, not NATS_TIMEOUT.

See also
  stanConnOptions
  stanConnection_Destroy()

Parameters

  sc | the location where to store the pointer to the newly created natsConnection object.
  clusterID | the name of the cluster this connection is for.
  clientID | the client ID for this connection. Only one connection with this ID will be accepted by the server. Use only a-zA-Z0-9_- characters.
  options | the options to use for this connection (can be `NULL`).

## stanConnection_GetNATSConnection()

NATS_EXTERN natsStatus stanConnection_GetNATSConnection | ( | stanConnection * | sc,
|  | natsConnection ** | nc
| ) |  |

This can be used if the application needs to do non streaming messaging but does not want to create a separate NATS Connection.

Obtain a NATS connection from a NATS streaming connection. The NATS connection can be used to perform regular NATS operations, but it is owned and managed by the NATS streaming connection. It cannot be closed, which will happen when the NATS streaming connection is closed.

Note
  For each call to this function, the user must call stanConnection_ReleaseNATSConnection() when access to the NATS Connection is no longer needed.

Warning
  The returned connection cannot be closed, drained nor destroyed. Calling corresponding functions will have no effect or return NATS_ILLEGAL_STATE.

See also
  stanConnection_ReleaseNATSConnection()

Parameters

  sc | the pointer to the stanConnection object.
  nc | the location where to store the pointer of the natsConnection object.

## stanConnection_ReleaseNATSConnection()

NATS_EXTERN void stanConnection_ReleaseNATSConnection | ( | stanConnection * | sc | ) |

This should be paired with the stanConnection_GetNATSConnection() call. That is, after getting a reference to the underlying NATS Connection and once that connection is no longer needed, calling this function will allow resources to be properly released when the streaming connection is destroyed.

You would normally call stanConnection_GetNATSConnection() and this function only once.

After the last stanConnection_ReleaseNATSConnection() call is made, you must no longer use the NATS Connection because if stanConnection_Destroy() is called, that could make the pointer to the NATS Connection invalid.

Note
  If the streaming connection is closed/destroyed before the last call to stanConnection_ReleaseNATSConnection, the pointer to the NATS connection will still be valid, although all calls will fail since the connection is now closed. Calling this function will release the streaming object allowing memory to be freed.

See also
  stanConnection_GetNATSConnection

Parameters

  sc | the pointer to the stanConnection object.

## stanConnection_Close()

NATS_EXTERN natsStatus stanConnection_Close | ( | stanConnection * | sc | ) |

Closes the connection to the server. This call will release all blocking calls. The connection object is still usable until the call to stanConnection_Destroy().

Warning
  See warning about connecting to a NATS Server v2.2.0+ in stanConnection_Connect().

Parameters

  sc | the pointer to the stanConnection object.

## stanConnection_Destroy()

NATS_EXTERN natsStatus stanConnection_Destroy | ( | stanConnection * | sc | ) |

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

Parameters

  sc | the pointer to the stanConnection object.