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