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
proton-c
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 Mon Jun 2 2014 22:59:05 for proton by
1.8.1.2