Link
Engine

## Modules

| Sender
| Receiver
| Terminus

## Typedefs

typedef struct pn_link_t | pn_link_t
| An AMQP Link object. More...

## Enumerations

enum | pn_snd_settle_mode_t { PN_SND_UNSETTLED = 0, PN_SND_SETTLED = 1, PN_SND_MIXED = 2 }
| Describes the permitted/expected settlement behaviours of a sending link. More...
enum | pn_rcv_settle_mode_t { PN_RCV_FIRST = 0, PN_RCV_SECOND = 1 }
| Describes the permitted/expected settlement behaviours of a receiving link. More...

## Functions

PN_EXTERN pn_link_t * | pn_sender (pn_session_t *session, const char *name)
| Construct a new sender on a session. More...
PN_EXTERN pn_link_t * | pn_receiver (pn_session_t *session, const char *name)
| Construct a new receiver on a session. More...
PN_EXTERN void | pn_link_free (pn_link_t *link)
| Free a link object. More...
PN_EXTERN void * | pn_link_get_context (pn_link_t *link)
PN_EXTERN void | pn_link_set_context (pn_link_t *link, void *context)
PN_EXTERN pn_record_t * | pn_link_attachments (pn_link_t *link)
| Get the attachments that are associated with a link object. More...
PN_EXTERN const char * | pn_link_name (pn_link_t *link)
| Get the name of a link. More...
PN_EXTERN bool | pn_link_is_sender (pn_link_t *link)
| Test if a link is a sender. More...
PN_EXTERN bool | pn_link_is_receiver (pn_link_t *link)
| Test if a link is a receiver. More...
PN_EXTERN pn_state_t | pn_link_state (pn_link_t *link)
| Get the endpoint state flags for a link. More...
PN_EXTERN pn_error_t * | pn_link_error (pn_link_t *link)
| Get additional error information associated with the link. More...
PN_EXTERN pn_condition_t * | pn_link_condition (pn_link_t *link)
| Get the local condition associated with a link endpoint. More...
PN_EXTERN pn_condition_t * | pn_link_remote_condition (pn_link_t *link)
| Get the remote condition associated with a link endpoint. More...
PN_EXTERN pn_session_t * | pn_link_session (pn_link_t *link)
| Get the parent session for a link object. More...
PN_EXTERN pn_link_t * | pn_link_head (pn_connection_t *connection, pn_state_t state)
| Retrieve the first link that matches the given state mask. More...
PN_EXTERN pn_link_t * | pn_link_next (pn_link_t *link, pn_state_t state)
| Retrieve the next link that matches the given state mask. More...
PN_EXTERN void | pn_link_open (pn_link_t *link)
| Open a link. More...
PN_EXTERN void | pn_link_close (pn_link_t *link)
| Close a link. More...
PN_EXTERN void | pn_link_detach (pn_link_t *link)
| Detach a link. More...
PN_EXTERN pn_terminus_t * | pn_link_source (pn_link_t *link)
| Access the locally defined source definition for a link. More...
PN_EXTERN pn_terminus_t * | pn_link_target (pn_link_t *link)
| Access the locally defined target definition for a link. More...
PN_EXTERN pn_terminus_t * | pn_link_remote_source (pn_link_t *link)
| Access the remotely defined source definition for a link. More...
PN_EXTERN pn_terminus_t * | pn_link_remote_target (pn_link_t *link)
| Access the remotely defined target definition for a link. More...
PN_EXTERN pn_delivery_t * | pn_link_current (pn_link_t *link)
| Get the current delivery for a link. More...
PN_EXTERN bool | pn_link_advance (pn_link_t *link)
| Advance the current delivery of a link to the next delivery on the link. More...
PN_EXTERN int | pn_link_credit (pn_link_t *link)
| Get the credit balance for a link. More...
PN_EXTERN int | pn_link_queued (pn_link_t *link)
| Get the number of queued deliveries for a link. More...
PN_EXTERN int | pn_link_remote_credit (pn_link_t *link)
| Get the remote view of the credit for a link. More...
PN_EXTERN bool | pn_link_get_drain (pn_link_t *link)
| Get the drain flag for a link. More...
PN_EXTERN int | pn_link_drained (pn_link_t *link)
| Drain excess credit for a link. More...
PN_EXTERN int | pn_link_available (pn_link_t *link)
| Get the available deliveries hint for a link. More...
PN_EXTERN pn_snd_settle_mode_t | pn_link_snd_settle_mode (pn_link_t *link)
| Get the local sender settle mode for a link. More...
PN_EXTERN pn_rcv_settle_mode_t | pn_link_rcv_settle_mode (pn_link_t *link)
| Get the local receiver settle mode for a link. More...
PN_EXTERN void | pn_link_set_snd_settle_mode (pn_link_t *link, pn_snd_settle_mode_t mode)
| Set the local sender settle mode for a link. More...
PN_EXTERN void | pn_link_set_rcv_settle_mode (pn_link_t *link, pn_rcv_settle_mode_t mode)
| Set the local receiver settle mode for a link. More...
PN_EXTERN pn_snd_settle_mode_t | pn_link_remote_snd_settle_mode (pn_link_t *link)
| Get the remote sender settle mode for a link. More...
PN_EXTERN pn_rcv_settle_mode_t | pn_link_remote_rcv_settle_mode (pn_link_t *link)
| Get the remote receiver settle mode for a link. More...
PN_EXTERN int | pn_link_unsettled (pn_link_t *link)
| Get the number of unsettled deliveries for a link. More...
PN_EXTERN pn_delivery_t * | pn_unsettled_head (pn_link_t *link)
| Get the first unsettled delivery for a link. More...
PN_EXTERN pn_delivery_t * | pn_unsettled_next (pn_delivery_t *delivery)
| Get the next unsettled delivery on a link. More...

