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
transport.h
Go to the documentation of this file.
1
#ifndef PROTON_TRANSPORT_H
2
#define PROTON_TRANSPORT_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
* Transport API for the proton Engine.
38
*
39
* @defgroup transport Transport
40
* @ingroup engine
41
* @{
42
*/
43
44
/**
45
* Holds the trace flags for an AMQP transport.
46
*
47
* The trace flags for an AMQP transport control what sort of
48
* information is logged by an AMQP transport. The following bits can
49
* be set:
50
*
51
* - ::PN_TRACE_OFF
52
* - ::PN_TRACE_RAW
53
* - ::PN_TRACE_FRM
54
* - ::PN_TRACE_DRV
55
*
56
*/
57
typedef
int
pn_trace_t
;
58
59
/**
60
* Callback for customizing logging behaviour.
61
*/
62
typedef
void (*
pn_tracer_t
)(
pn_transport_t
*transport,
const
char
*message);
63
64
/**
65
* Turn logging off entirely.
66
*/
67
#define PN_TRACE_OFF (0)
68
69
/**
70
* Log raw binary data into/out of the transport.
71
*/
72
#define PN_TRACE_RAW (1)
73
74
/**
75
* Log frames into/out of the transport.
76
*/
77
#define PN_TRACE_FRM (2)
78
79
/**
80
* Log driver related events, e.g. initialization, end of stream, etc.
81
*/
82
#define PN_TRACE_DRV (4)
83
84
/**
85
* Factory for creating a transport.
86
*
87
* A transport is used by a connection to interface with the network.
88
* There can only be one connection associated with a transport. See
89
* pn_transport_bind().
90
*
91
* @return pointer to new transport
92
*/
93
PN_EXTERN
pn_transport_t
*
pn_transport
(
void
);
94
95
/**
96
* Free a transport object.
97
*
98
* When a transport is freed, it is automatically unbound from its
99
* associated connection.
100
*
101
* @param[in] transport a transport object or NULL
102
*/
103
PN_EXTERN
void
pn_transport_free
(
pn_transport_t
*transport);
104
105
/**
106
* Get additional error information associated with the transport.
107
*
108
* Whenever a transport operation fails (i.e. returns an error code),
109
* additional error details can be obtained using this function. The
110
* error object that is returned may also be used to clear the error
111
* condition.
112
*
113
* The pointer returned by this operation is valid until the
114
* transport object is freed.
115
*
116
* @param[in] transport the transport object
117
* @return the transport's error object
118
*/
119
PN_EXTERN
pn_error_t
*
pn_transport_error
(
pn_transport_t
*transport);
120
121
/**
122
* Binds the transport to an AMQP connection.
123
*
124
* @return an error code, or 0 on success
125
*/
126
PN_EXTERN
int
pn_transport_bind
(
pn_transport_t
*transport,
pn_connection_t
*connection);
127
128
/**
129
* Unbinds a transport from its AMQP connection.
130
*
131
* @return an error code, or 0 on success
132
*/
133
PN_EXTERN
int
pn_transport_unbind
(
pn_transport_t
*transport);
134
135
/**
136
* Update a transports trace flags.
137
*
138
* The trace flags for a transport control what sort of information is
139
* logged. See ::pn_trace_t for more details.
140
*
141
* @param[in] transport a transport object
142
* @param[in] trace the trace flags
143
*/
144
PN_EXTERN
void
pn_transport_trace
(
pn_transport_t
*transport, pn_trace_t trace);
145
146
/**
147
* Set the tracing function used by a transport.
148
*
149
* The tracing function is called to perform logging. Overriding this
150
* function allows embedding applications to divert the engine's
151
* logging to a place of their choice.
152
*
153
* @param[in] transport a transport object
154
* @param[in] tracer the tracing function
155
*/
156
PN_EXTERN
void
pn_transport_set_tracer
(
pn_transport_t
*transport,
pn_tracer_t
tracer);
157
158
/**
159
* Get the tracning function used by a transport.
160
*
161
* @param[in] transport a transport object
162
* @return the tracing function used by a transport
163
*/
164
PN_EXTERN
pn_tracer_t
pn_transport_get_tracer
(
pn_transport_t
*transport);
165
166
/**
167
* Get the application context that is associated with a transport object.
168
*
169
* The application context for a transport may be set using
170
* ::pn_transport_set_context.
171
*
172
* @param[in] transport the transport whose context is to be returned.
173
* @return the application context for the transport object
174
*/
175
PN_EXTERN
void
*
pn_transport_get_context
(
pn_transport_t
*transport);
176
177
/**
178
* Set a new application context for a transport object.
179
*
180
* The application context for a transport object may be retrieved using
181
* ::pn_transport_get_context.
182
*
183
* @param[in] transport the transport object
184
* @param[in] context the application context
185
*/
186
PN_EXTERN
void
pn_transport_set_context
(
pn_transport_t
*transport,
void
*context);
187
188
/**
189
* Log a message using a transport's logging mechanism.
190
*
191
* This can be useful in a debugging context as the log message will
192
* be prefixed with the transport's identifier.
193
*
194
* @param[in] transport a transport object
195
* @param[in] message the message to be logged
196
*/
197
PN_EXTERN
void
pn_transport_log
(
pn_transport_t
*transport,
const
char
*message);
198
199
/**
200
* Log a printf formatted message using a transport's logging
201
* mechanism.
202
*
203
* This can be useful in a debugging context as the log message will
204
* be prefixed with the transport's identifier.
205
*
206
* @param[in] transport a transport object
207
* @param[in] fmt the printf formatted message to be logged
208
*/
209
PN_EXTERN
void
pn_transport_logf
(
pn_transport_t
*transport,
const
char
*fmt, ...);
210
211
/**
212
* Get the maximum allowed channel for a transport.
213
*
214
* @param[in] transport a transport object
215
* @return the maximum allowed channel
216
*/
217
PN_EXTERN
uint16_t
pn_transport_get_channel_max
(
pn_transport_t
*transport);
218
219
/**
220
* Set the maximum allowed channel for a transport.
221
*
222
* @param[in] transport a transport object
223
* @param[in] channel_max the maximum allowed channel
224
*/
225
PN_EXTERN
void
pn_transport_set_channel_max
(
pn_transport_t
*transport, uint16_t channel_max);
226
227
/**
228
* Get the maximum allowed channel of a transport's remote peer.
229
*
230
* @param[in] transport a transport object
231
* @return the maximum allowed channel of the transport's remote peer
232
*/
233
PN_EXTERN
uint16_t
pn_transport_remote_channel_max
(
pn_transport_t
*transport);
234
235
/**
236
* Get the maximum frame size of a transport.
237
*
238
* @param[in] transport a transport object
239
* @return the maximum frame size of the transport object
240
*/
241
PN_EXTERN
uint32_t
pn_transport_get_max_frame
(
pn_transport_t
*transport);
242
243
/**
244
* Set the maximum frame size of a transport.
245
*
246
* @param[in] transport a transport object
247
* @param[in] size the maximum frame size for the transport object
248
*/
249
PN_EXTERN
void
pn_transport_set_max_frame
(
pn_transport_t
*transport, uint32_t size);
250
251
/**
252
* Get the maximum frame size of a transport's remote peer.
253
*
254
* @param[in] transport a transport object
255
* @return the maximum frame size of the transport's remote peer
256
*/
257
PN_EXTERN
uint32_t
pn_transport_get_remote_max_frame
(
pn_transport_t
*transport);
258
259
/**
260
* Get the idle timeout for a transport.
261
*
262
* A zero idle timeout means heartbeats are disabled.
263
*
264
* @param[in] transport a transport object
265
* @return the transport's idle timeout
266
*/
267
PN_EXTERN
pn_millis_t
pn_transport_get_idle_timeout
(
pn_transport_t
*transport);
268
269
/**
270
* Set the idle timeout for a transport.
271
*
272
* A zero idle timeout means heartbeats are disabled.
273
*
274
* @param[in] transport a transport object
275
* @param[in] timeout the idle timeout for the transport object
276
*/
277
PN_EXTERN
void
pn_transport_set_idle_timeout
(
pn_transport_t
*transport,
pn_millis_t
timeout);
278
279
/**
280
* Get the idle timeout for a transport's remote peer.
281
*
282
* A zero idle timeout means heartbeats are disabled.
283
*
284
* @param[in] transport a transport object
285
* @return the idle timeout for the transport's remote peer
286
*/
287
PN_EXTERN
pn_millis_t
pn_transport_get_remote_idle_timeout
(
pn_transport_t
*transport);
288
289
/**
290
* @deprecated
291
*/
292
PN_EXTERN
ssize_t
pn_transport_input
(
pn_transport_t
*transport,
const
char
*bytes,
size_t
available);
293
/**
294
* @deprecated
295
*/
296
PN_EXTERN
ssize_t
pn_transport_output
(
pn_transport_t
*transport,
char
*bytes,
size_t
size);
297
298
/**
299
* Get the amount of free space for input following the transport's
300
* tail pointer.
301
*
302
* If the engine is in an exceptional state such as encountering an
303
* error condition or reaching the end of stream state, a negative
304
* value will be returned indicating the condition. If an error is
305
* indicated, futher details can be obtained from
306
* ::pn_transport_error. Calls to ::pn_transport_process may alter the
307
* value of this pointer. See ::pn_transport_process for details.
308
*
309
* @param[in] transport the transport
310
* @return the free space in the transport, PN_EOS or error code if < 0
311
*/
312
PN_EXTERN
ssize_t
pn_transport_capacity
(
pn_transport_t
*transport);
313
314
/**
315
* Get the transport's tail pointer.
316
*
317
* The amount of free space following this pointer is reported by
318
* ::pn_transport_capacity. Calls to ::pn_transport_process may alther
319
* the value of this pointer. See ::pn_transport_process for details.
320
*
321
* @param[in] transport the transport
322
* @return a pointer to the transport's input buffer, NULL if no capacity available.
323
*/
324
PN_EXTERN
char
*
pn_transport_tail
(
pn_transport_t
*transport);
325
326
/**
327
* Pushes the supplied bytes into the tail of the transport.
328
*
329
* This is equivalent to copying @c size bytes afther the tail pointer
330
* and then calling ::pn_transport_process with an argument of @c
331
* size. It is an error to call this with a @c size larger than the
332
* capacity reported by ::pn_transport_capacity.
333
*
334
* @param[in] transport the transport
335
* @param[in] src the start of the data to push into the transport
336
* @param[in] size the amount of data to push into the transport
337
*
338
* @return 0 on success, or error code if < 0
339
*/
340
PN_EXTERN
int
pn_transport_push
(
pn_transport_t
*transport,
const
char
*src,
size_t
size);
341
342
/**
343
* Process input data following the tail pointer.
344
*
345
* Calling this function will cause the transport to consume @c size
346
* bytes of input occupying the free space following the tail pointer.
347
* Calls to this function may change the value of ::pn_transport_tail,
348
* as well as the amount of free space reported by
349
* ::pn_transport_capacity.
350
*
351
* @param[in] transport the transport
352
* @param[in] size the amount of data written to the transport's input buffer
353
* @return 0 on success, or error code if < 0
354
*/
355
PN_EXTERN
int
pn_transport_process
(
pn_transport_t
*transport,
size_t
size);
356
357
/**
358
* Indicate that the input has reached End Of Stream (EOS).
359
*
360
* This tells the transport that no more input will be forthcoming.
361
*
362
* @param[in] transport the transport
363
* @return 0 on success, or error code if < 0
364
*/
365
PN_EXTERN
int
pn_transport_close_tail
(
pn_transport_t
*transport);
366
367
/**
368
* Get the number of pending output bytes following the transport's
369
* head pointer.
370
*
371
* If the engine is in an exceptional state such as encountering an
372
* error condition or reaching the end of stream state, a negative
373
* value will be returned indicating the condition. If an error is
374
* indicated, further details can be obtained from
375
* ::pn_transport_error. Calls to ::pn_transport_pop may alter the
376
* value of this pointer. See ::pn_transport_pop for details.
377
*
378
* @param[in] transport the transport
379
* @return the number of pending output bytes, or an error code
380
*/
381
PN_EXTERN
ssize_t
pn_transport_pending
(
pn_transport_t
*transport);
382
383
/**
384
* Get the transport's head pointer.
385
*
386
* This pointer references queued output data. The
387
* ::pn_transport_pending function reports how many bytes of output
388
* data follow this pointer. Calls to ::pn_transport_pop may alter
389
* this pointer and any data it references. See ::pn_transport_pop for
390
* details.
391
*
392
* @param[in] transport the transport
393
* @return a pointer to the transport's output buffer, or NULL if no pending output.
394
*/
395
PN_EXTERN
const
char
*
pn_transport_head
(
pn_transport_t
*transport);
396
397
/**
398
* Copies @c size bytes from the head of the transport to the @c dst
399
* pointer.
400
*
401
* It is an error to call this with a value of @c size that is greater
402
* than the value reported by ::pn_transport_pending.
403
*
404
* @param[in] transport the transport
405
* @param[out] dst the destination buffer
406
* @param[in] size the capacity of the destination buffer
407
* @return 0 on success, or error code if < 0
408
*/
409
PN_EXTERN
int
pn_transport_peek
(
pn_transport_t
*transport,
char
*dst,
size_t
size);
410
411
/**
412
* Removes @c size bytes of output from the pending output queue
413
* following the transport's head pointer.
414
*
415
* Calls to this function may alter the transport's head pointer as
416
* well as the number of pending bytes reported by
417
* ::pn_transport_pending.
418
*
419
* @param[in] transport the transport
420
* @param[in] size the number of bytes to remove
421
*/
422
PN_EXTERN
void
pn_transport_pop
(
pn_transport_t
*transport,
size_t
size);
423
424
/**
425
* Indicate that the output has closed.
426
*
427
* This tells the transport that no more output will be popped.
428
*
429
* @param[in] transport the transport
430
* @return 0 on success, or error code if < 0
431
*/
432
PN_EXTERN
int
pn_transport_close_head
(
pn_transport_t
*transport);
433
434
/**
435
* Check if a transport has buffered data.
436
*
437
* @param[in] transport a transport object
438
* @return true if the transport has buffered data, false otherwise
439
*/
440
PN_EXTERN
bool
pn_transport_quiesced
(
pn_transport_t
*transport);
441
442
/**
443
* Check if a transport is closed.
444
*
445
* A transport is defined to be closed when both the tail and the head
446
* are closed. In other words, when both ::pn_transport_capacity() < 0
447
* and ::pn_transport_pending() < 0.
448
*
449
* @param[in] transport a transport object
450
* @return true if the transport is closed, false otherwise
451
*/
452
PN_EXTERN
bool
pn_transport_closed
(
pn_transport_t
*transport);
453
454
/**
455
* Process any pending transport timer events.
456
*
457
* This method should be called after all pending input has been
458
* processed by the transport (see ::pn_transport_input), and before
459
* generating output (see ::pn_transport_output). It returns the
460
* deadline for the next pending timer event, if any are present.
461
*
462
* @param[in] transport the transport to process.
463
* @param[in] now the current time
464
*
465
* @return if non-zero, then the expiration time of the next pending timer event for the
466
* transport. The caller must invoke pn_transport_tick again at least once at or before
467
* this deadline occurs.
468
*/
469
PN_EXTERN
pn_timestamp_t
pn_transport_tick
(
pn_transport_t
*transport,
pn_timestamp_t
now);
470
471
/**
472
* Get the number of frames output by a transport.
473
*
474
* @param[in] transport a transport object
475
* @return the number of frames output by the transport
476
*/
477
PN_EXTERN
uint64_t
pn_transport_get_frames_output
(
const
pn_transport_t
*transport);
478
479
/**
480
* Get the number of frames input by a transport.
481
*
482
* @param[in] transport a transport object
483
* @return the number of frames input by the transport
484
*/
485
PN_EXTERN
uint64_t
pn_transport_get_frames_input
(
const
pn_transport_t
*transport);
486
487
#ifdef __cplusplus
488
}
489
#endif
490
491
/** @}
492
*/
493
494
#endif
/* transport.h */
Generated on Mon Jun 2 2014 22:59:05 for proton by
1.8.1.2