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