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

Functions
Streaming Connection Options
Functions

## Functions
NATS_EXTERN natsStatus | stanConnOptions_Create (stanConnOptions **newOpts)
| Creates a stanConnOptions object. More...
NATS_EXTERN natsStatus | stanConnOptions_SetURL (stanConnOptions *opts, const char *url)
| Sets the URL to connect to. More...
NATS_EXTERN natsStatus | stanConnOptions_SetNATSOptions (stanConnOptions *opts, natsOptions *nOpts)
| Sets the NATS Options to use to create the connection. More...
NATS_EXTERN natsStatus | stanConnOptions_SetConnectionWait (stanConnOptions *opts, int64_t wait)
| Sets the timeout for establishing a connection. More...
NATS_EXTERN natsStatus | stanConnOptions_SetPubAckWait (stanConnOptions *opts, int64_t wait)
| Sets the timeout for waiting for an ACK for a published message. More...
NATS_EXTERN natsStatus | stanConnOptions_SetDiscoveryPrefix (stanConnOptions *opts, const char *prefix)
| Sets the subject prefix the library sends the connect request to. More...
NATS_EXTERN natsStatus | stanConnOptions_SetMaxPubAcksInflight (stanConnOptions *opts, int maxPubAcksInflight, float percentage)
| Sets the maximum number of published messages without outstanding ACKs from the server. More...
NATS_EXTERN natsStatus | stanConnOptions_SetPings (stanConnOptions *opts, int interval, int maxOut)
| Sets the ping interval and max out values. More...
NATS_EXTERN natsStatus | stanConnOptions_SetConnectionLostHandler (stanConnOptions *opts, stanConnectionLostHandler handler, void *closure)
| Sets the connection lost handler. More...
NATS_EXTERN void | stanConnOptions_Destroy (stanConnOptions *opts)
| Destroys a stanConnOptions object. More...

## Detailed Description

NATS Streaming Connection Options.

## Function Documentation

## ◆ stanConnOptions_Create()

NATS_EXTERN natsStatus stanConnOptions_Create | ( | stanConnOptions ** | newOpts | ) |

Creates a stanConnOptions object. This object is used when one wants to set specific options prior to connecting to the `NATS Streaning Server`.

After making the appropriate `stanConnOptions_SetXXX()` calls, this object is passed to the stanConnection_Connect() call, which will clone this object. After stanConnection_Connect() returns, modifications to the options object will not affect the connection.

The default options set in this call are: url: `nats://localhost:4222` connection wait: 2 seconds publish ack wait: 30 seconds discovery prefix: `_STAN.discovery` maximum publish acks inflight and percentage: 16384, 50% ping interval: 5 seconds max ping out without response: 3

Note
  The object needs to be destroyed when no longer needed.

See also
  stanConnection_Connect()
  stanConnOptions_Destroy()

Parameters

  newOpts | the location where store the pointer to the newly created stanConnOptions object.

## ◆ stanConnOptions_SetURL()

NATS_EXTERN natsStatus stanConnOptions_SetURL | ( | stanConnOptions * | opts,
|  | const char * | url
| ) |  |

Sets the URL of the `NATS Streaming Server` the client should try to connect to. The URL can contain optional user name and password. You can provide a comma separated list of URLs too.

Some valid URLS:

- nats://localhost:4222
- nats://user@localhost:4222
- nats://user:password@localhost:4222
- nats://host1:4222,nats://host2:4222,nats://host3:4222

Note
  This option takes precedence over natsOptions_SetURL when NATS options are passed with stanConnOptions_SetNATSOptions.

Parameters

  opts | the pointer to the stanConnOptions object.
  url | the string representing the URL the connection should use to connect to the server.

## ◆ stanConnOptions_SetNATSOptions()

NATS_EXTERN natsStatus stanConnOptions_SetNATSOptions | ( | stanConnOptions * | opts,
|  | natsOptions * | nOpts
| ) |  |

The Streaming client connects to the NATS Streaming Server through a regular NATS Connection (natsConnection). To configure this connection create a natsOptions and configure it as needed, then call this function.

