proton
0
|
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) |
Get the application context that is associated with a link object. More... | |
PN_EXTERN void | pn_link_set_context (pn_link_t *link, void *context) |
Set a new application context for 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 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... | |
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.
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.
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.
[in] | link | a link object |
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.
[in] | link | a link object |
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.
[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.
[in] | link | the link object |
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.
[in] | link | a link object |
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.
[in] | link | a link object |
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.
[in] | link | a link object |
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.
[in] | link | the link object |
Free a link object.
When a link object is freed, all pn_delivery_t objects associated with the session are also freed.
[in] | link | a link object to free (or NULL) |
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.
[in] | link | the link whose context is to be returned. |
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.
[in] | link | a link object |
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.
[in] | connection | to be searched for matching Links |
[in] | state | mask to match |
Test if a link is a receiver.
[in] | link | a link object |
Test if a link is a sender.
[in] | link | a link object |
Get the name of a link.
[in] | link | a link object |
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.
[in] | link | the previous link obtained from pn_link_head or pn_link_next |
[in] | state | mask to match |
Open a link.
Once this operation has completed, the PN_LOCAL_ACTIVE state flag will be set.
[in] | link | a link object |
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.
[in] | link | a link object |
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.
[in] | link | a link object |
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.
[in] | link | the link object |
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.
[in] | link | a link object |
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.
[in] | link | a link object |
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.
[in] | link | a link object |
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.
[in] | link | a link object |
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.
[in] | link | a link object |
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.
[in] | link | the link object |
Set a new application context for a link object.
The application context for a link object may be retrieved using pn_link_get_context.
[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.
[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.
[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.
[in] | link | a link object |
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.
[in] | link | a link object |
PN_EXTERN pn_state_t pn_link_state | ( | pn_link_t * | link | ) |
Get the endpoint state flags for a link.
[in] | link | the link |
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.
[in] | link | a link object |
Get the number of unsettled deliveries for a link.
[in] | link | a link object |
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.
[in] | session | the session object |
[in] | name | the name of the link |
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.
[in] | session | the session object |
[in] | name | the name of the link |
PN_EXTERN pn_delivery_t* pn_unsettled_head | ( | pn_link_t * | link | ) |
Get the first unsettled delivery for a link.
"
[in] | link | a link object |
PN_EXTERN pn_delivery_t* pn_unsettled_next | ( | pn_delivery_t * | delivery | ) |
Get the next unsettled delivery on a link.
[in] | delivery | a delivery object |