## Detailed Description

## Typedef Documentation

typedef struct pn_link_t pn_link_t

An AMQP Link object.

A pn_link_t object encapsulates all of the endpoint state associated with an AMQP Link. A pn_link_t object contains an ordered sequence of pn_delivery_t objects representing in-flight deliveries. A pn_link_t may be either a Sender , or a Receiver , but never both.

A pn_link_t object maintains a pointer to the current delivery within the ordered sequence of deliveries contained by the link (See pn_link_current). The current delivery is the target of a number of operations associated with the link, such as sending (pn_link_send) and receiving (pn_link_recv) message data.

## Enumeration Type Documentation

enum pn_rcv_settle_mode_t

Describes the permitted/expected settlement behaviours of a receiving link.

The receiver settle mode describes the permitted and expected behaviour of a receiving link with respect to settling of deliveries. See pn_delivery_settle for more details.

Enumerator
PN_RCV_FIRST | The receiver will settle deliveries regardless of what the sender does.
PN_RCV_SECOND | The receiver will only settle deliveries after the sender settles.

enum pn_snd_settle_mode_t

Describes the permitted/expected settlement behaviours of a sending link.

The sender settle mode describes the permitted and expected behaviour of a sending link with respect to settling of deliveries. See pn_delivery_settle for more details.

Enumerator
PN_SND_UNSETTLED | The sender will send all deliveries initially unsettled.
PN_SND_SETTLED | The sender will send all deliveries settled to the receiver.
PN_SND_MIXED | The sender may send a mixure of settled and unsettled deliveries.

## Function Documentation

PN_EXTERN bool pn_link_advance | ( | pn_link_t * | link | ) |

Advance the current delivery of a link to the next delivery on the link.

For sending links this operation is used to finish sending message data for the current outgoing delivery and move on to the next outgoing delivery (if any).

For receiving links, this operation is used to finish accessing message data from the current incoming delivery and move on to the next incoming delivery (if any).

Each link maintains a sequence of deliveries in the order they were created, along with a pointer to the current delivery. The pn_link_advance operation will modify the current delivery on the link to point to the next delivery in the sequence. If there is no next delivery in the sequence, the current delivery will be set to NULL. This operation will return true if invoking it caused the value of the current delivery to change, even if it was set to NULL.

Parameters

  [in] | link | a link object

Returns
  true if the current delivery was changed

PN_EXTERN pn_record_t* pn_link_attachments | ( | pn_link_t * | link | ) |

Get the attachments that are associated with a link object.

Parameters

  [in] | link | the link whose attachments are to be returned.

Returns
  the attachments for the link object

PN_EXTERN int pn_link_available | ( | pn_link_t * | link | ) |

Get the available deliveries hint for a link.

The available count for a link provides a hint as to the number of deliveries that might be able to be sent if sufficient credit were issued by the receiving link endpoint. See pn_link_offered for more details.

