C AMQP Protocol Engine API  0.7
 All Classes Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
Link
Collaboration diagram for Link:

Modules

 Sender
 
 Receiver
 
 Terminus
 

Typedefs

typedef struct pn_link_t pn_link_t
 

Enumerations

enum  pn_snd_settle_mode_t { PN_SND_UNSETTLED = 0, PN_SND_SETTLED = 1, PN_SND_MIXED = 2 }
 
enum  pn_rcv_settle_mode_t { PN_RCV_FIRST = 0, PN_RCV_SECOND = 1 }
 

Functions

PN_EXTERN pn_link_tpn_sender (pn_session_t *session, const char *name)
 
PN_EXTERN pn_link_tpn_receiver (pn_session_t *session, const char *name)
 
PN_EXTERN void pn_link_free (pn_link_t *link)
 
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 const char * pn_link_name (pn_link_t *link)
 
PN_EXTERN bool pn_link_is_sender (pn_link_t *link)
 
PN_EXTERN bool pn_link_is_receiver (pn_link_t *link)
 
PN_EXTERN pn_state_t pn_link_state (pn_link_t *link)
 
PN_EXTERN pn_error_tpn_link_error (pn_link_t *link)
 
PN_EXTERN pn_condition_tpn_link_condition (pn_link_t *link)
 
PN_EXTERN pn_condition_tpn_link_remote_condition (pn_link_t *link)
 
PN_EXTERN pn_session_tpn_link_session (pn_link_t *link)
 
PN_EXTERN pn_link_tpn_link_head (pn_connection_t *connection, pn_state_t state)
 
PN_EXTERN pn_link_tpn_link_next (pn_link_t *link, pn_state_t state)
 
PN_EXTERN void pn_link_open (pn_link_t *link)
 
PN_EXTERN void pn_link_close (pn_link_t *link)
 
PN_EXTERN pn_terminus_tpn_link_source (pn_link_t *link)
 
PN_EXTERN pn_terminus_tpn_link_target (pn_link_t *link)
 
PN_EXTERN pn_terminus_tpn_link_remote_source (pn_link_t *link)
 
PN_EXTERN pn_terminus_tpn_link_remote_target (pn_link_t *link)
 
PN_EXTERN pn_delivery_tpn_link_current (pn_link_t *link)
 
PN_EXTERN bool pn_link_advance (pn_link_t *link)
 
PN_EXTERN int pn_link_credit (pn_link_t *link)
 
PN_EXTERN int pn_link_queued (pn_link_t *link)
 
PN_EXTERN int pn_link_remote_credit (pn_link_t *link)
 
PN_EXTERN bool pn_link_get_drain (pn_link_t *link)
 
PN_EXTERN int pn_link_drained (pn_link_t *link)
 
PN_EXTERN int pn_link_available (pn_link_t *link)
 
PN_EXTERN pn_snd_settle_mode_t pn_link_snd_settle_mode (pn_link_t *link)
 
PN_EXTERN pn_rcv_settle_mode_t pn_link_rcv_settle_mode (pn_link_t *link)
 
PN_EXTERN void pn_link_set_snd_settle_mode (pn_link_t *link, pn_snd_settle_mode_t mode)
 
PN_EXTERN void pn_link_set_rcv_settle_mode (pn_link_t *link, pn_rcv_settle_mode_t mode)
 
PN_EXTERN pn_snd_settle_mode_t pn_link_remote_snd_settle_mode (pn_link_t *link)
 
PN_EXTERN pn_rcv_settle_mode_t pn_link_remote_rcv_settle_mode (pn_link_t *link)
 
PN_EXTERN int pn_link_unsettled (pn_link_t *link)
 
PN_EXTERN pn_delivery_tpn_unsettled_head (pn_link_t *link)
 
PN_EXTERN pn_delivery_tpn_unsettled_next (pn_delivery_t *delivery)
 

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

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.

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]linka link object
Returns
true if the current delivery was changed
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]linka 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]linka 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]linkthe 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]linka 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]linka link object
Returns
the current delivery for the link, or NULL if there is none
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]linka 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]linkthe 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.

Parameters
[in]linka link object to free (or NULL)
PN_EXTERN void* pn_link_get_context ( pn_link_t link)

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]linkthe 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]linka 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]connectionto be searched for matching Links
[in]statemask 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]linka 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]linka 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]linka 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]linkthe previous link obtained from pn_link_head or pn_link_next
[in]statemask 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]linka 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]linka 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]linka 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]linkthe 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]linka 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]linka 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]linka 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]linka 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]linka 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]linkthe link object
Returns
the parent session object
PN_EXTERN void pn_link_set_context ( pn_link_t link,
void *  context 
)

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]linkthe link object
[in]contextthe 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]linka link object
[in]modethe 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]linka link object
[in]modethe 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]linka 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]linka 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]linkthe 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]linka 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]linka 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]sessionthe session object
[in]namethe 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]sessionthe session object
[in]namethe 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]linka 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]deliverya delivery object
Returns
the next unsettled delivery on the link