proton  0
link.h
Go to the documentation of this file.
1 #ifndef PROTON_LINK_H
2 #define PROTON_LINK_H 1
3 
4 /*
5  *
6  * Licensed to the Apache Software Foundation (ASF) under one
7  * or more contributor license agreements. See the NOTICE file
8  * distributed with this work for additional information
9  * regarding copyright ownership. The ASF licenses this file
10  * to you under the Apache License, Version 2.0 (the
11  * "License"); you may not use this file except in compliance
12  * with the License. You may obtain a copy of the License at
13  *
14  * http://www.apache.org/licenses/LICENSE-2.0
15  *
16  * Unless required by applicable law or agreed to in writing,
17  * software distributed under the License is distributed on an
18  * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
19  * KIND, either express or implied. See the License for the
20  * specific language governing permissions and limitations
21  * under the License.
22  *
23  */
24 
25 #include <proton/import_export.h>
26 #include <proton/type_compat.h>
27 #include <proton/condition.h>
28 #include <proton/terminus.h>
29 #include <proton/types.h>
30 #include <proton/object.h>
31 #include <stddef.h>
32 
33 #ifdef __cplusplus
34 extern "C" {
35 #endif
36 
37 /**
38  * @file
39  *
40  * Link API for the proton Engine.
41  *
42  * @defgroup link Link
43  * @ingroup engine
44  * @{
45  */
46 
47 /**
48  * Construct a new sender on a session.
49  *
50  * Each sending link between two AMQP containers must be uniquely
51  * named. Note that this uniqueness cannot be enforced at the API
52  * level, so some consideration should be taken in choosing link
53  * names.
54  *
55  * @param[in] session the session object
56  * @param[in] name the name of the link
57  * @return a newly constructed sender link or NULL on error
58  */
59 PN_EXTERN pn_link_t *pn_sender(pn_session_t *session, const char *name);
60 
61 /**
62  * Construct a new receiver on a session.
63  *
64  * Each receiving link between two AMQP containers must be uniquely
65  * named. Note that this uniqueness cannot be enforced at the API
66  * level, so some consideration should be taken in choosing link
67  * names.
68  *
69  * @param[in] session the session object
70  * @param[in] name the name of the link
71  * @return a newly constructed receiver link or NULL on error
72  */
73 PN_EXTERN pn_link_t *pn_receiver(pn_session_t *session, const char *name);
74 
75 /**
76  * Free a link object.
77  *
78  * When a link object is freed, all ::pn_delivery_t objects associated
79  * with the session are also freed. Freeing a link will settle any
80  * unsettled deliveries on the link.
81  *
82  * @param[in] link a link object to free (or NULL)
83  */
84 PN_EXTERN void pn_link_free(pn_link_t *link);
85 
86 /**
87  * @deprecated
88  * Get the application context that is associated with a link object.
89  *
90  * The application context for a link may be set using
91  * ::pn_link_set_context.
92  *
93  * @param[in] link the link whose context is to be returned.
94  * @return the application context for the link object
95  */
97 
98 /**
99  * @deprecated
100  * Set a new application context for a link object.
101  *
102  * The application context for a link object may be retrieved using
103  * ::pn_link_get_context.
104  *
105  * @param[in] link the link object
106  * @param[in] context the application context
107  */
108 PN_EXTERN void pn_link_set_context(pn_link_t *link, void *context);
109 
110 /**
111  * Get the attachments that are associated with a link object.
112  *
113  * @param[in] link the link whose attachments are to be returned.
114  * @return the attachments for the link object
115  */
117 
118 /**
119  * Get the name of a link.
120  *
121  * @param[in] link a link object
122  * @return the name of the link
123  */
124 PN_EXTERN const char *pn_link_name(pn_link_t *link);
125 
126 /**
127  * Test if a link is a sender.
128  *
129  * @param[in] link a link object
130  * @return true if and only if the link is a sender
131  */
133 
134 /**
135  * Test if a link is a receiver.
136  *
137  * @param[in] link a link object
138  * @return true if and only if the link is a receiver
139  */
141 
142 /**
143  * Get the endpoint state flags for a link.
144  *
145  * @param[in] link the link
146  * @return the link's state flags
147  */
149 
150 /**
151  * Get additional error information associated with the link.
152  *
153  * Whenever a link operation fails (i.e. returns an error code),
154  * additional error details can be obtained using this function. The
155  * error object that is returned may also be used to clear the error
156  * condition.
157  *
158  * The pointer returned by this operation is valid until the
159  * link object is freed.
160  *
161  * @param[in] link the link object
162  * @return the link's error object
163  */
165 
166 /**
167  * Get the local condition associated with a link endpoint.
168  *
169  * The ::pn_condition_t object retrieved may be modified prior to
170  * closing a link in order to indicate a particular condition
171  * exists when the link closes. This is normally used to
172  * communicate error conditions to the remote peer, however it may
173  * also be used in non error cases. See ::pn_condition_t for more
174  * details.
175  *
176  * The pointer returned by this operation is valid until the link
177  * object is freed.
178  *
179  * @param[in] link the link object
180  * @return the link's local condition object
181  */
183 
184 /**
185  * Get the remote condition associated with a link endpoint.
186  *
187  * The ::pn_condition_t object retrieved may be examined in order to
188  * determine whether the remote peer was indicating some sort of
189  * exceptional condition when the remote link endpoint was
190  * closed. The ::pn_condition_t object returned may not be modified.
191  *
192  * The pointer returned by this operation is valid until the
193  * link object is freed.
194  *
195  * @param[in] link the link object
196  * @return the link's remote condition object
197  */
199 
200 /**
201  * Get the parent session for a link object.
202  *
203  * This operation retrieves the parent ::pn_session_t object that
204  * contains the given ::pn_link_t object.
205  *
206  * @param[in] link the link object
207  * @return the parent session object
208  */
210 
211 /**
212  * Retrieve the first link that matches the given state mask.
213  *
214  * Examines the state of each link owned by the connection and returns
215  * the first link that matches the given state mask. If state contains
216  * both local and remote flags, then an exact match against those
217  * flags is performed. If state contains only local or only remote
218  * flags, then a match occurs if any of the local or remote flags are
219  * set respectively. state==0 matches all links.
220  *
221  * @param[in] connection to be searched for matching Links
222  * @param[in] state mask to match
223  * @return the first link owned by the connection that matches the
224  * mask, else NULL if no links match
225  */
227 
228 /**
229  * Retrieve the next link that matches the given state mask.
230  *
231  * When used with pn_link_head, the application can access all links
232  * on the connection that match the given state. See pn_link_head for
233  * description of match behavior.
234  *
235  * @param[in] link the previous link obtained from pn_link_head or
236  * pn_link_next
237  * @param[in] state mask to match
238  * @return the next session owned by the connection that matches the
239  * mask, else NULL if no sessions match
240  */
242 
243 /**
244  * Open a link.
245  *
246  * Once this operation has completed, the PN_LOCAL_ACTIVE state flag
247  * will be set.
248  *
249  * @param[in] link a link object
250  */
251 PN_EXTERN void pn_link_open(pn_link_t *link);
252 
253 /**
254  * Close a link.
255  *
256  * Once this operation has completed, the PN_LOCAL_CLOSED state flag
257  * will be set. This may be called without calling
258  * ::pn_link_open, in this case it is equivalent to calling
259  * ::pn_link_open followed by ::pn_link_close.
260  *
261  * @param[in] link a link object
262  */
263 PN_EXTERN void pn_link_close(pn_link_t *link);
264 
265 /**
266  * Detach a link.
267  *
268  * @param[in] link a link object
269  */
271 
272 /**
273  * Access the locally defined source definition for a link.
274  *
275  * The pointer returned by this operation is valid until the link
276  * object is freed.
277  *
278  * @param[in] link a link object
279  * @return a pointer to a source terminus
280  */
282 
283 /**
284  * Access the locally defined target definition for a link.
285  *
286  * The pointer returned by this operation is valid until the link
287  * object is freed.
288  *
289  * @param[in] link a link object
290  * @return a pointer to a target terminus
291  */
293 
294 /**
295  * Access the remotely defined source definition for a link.
296  *
297  * The pointer returned by this operation is valid until the link
298  * object is freed. The remotely defined terminus will be empty until
299  * the link is remotely opened as indicated by the PN_REMOTE_ACTIVE
300  * flag.
301  *
302  * @param[in] link a link object
303  * @return a pointer to the remotely defined source terminus
304  */
306 
307 /**
308  * Access the remotely defined target definition for a link.
309  *
310  * The pointer returned by this operation is valid until the link
311  * object is freed. The remotely defined terminus will be empty until
312  * the link is remotely opened as indicated by the PN_REMOTE_ACTIVE
313  * flag.
314  *
315  * @param[in] link a link object
316  * @return a pointer to the remotely defined target terminus
317  */
319 
320 /**
321  * Get the current delivery for a link.
322  *
323  * Each link maintains a sequence of deliveries in the order they were
324  * created, along with a pointer to the *current* delivery. All
325  * send/recv operations on a link take place on the *current*
326  * delivery. If a link has no current delivery, the current delivery
327  * is automatically initialized to the next delivery created on the
328  * link. Once initialized, the current delivery remains the same until
329  * it is changed through use of ::pn_link_advance or until it is
330  * settled via ::pn_delivery_settle.
331  *
332  * @param[in] link a link object
333  * @return the current delivery for the link, or NULL if there is none
334  */
336 
337 /**
338  * Advance the current delivery of a link to the next delivery on the
339  * link.
340  *
341  * For sending links this operation is used to finish sending message
342  * data for the current outgoing delivery and move on to the next
343  * outgoing delivery (if any).
344  *
345  * For receiving links, this operation is used to finish accessing
346  * message data from the current incoming delivery and move on to the
347  * next incoming delivery (if any).
348  *
349  * Each link maintains a sequence of deliveries in the order they were
350  * created, along with a pointer to the *current* delivery. The
351  * pn_link_advance operation will modify the *current* delivery on the
352  * link to point to the next delivery in the sequence. If there is no
353  * next delivery in the sequence, the current delivery will be set to
354  * NULL. This operation will return true if invoking it caused the
355  * value of the current delivery to change, even if it was set to
356  * NULL.
357  *
358  * @param[in] link a link object
359  * @return true if the current delivery was changed
360  */
362 
363 /**
364  * Get the credit balance for a link.
365  *
366  * Links use a credit based flow control scheme. Every receiver
367  * maintains a credit balance that corresponds to the number of
368  * deliveries that the receiver can accept at any given moment. As
369  * more capacity becomes available at the receiver (see
370  * ::pn_link_flow), it adds credit to this balance and communicates
371  * the new balance to the sender. Whenever a delivery is
372  * sent/received, the credit balance maintained by the link is
373  * decremented by one. Once the credit balance at the sender reaches
374  * zero, the sender must pause sending until more credit is obtained
375  * from the receiver.
376  *
377  * Note that a sending link may still be used to send deliveries even
378  * if pn_link_credit reaches zero, however those deliveries will end
379  * up being buffered by the link until enough credit is obtained from
380  * the receiver to send them over the wire. In this case the balance
381  * reported by ::pn_link_credit will go negative.
382  *
383  * @param[in] link a link object
384  * @return the credit balance for the link
385  */
387 
388 /**
389  * Get the number of queued deliveries for a link.
390  *
391  * Links may queue deliveries for a number of reasons, for example
392  * there may be insufficient credit to send them to the receiver (see
393  * ::pn_link_credit), or they simply may not have yet had a chance to
394  * be written to the wire. This operation will return the number of
395  * queued deliveries on a link.
396  *
397  * @param[in] link a link object
398  * @return the number of queued deliveries for the link
399  */
401 
402 /**
403  * Get the remote view of the credit for a link.
404  *
405  * The remote view of the credit for a link differs from local view of
406  * credit for a link by the number of queued deliveries. In other
407  * words ::pn_link_remote_credit is defined to be ::pn_link_credit -
408  * ::pn_link_queued.
409  *
410  * @param[in] link a link object
411  * @return the remote view of the credit for a link
412  */
414 
415 /**
416  * Get the drain flag for a link.
417  *
418  * If a link is in drain mode, then the sending endpoint of a link
419  * must immediately use up all available credit on the link. If this
420  * is not possible, the excess credit must be returned by invoking
421  * ::pn_link_drained. Only the receiving endpoint can set the drain
422  * mode. See ::pn_link_set_drain for details.
423  *
424  * @param[in] link a link object
425  * @return true if and only if the link is in drain mode
426  */
428 
429 /**
430  * Drain excess credit for a link.
431  *
432  * When a link is in drain mode, the sender must use all excess credit
433  * immediately, and release any excess credit back to the receiver if
434  * there are no deliveries available to send.
435  *
436  * When invoked on a sending link that is in drain mode, this
437  * operation will release all excess credit back to the receiver and
438  * return the number of credits released back to the sender. If the
439  * link is not in drain mode, this operation is a noop.
440  *
441  * When invoked on a receiving link, this operation will return and
442  * reset the number of credits the sender has released back to the
443  * receiver.
444  *
445  * @param[in] link a link object
446  * @return the number of credits drained
447  */
449 
450 /**
451  * Get the available deliveries hint for a link.
452  *
453  * The available count for a link provides a hint as to the number of
454  * deliveries that might be able to be sent if sufficient credit were
455  * issued by the receiving link endpoint. See ::pn_link_offered for
456  * more details.
457  *
458  * @param[in] link a link object
459  * @return the available deliveries hint
460  */
462 
463 /**
464  * Describes the permitted/expected settlement behaviours of a sending
465  * link.
466  *
467  * The sender settle mode describes the permitted and expected
468  * behaviour of a sending link with respect to settling of deliveries.
469  * See ::pn_delivery_settle for more details.
470  */
471 typedef enum {
472  PN_SND_UNSETTLED = 0, /**< The sender will send all deliveries
473  initially unsettled. */
474  PN_SND_SETTLED = 1, /**< The sender will send all deliveries settled
475  to the receiver. */
476  PN_SND_MIXED = 2 /**< The sender may send a mixure of settled and
477  unsettled deliveries. */
479 
480 /**
481  * Describes the permitted/expected settlement behaviours of a
482  * receiving link.
483  *
484  * The receiver settle mode describes the permitted and expected
485  * behaviour of a receiving link with respect to settling of
486  * deliveries. See ::pn_delivery_settle for more details.
487  */
488 typedef enum {
489  PN_RCV_FIRST = 0, /**< The receiver will settle deliveries
490  regardless of what the sender does. */
491  PN_RCV_SECOND = 1 /**< The receiver will only settle deliveries
492  after the sender settles. */
494 
495 /**
496  * Get the local sender settle mode for a link.
497  *
498  * @param[in] link a link object
499  * @return the local sender settle mode
500  */
502 
503 /**
504  * Get the local receiver settle mode for a link.
505  *
506  * @param[in] link a link object
507  * @return the local receiver settle mode
508  */
510 
511 /**
512  * Set the local sender settle mode for a link.
513  *
514  * @param[in] link a link object
515  * @param[in] mode the sender settle mode
516  */
518 
519 /**
520  * Set the local receiver settle mode for a link.
521  *
522  * @param[in] link a link object
523  * @param[in] mode the receiver settle mode
524  */
526 
527 /**
528  * Get the remote sender settle mode for a link.
529  *
530  * @param[in] link a link object
531  * @return the remote sender settle mode
532  */
534 
535 /**
536  * Get the remote receiver settle mode for a link.
537  *
538  * @param[in] link a link object
539  * @return the remote receiver settle mode
540  */
542 
543 /**
544  * Get the number of unsettled deliveries for a link.
545  *
546  * @param[in] link a link object
547  * @return the number of unsettled deliveries
548  */
550 
551 /**
552  * Get the first unsettled delivery for a link.
553  *
554  " @param[in] link a link object
555  * @return a pointer to the first unsettled delivery on the link
556  */
558 
559 /**
560  * Get the next unsettled delivery on a link.
561  *
562  * @param[in] delivery a delivery object
563  * @return the next unsettled delivery on the link
564  */
566 
567 /**
568  * @defgroup sender Sender
569  * @{
570  */
571 
572 /**
573  * Signal the availability of deliveries for a link.
574  *
575  * @param[in] sender a sender link object
576  * @param[in] credit the number of deliveries potentially available
577  * for transfer
578  */
579 PN_EXTERN void pn_link_offered(pn_link_t *sender, int credit);
580 
581 /**
582  * Send message data for the current delivery on a link.
583  *
584  * @param[in] sender a sender link object
585  * @param[in] bytes the start of the message data
586  * @param[in] n the number of bytes of message data
587  * @return the number of bytes sent, or an error code
588  */
589 PN_EXTERN ssize_t pn_link_send(pn_link_t *sender, const char *bytes, size_t n);
590 
591 //PN_EXTERN void pn_link_abort(pn_sender_t *sender);
592 
593 /** @} */
594 
595 // receiver
596 /**
597  * @defgroup receiver Receiver
598  * @{
599  */
600 
601 /**
602  * Grant credit for incoming deliveries on a receiver.
603  *
604  * @param[in] receiver a receiving link object
605  * @param[in] credit the amount to increment the link credit
606  */
607 PN_EXTERN void pn_link_flow(pn_link_t *receiver, int credit);
608 
609 /**
610  * Grant credit for incoming deliveries on a receiver, and set drain
611  * mode to true.
612  *
613  * Use ::pn_link_set_drain to set the drain mode explicitly.
614  *
615  * @param[in] receiver a receiving link object
616  * @param[in] credit the amount to increment the link credit
617  */
618 PN_EXTERN void pn_link_drain(pn_link_t *receiver, int credit);
619 
620 /**
621  * Set the drain mode on a link.
622  *
623  * @param[in] receiver a receiving link object
624  * @param[in] drain the drain mode
625  */
626 PN_EXTERN void pn_link_set_drain(pn_link_t *receiver, bool drain);
627 
628 /**
629  * Receive message data for the current delivery on a link.
630  *
631  * Use ::pn_delivery_pending on the current delivery to figure out how
632  * much buffer space is needed.
633  *
634  * Note that the link API can be used to stream large messages across
635  * the network, so just because there is no data to read does not
636  * imply the message is complete. To ensure the entirety of the
637  * message data has been read, either invoke ::pn_link_recv until
638  * PN_EOS is returned, or verify that ::pn_delivery_partial is false,
639  * and ::pn_delivery_pending is 0.
640  *
641  * @param[in] receiver a receiving link object
642  * @param[in] bytes a pointer to an empty buffer
643  * @param[in] n the buffer capacity
644  * @return the number of bytes received, PN_EOS, or an error code
645  */
646 PN_EXTERN ssize_t pn_link_recv(pn_link_t *receiver, char *bytes, size_t n);
647 
648 /**
649  * Check if a link is currently draining.
650  *
651  * A link is defined to be draining when drain mode is set to true,
652  * and the sender still has excess credit.
653  *
654  * @param[in] receiver a receiving link object
655  * @return true if the link is currently draining, false otherwise
656  */
657 PN_EXTERN bool pn_link_draining(pn_link_t *receiver);
658 
659 /** @} */
660 
661 /** @}
662  */
663 
664 #ifdef __cplusplus
665 }
666 #endif
667 
668 #endif /* link.h */
669 
PN_EXTERN bool pn_link_draining(pn_link_t *receiver)
Check if a link is currently draining.
struct pn_record_t pn_record_t
Definition: object.h:46
struct pn_terminus_t pn_terminus_t
Encapsulates the endpoint state associated with an AMQP Terminus.
Definition: terminus.h:53
#define PN_EXTERN
Definition: import_export.h:53
struct pn_session_t pn_session_t
An AMQP Session object.
Definition: types.h:123
PN_EXTERN ssize_t pn_link_send(pn_link_t *sender, const char *bytes, size_t n)
Send message data for the current delivery on a link.
Terminus API for the proton Engine.
The Condition API for the proton Engine.
struct pn_delivery_t pn_delivery_t
An AMQP Delivery object.
Definition: types.h:232
PN_EXTERN ssize_t pn_link_recv(pn_link_t *receiver, char *bytes, size_t n)
Receive message data for the current delivery on a link.
PN_EXTERN void pn_link_set_drain(pn_link_t *receiver, bool drain)
Set the drain mode on a link.
struct pn_error_t pn_error_t
A pn_error_t has an int error code and some string text to describe the error.
Definition: error.h:33
struct pn_connection_t pn_connection_t
An AMQP Connection object.
Definition: types.h:112
PN_EXTERN void pn_link_offered(pn_link_t *sender, int credit)
Signal the availability of deliveries for a link.
struct pn_condition_t pn_condition_t
An AMQP Condition object.
Definition: condition.h:64
PN_EXTERN void pn_link_drain(pn_link_t *receiver, int credit)
Grant credit for incoming deliveries on a receiver, and set drain mode to true.
int pn_state_t
Holds the state flags for an AMQP endpoint.
Definition: types.h:97
PN_EXTERN void pn_link_flow(pn_link_t *receiver, int credit)
Grant credit for incoming deliveries on a receiver.