Parameters

  [in] | link | a link object

Returns
  the available deliveries hint

PN_EXTERN void pn_link_close | ( | pn_link_t * | link | ) |

Close a link.

Once this operation has completed, the PN_LOCAL_CLOSED state flag will be set. This may be called without calling pn_link_open, in this case it is equivalent to calling pn_link_open followed by pn_link_close.

Parameters

  [in] | link | a link object

PN_EXTERN pn_condition_t* pn_link_condition | ( | pn_link_t * | link | ) |

Get the local condition associated with a link endpoint.

The pn_condition_t object retrieved may be modified prior to closing a link in order to indicate a particular condition exists when the link closes. This is normally used to communicate error conditions to the remote peer, however it may also be used in non error cases. See pn_condition_t for more details.

The pointer returned by this operation is valid until the link object is freed.

Parameters

  [in] | link | the link object

Returns
  the link's local condition object

PN_EXTERN int pn_link_credit | ( | pn_link_t * | link | ) |

Get the credit balance for a link.

Links use a credit based flow control scheme. Every receiver maintains a credit balance that corresponds to the number of deliveries that the receiver can accept at any given moment. As more capacity becomes available at the receiver (see pn_link_flow), it adds credit to this balance and communicates the new balance to the sender. Whenever a delivery is sent/received, the credit balance maintained by the link is decremented by one. Once the credit balance at the sender reaches zero, the sender must pause sending until more credit is obtained from the receiver.

Note that a sending link may still be used to send deliveries even if pn_link_credit reaches zero, however those deliveries will end up being buffered by the link until enough credit is obtained from the receiver to send them over the wire. In this case the balance reported by pn_link_credit will go negative.

Parameters

  [in] | link | a link object

Returns
  the credit balance for the link

PN_EXTERN pn_delivery_t* pn_link_current | ( | pn_link_t * | link | ) |

Get the current delivery for a link.

Each link maintains a sequence of deliveries in the order they were created, along with a pointer to the current delivery. All send/recv operations on a link take place on the current delivery. If a link has no current delivery, the current delivery is automatically initialized to the next delivery created on the link. Once initialized, the current delivery remains the same until it is changed through use of pn_link_advance or until it is settled via pn_delivery_settle.

Parameters

  [in] | link | a link object

Returns
  the current delivery for the link, or NULL if there is none

PN_EXTERN void pn_link_detach | ( | pn_link_t * | link | ) |

Detach a link.

Parameters

  [in] | link | a link object

PN_EXTERN int pn_link_drained | ( | pn_link_t * | link | ) |

Drain excess credit for a link.

When a link is in drain mode, the sender must use all excess credit immediately, and release any excess credit back to the receiver if there are no deliveries available to send.

When invoked on a sending link that is in drain mode, this operation will release all excess credit back to the receiver and return the number of credits released back to the sender. If the link is not in drain mode, this operation is a noop.

When invoked on a receiving link, this operation will return and reset the number of credits the sender has released back to the receiver.

Parameters

  [in] | link | a link object

Returns
  the number of credits drained

PN_EXTERN pn_error_t* pn_link_error | ( | pn_link_t * | link | ) |

Get additional error information associated with the link.

Whenever a link operation fails (i.e. returns an error code), additional error details can be obtained using this function. The error object that is returned may also be used to clear the error condition.

The pointer returned by this operation is valid until the link object is freed.

Parameters

  [in] | link | the link object

Returns
  the link's error object

PN_EXTERN void pn_link_free | ( | pn_link_t * | link | ) |

Free a link object.

When a link object is freed, all pn_delivery_t objects associated with the session are also freed. Freeing a link will settle any unsettled deliveries on the link.

Parameters

  [in] | link | a link object to free (or NULL)

PN_EXTERN void* pn_link_get_context | ( | pn_link_t * | link | ) |

Deprecated:
  Get the application context that is associated with a link object.

The application context for a link may be set using pn_link_set_context.

Parameters

  [in] | link | the link whose context is to be returned.

Returns
  the application context for the link object

PN_EXTERN bool pn_link_get_drain | ( | pn_link_t * | link | ) |

Get the drain flag for a link.

If a link is in drain mode, then the sending endpoint of a link must immediately use up all available credit on the link. If this is not possible, the excess credit must be returned by invoking pn_link_drained. Only the receiving endpoint can set the drain mode. See pn_link_set_drain for details.

