proton
0
Main Page
Related Pages
Modules
Data Structures
Files
File List
Globals
All
Data Structures
Files
Functions
Variables
Typedefs
Enumerations
Enumerator
Macros
Groups
Pages
include
proton
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
*/
91
PN_EXTERN
void
*
pn_link_get_context
(
pn_link_t
*link);
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
*/
118
PN_EXTERN
bool
pn_link_is_sender
(
pn_link_t
*link);
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
*/
126
PN_EXTERN
bool
pn_link_is_receiver
(
pn_link_t
*link);
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
*/
134
PN_EXTERN
pn_state_t
pn_link_state
(
pn_link_t
*link);
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
*/
150
PN_EXTERN
pn_error_t
*
pn_link_error
(
pn_link_t
*link);
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
*/
168
PN_EXTERN
pn_condition_t
*
pn_link_condition
(
pn_link_t
*link);
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
*/
184
PN_EXTERN
pn_condition_t
*
pn_link_remote_condition
(
pn_link_t
*link);
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
*/
195
PN_EXTERN
pn_session_t
*
pn_link_session
(
pn_link_t
*link);
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
*/
212
PN_EXTERN
pn_link_t
*
pn_link_head
(
pn_connection_t
*connection,
pn_state_t
state);
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
*/
227
PN_EXTERN
pn_link_t
*
pn_link_next
(
pn_link_t
*link,
pn_state_t
state);
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
*/
260
PN_EXTERN
pn_terminus_t
*
pn_link_source
(
pn_link_t
*link);
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
*/
271
PN_EXTERN
pn_terminus_t
*
pn_link_target
(
pn_link_t
*link);
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
*/
284
PN_EXTERN
pn_terminus_t
*
pn_link_remote_source
(
pn_link_t
*link);
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
*/
297
PN_EXTERN
pn_terminus_t
*
pn_link_remote_target
(
pn_link_t
*link);
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
*/
314
PN_EXTERN
pn_delivery_t
*
pn_link_current
(
pn_link_t
*link);
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
*/
340
PN_EXTERN
bool
pn_link_advance
(
pn_link_t
*link);
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
*/
365
PN_EXTERN
int
pn_link_credit
(
pn_link_t
*link);
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
*/
379
PN_EXTERN
int
pn_link_queued
(
pn_link_t
*link);
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
*/
392
PN_EXTERN
int
pn_link_remote_credit
(
pn_link_t
*link);
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
*/
406
PN_EXTERN
bool
pn_link_get_drain
(
pn_link_t
*link);
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
*/
427
PN_EXTERN
int
pn_link_drained
(
pn_link_t
*link);
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
*/
440
PN_EXTERN
int
pn_link_available
(
pn_link_t
*link);
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. */
457
}
pn_snd_settle_mode_t
;
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. */
472
}
pn_rcv_settle_mode_t
;
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
*/
480
PN_EXTERN
pn_snd_settle_mode_t
pn_link_snd_settle_mode
(
pn_link_t
*link);
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
*/
488
PN_EXTERN
pn_rcv_settle_mode_t
pn_link_rcv_settle_mode
(
pn_link_t
*link);
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
*/
496
PN_EXTERN
void
pn_link_set_snd_settle_mode
(
pn_link_t
*link,
pn_snd_settle_mode_t
mode);
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
*/
504
PN_EXTERN
void
pn_link_set_rcv_settle_mode
(
pn_link_t
*link,
pn_rcv_settle_mode_t
mode);
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
*/
512
PN_EXTERN
pn_snd_settle_mode_t
pn_link_remote_snd_settle_mode
(
pn_link_t
*link);
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
*/
520
PN_EXTERN
pn_rcv_settle_mode_t
pn_link_remote_rcv_settle_mode
(
pn_link_t
*link);
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
*/
528
PN_EXTERN
int
pn_link_unsettled
(
pn_link_t
*link);
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
*/
536
PN_EXTERN
pn_delivery_t
*
pn_unsettled_head
(
pn_link_t
*link);
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
*/
544
PN_EXTERN
pn_delivery_t
*
pn_unsettled_next
(
pn_delivery_t
*delivery);
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
Generated on Thu Jul 10 2014 02:10:59 for proton by
1.8.3.1