This function clones the passed options, so after this call, any changes to the given natsOptions will not affect the stanConnOptions.

Note
  If both natsOptions_SetURL and stanConnOptions_SetURL are used the URL(s) set in the later take precedence.

Parameters

  opts | the pointer to the stanConnOptions object.
  nOpts | the pointer to the natsOptions object to use to create the connection to the server.

## ◆ stanConnOptions_SetConnectionWait()

NATS_EXTERN natsStatus stanConnOptions_SetConnectionWait | ( | stanConnOptions * | opts,
|  | int64_t | wait
| ) |  |

Value expressed in milliseconds.

Default is 2000 milliseconds (2 seconds).

Parameters

  opts | the pointer to the stanConnOptions object.
  wait | how long to wait for a response from the streaming server.

## ◆ stanConnOptions_SetPubAckWait()

NATS_EXTERN natsStatus stanConnOptions_SetPubAckWait | ( | stanConnOptions * | opts,
|  | int64_t | wait
| ) |  |

Value expressed in milliseconds.

Default is 30000 milliseconds (30 seconds).

Parameters

  opts | the pointer to the stanConnOptions object.
  wait | how long to wait for a response from the streaming server.

## ◆ stanConnOptions_SetDiscoveryPrefix()

NATS_EXTERN natsStatus stanConnOptions_SetDiscoveryPrefix | ( | stanConnOptions * | opts,
|  | const char * | prefix
| ) |  |

Default is `_STAN.discovery`

Parameters

  opts | the pointer to the stanConnOptions object.
  prefix | the subject prefix the library sends the connect request to.

## ◆ stanConnOptions_SetMaxPubAcksInflight()

NATS_EXTERN natsStatus stanConnOptions_SetMaxPubAcksInflight | ( | stanConnOptions * | opts,
|  | int | maxPubAcksInflight,
|  | float | percentage
| ) |  |

A connection will block stanConnection_Publish() or stanConnection_PublishAsync calls if the number of outstanding published messages has reached this number.

When the connection receives ACKs, the number of outstanding messages will decrease. If the number falls between `maxPubAcksInflight * percentage`, then the blocked publish calls will be released.

Parameters

  opts | the pointer to the stanConnOptions object.
  maxPubAcksInflight | the maximum number of published messages without ACKs from the server.
  percentage | the percentage (expressed as a float between ]0.0 and 1.0]) of the maxPubAcksInflight number below which a blocked publish call is released.

## ◆ stanConnOptions_SetPings()

NATS_EXTERN natsStatus stanConnOptions_SetPings | ( | stanConnOptions * | opts,
|  | int | interval,
|  | int | maxOut
| ) |  |

Value expressed in number of seconds.

Default is 5 seconds and 3 missed PONGs.

The interval needs to be at least 1 and represents the number of seconds. The maxOut needs to be at least 2, since the count of sent PINGs increase whenever a PING is sent and reset to 0 when a response is received. Setting to 1 would cause the library to close the connection right away.

Parameters

  opts | the pointer to the stanConnOptions object.
  interval | the number of seconds between each PING.
  maxOut | the maximum number of PINGs without receiving a PONG back.

## ◆ stanConnOptions_SetConnectionLostHandler()

NATS_EXTERN natsStatus stanConnOptions_SetConnectionLostHandler | ( | stanConnOptions * | opts,
|  | stanConnectionLostHandler | handler,
|  | void * | closure
| ) |  |

This callback will be invoked should the client permanently lose contact with the server (or another client replaces it while being disconnected). The callback will not be invoked on normal stanConnection_Close().

Parameters

  opts | the pointer to the stanConnOptions object.
  handler | the handler to be invoked when the connection to the streaming server is lost.
  closure | the closure the library will pass to the callback.

## ◆ stanConnOptions_Destroy()

NATS_EXTERN void stanConnOptions_Destroy | ( | stanConnOptions * | opts | ) |

Destroys the stanConnOptions object, freeing used memory. See the note in the stanConnOptions_Create() call.

Parameters

  opts | the pointer to the stanConnOptions object to destroy.