Parameters

  [in] | link | a link object

Returns
  true if and only if the link is in drain mode

PN_EXTERN pn_link_t* pn_link_head | ( | pn_connection_t * | connection,
|  | pn_state_t | state
| ) |  |

Retrieve the first link that matches the given state mask.

Examines the state of each link owned by the connection and returns the first link that matches the given state mask. If state contains both local and remote flags, then an exact match against those flags is performed. If state contains only local or only remote flags, then a match occurs if any of the local or remote flags are set respectively.

Parameters

  [in] | connection | to be searched for matching Links
  [in] | state | mask to match

Returns
  the first link owned by the connection that matches the mask, else NULL if no links match

PN_EXTERN bool pn_link_is_receiver | ( | pn_link_t * | link | ) |

Test if a link is a receiver.

Parameters

  [in] | link | a link object

Returns
  true if and only if the link is a receiver

PN_EXTERN bool pn_link_is_sender | ( | pn_link_t * | link | ) |

Test if a link is a sender.

Parameters

  [in] | link | a link object

Returns
  true if and only if the link is a sender

PN_EXTERN const char* pn_link_name | ( | pn_link_t * | link | ) |

Get the name of a link.

Parameters

  [in] | link | a link object

Returns
  the name of the link

PN_EXTERN pn_link_t* pn_link_next | ( | pn_link_t * | link,
|  | pn_state_t | state
| ) |  |

Retrieve the next link that matches the given state mask.

When used with pn_link_head, the application can access all links on the connection that match the given state. See pn_link_head for description of match behavior.

Parameters

  [in] | link | the previous link obtained from pn_link_head or pn_link_next
  [in] | state | mask to match

Returns
  the next session owned by the connection that matches the mask, else NULL if no sessions match

PN_EXTERN void pn_link_open | ( | pn_link_t * | link | ) |

Open a link.

Once this operation has completed, the PN_LOCAL_ACTIVE state flag will be set.

Parameters

  [in] | link | a link object

PN_EXTERN int pn_link_queued | ( | pn_link_t * | link | ) |

Get the number of queued deliveries for a link.

Links may queue deliveries for a number of reasons, for example there may be insufficient credit to send them to the receiver (see pn_link_credit), or they simply may not have yet had a chance to be written to the wire. This operation will return the number of queued deliveries on a link.

Parameters

  [in] | link | a link object

Returns
  the number of queued deliveries for the link

PN_EXTERN pn_rcv_settle_mode_t pn_link_rcv_settle_mode | ( | pn_link_t * | link | ) |

Get the local receiver settle mode for a link.

Parameters

  [in] | link | a link object

Returns
  the local receiver settle mode

PN_EXTERN pn_condition_t* pn_link_remote_condition | ( | pn_link_t * | link | ) |

Get the remote condition associated with a link endpoint.

The pn_condition_t object retrieved may be examined in order to determine whether the remote peer was indicating some sort of exceptional condition when the remote link endpoint was closed. The pn_condition_t object returned may not be modified.

The pointer returned by this operation is valid until the link object is freed.

Parameters

  [in] | link | the link object

Returns
  the link's remote condition object

PN_EXTERN int pn_link_remote_credit | ( | pn_link_t * | link | ) |

Get the remote view of the credit for a link.

The remote view of the credit for a link differs from local view of credit for a link by the number of queued deliveries. In other words pn_link_remote_credit is defined to be pn_link_credit - pn_link_queued.

Parameters

  [in] | link | a link object

Returns
  the remote view of the credit for a link

PN_EXTERN pn_rcv_settle_mode_t pn_link_remote_rcv_settle_mode | ( | pn_link_t * | link | ) |

Get the remote receiver settle mode for a link.

Parameters

  [in] | link | a link object

Returns
  the remote receiver settle mode

PN_EXTERN pn_snd_settle_mode_t pn_link_remote_snd_settle_mode | ( | pn_link_t * | link | ) |

Get the remote sender settle mode for a link.

Parameters

  [in] | link | a link object

Returns
  the remote sender settle mode

PN_EXTERN pn_terminus_t* pn_link_remote_source | ( | pn_link_t * | link | ) |

Access the remotely defined source definition for a link.

The pointer returned by this operation is valid until the link object is freed. The remotely defined terminus will be empty until the link is remotely opened as indicated by the PN_REMOTE_ACTIVE flag.

Parameters

  [in] | link | a link object

Returns
  a pointer to the remotely defined source terminus

PN_EXTERN pn_terminus_t* pn_link_remote_target | ( | pn_link_t * | link | ) |

Access the remotely defined target definition for a link.

The pointer returned by this operation is valid until the link object is freed. The remotely defined terminus will be empty until the link is remotely opened as indicated by the PN_REMOTE_ACTIVE flag.

Parameters

  [in] | link | a link object

Returns
  a pointer to the remotely defined target terminus

PN_EXTERN pn_session_t* pn_link_session | ( | pn_link_t * | link | ) |

Get the parent session for a link object.

This operation retrieves the parent pn_session_t object that contains the given pn_link_t object.

Parameters

  [in] | link | the link object

Returns
  the parent session object

PN_EXTERN void pn_link_set_context | ( | pn_link_t * | link,
|  | void * | context
| ) |  |

Deprecated:
  Set a new application context for a link object.

The application context for a link object may be retrieved using pn_link_get_context.

Parameters

  [in] | link | the link object
  [in] | context | the application context

PN_EXTERN void pn_link_set_rcv_settle_mode | ( | pn_link_t * | link,
|  | pn_rcv_settle_mode_t | mode
| ) |  |

Set the local receiver settle mode for a link.

Parameters

  [in] | link | a link object
  [in] | mode | the receiver settle mode

PN_EXTERN void pn_link_set_snd_settle_mode | ( | pn_link_t * | link,
|  | pn_snd_settle_mode_t | mode
| ) |  |

Set the local sender settle mode for a link.

Parameters

  [in] | link | a link object
  [in] | mode | the sender settle mode

PN_EXTERN pn_snd_settle_mode_t pn_link_snd_settle_mode | ( | pn_link_t * | link | ) |

Get the local sender settle mode for a link.

Parameters

  [in] | link | a link object

Returns
  the local sender settle mode

PN_EXTERN pn_terminus_t* pn_link_source | ( | pn_link_t * | link | ) |

Access the locally defined source definition for a link.

The pointer returned by this operation is valid until the link object is freed.

Parameters

  [in] | link | a link object

Returns
  a pointer to a source terminus

PN_EXTERN pn_state_t pn_link_state | ( | pn_link_t * | link | ) |

Get the endpoint state flags for a link.

Parameters

  [in] | link | the link

Returns
  the link's state flags

PN_EXTERN pn_terminus_t* pn_link_target | ( | pn_link_t * | link | ) |

Access the locally defined target definition for a link.

The pointer returned by this operation is valid until the link object is freed.

Parameters

  [in] | link | a link object

Returns
  a pointer to a target terminus

PN_EXTERN int pn_link_unsettled | ( | pn_link_t * | link | ) |

Get the number of unsettled deliveries for a link.

Parameters

  [in] | link | a link object

Returns
  the number of unsettled deliveries

PN_EXTERN pn_link_t* pn_receiver | ( | pn_session_t * | session,
|  | const char * | name
| ) |  |

Construct a new receiver on a session.

Each receiving link between two AMQP containers must be uniquely named. Note that this uniqueness cannot be enforced at the API level, so some consideration should be taken in choosing link names.

Parameters

  [in] | session | the session object
  [in] | name | the name of the link

Returns
  a newly constructed receiver link or NULL on error

PN_EXTERN pn_link_t* pn_sender | ( | pn_session_t * | session,
|  | const char * | name
| ) |  |

Construct a new sender on a session.

Each sending link between two AMQP containers must be uniquely named. Note that this uniqueness cannot be enforced at the API level, so some consideration should be taken in choosing link names.

Parameters

  [in] | session | the session object
  [in] | name | the name of the link

Returns
  a newly constructed sender link or NULL on error

PN_EXTERN pn_delivery_t* pn_unsettled_head | ( | pn_link_t * | link | ) |

Get the first unsettled delivery for a link.

"

Parameters

  [in] | link | a link object

Returns
  a pointer to the first unsettled delivery on the link

PN_EXTERN pn_delivery_t* pn_unsettled_next | ( | pn_delivery_t * | delivery | ) |

Get the next unsettled delivery on a link.

Parameters

  [in] | delivery | a delivery object

Returns
  the next unsettled delivery on the link