proton  0
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Pages
engine.h
Go to the documentation of this file.
1 #ifndef PROTON_ENGINE_H
2 #define PROTON_ENGINE_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 #ifndef __cplusplus
27 #include <stdbool.h>
28 #endif
29 #include <stddef.h>
30 #include <sys/types.h>
31 #include <proton/codec.h>
32 #include <proton/error.h>
33 
34 #ifdef __cplusplus
35 extern "C" {
36 #endif
37 
38 /** @file
39  * API for the proton Engine.
40  *
41  * @todo
42  */
43 
45 typedef struct pn_connection_t pn_connection_t; /**< Connection */
46 typedef struct pn_session_t pn_session_t; /**< Session */
47 typedef struct pn_link_t pn_link_t; /**< Link */
50 
51 typedef enum {
53  PN_SOURCE = 1,
54  PN_TARGET = 2,
57 typedef enum {
62 typedef enum {
68 typedef enum {
73 typedef enum {
78 typedef enum {
79  PN_RCV_FIRST = 0, /**< implicitly settle rcvd xfers */
80  PN_RCV_SECOND = 1 /**< explicit disposition required */
82 
85 
86 typedef struct pn_delivery_tag_t {
87  size_t size;
88  const char *bytes;
90 
91 #ifndef SWIG // older versions of SWIG choke on this:
92 static inline pn_delivery_tag_t pn_dtag(const char *bytes, size_t size) {
93  pn_delivery_tag_t dtag = {size, bytes};
94  return dtag;
95 }
96 #endif
97 
98 typedef int pn_state_t; /**< encodes the state of an endpoint */
99 
100 #define PN_LOCAL_UNINIT (1) /**< local endpoint requires initialization */
101 #define PN_LOCAL_ACTIVE (2) /**< local endpoint is active */
102 #define PN_LOCAL_CLOSED (4) /**< local endpoint is closed */
103 #define PN_REMOTE_UNINIT (8) /**< remote endpoint pending initialization by peer */
104 #define PN_REMOTE_ACTIVE (16) /**< remote endpoint is active */
105 #define PN_REMOTE_CLOSED (32) /**< remote endpoint has closed */
106 
107 #define PN_LOCAL_MASK (PN_LOCAL_UNINIT | PN_LOCAL_ACTIVE | PN_LOCAL_CLOSED)
108 #define PN_REMOTE_MASK (PN_REMOTE_UNINIT | PN_REMOTE_ACTIVE | PN_REMOTE_CLOSED)
109 
110 /**
111  * The state/outcome of a message transfer.
112  *
113  * @todo document each value
114  */
115 
116 #define PN_RECEIVED (0x0000000000000023)
117 #define PN_ACCEPTED (0x0000000000000024)
118 #define PN_REJECTED (0x0000000000000025)
119 #define PN_RELEASED (0x0000000000000026)
120 #define PN_MODIFIED (0x0000000000000027)
121 
122 typedef int pn_trace_t;
123 
124 #define PN_TRACE_OFF (0)
125 #define PN_TRACE_RAW (1)
126 #define PN_TRACE_FRM (2)
127 #define PN_TRACE_DRV (4)
128 
129 // connection
130 
131 /** Factory to construct a new Connection.
132  *
133  * @return pointer to a new connection object.
134  */
136 
137 /** Retrieve the state of the connection.
138  *
139  * @param[in] connection the connection
140  * @return the connection's state flags
141  */
142 PN_EXTERN pn_state_t pn_connection_state(pn_connection_t *connection);
143 /** @todo: needs documentation */
145 /** @todo: needs documentation */
146 PN_EXTERN const char *pn_connection_get_container(pn_connection_t *connection);
147 /** @todo: needs documentation */
148 PN_EXTERN void pn_connection_set_container(pn_connection_t *connection, const char *container);
149 /** @todo: needs documentation */
150 PN_EXTERN const char *pn_connection_get_hostname(pn_connection_t *connection);
151 /** @todo: needs documentation */
152 PN_EXTERN void pn_connection_set_hostname(pn_connection_t *connection, const char *hostname);
161 
162 
163 /** Extracts the first delivery on the connection that has pending
164  * operations.
165  *
166  * Retrieves the first delivery on the Connection that has pending
167  * operations. A readable delivery indicates message data is waiting
168  * to be read. A writable delivery indicates that message data may be
169  * sent. An updated delivery indicates that the delivery's disposition
170  * has changed. A delivery will never be both readable and writible,
171  * but it may be both readable and updated or both writiable and
172  * updated.
173  *
174  * @param[in] connection the connection
175  * @return the first delivery object that needs to be serviced, else
176  * NULL if none
177  */
179 
180 /** Get the next delivery on the connection that needs has pending
181  * operations.
182  *
183  * @param[in] delivery the previous delivery retrieved from
184  * either pn_work_head() or pn_work_next()
185  * @return the next delivery that has pending operations, else
186  * NULL if none
187  */
189 
190 /** Factory for creating a new session on the connection.
191  *
192  * A new session is created for the connection, and is added to the
193  * set of sessions maintained by the connection.
194  *
195  * @param[in] connection the session will exist over this connection
196  * @return pointer to new session
197  */
199 
201 PN_EXTERN void pn_session_set_incoming_capacity(pn_session_t *ssn, size_t capacity);
202 
205 
206 /** Factory for creating a transport.
207  *
208  * A transport to be used by a connection to interface with the
209  * network. There can only be one connection associated with a
210  * transport. See pn_transport_bind().
211  *
212  * @return pointer to new transport
213  */
215 
216 /** Binds the transport to an AMQP connection endpoint.
217  *
218  * @return an error code, or 0 on success
219  */
220 
221 PN_EXTERN int pn_transport_bind(pn_transport_t *transport, pn_connection_t *connection);
222 
224 
225 /** Retrieve the first Session that matches the given state mask.
226  *
227  * Examines the state of each session owned by the connection, and
228  * returns the first Session that matches the given state mask. If
229  * state contains both local and remote flags, then an exact match
230  * against those flags is performed. If state contains only local or
231  * only remote flags, then a match occurs if any of the local or
232  * remote flags are set respectively.
233  *
234  * @param[in] connection to be searched for matching sessions
235  * @param[in] state mask to match
236  * @return the first session owned by the connection that matches the
237  * mask, else NULL if no sessions match
238  */
239 PN_EXTERN pn_session_t *pn_session_head(pn_connection_t *connection, pn_state_t state);
240 
241 /** Retrieve the next Session that matches the given state mask.
242  *
243  * When used with pn_session_head(), application can access all
244  * Sessions on the connection that match the given state. See
245  * pn_session_head() for description of match behavior.
246  *
247  * @param[in] session the previous session obtained from
248  * pn_session_head() or pn_session_next()
249  * @param[in] state mask to match.
250  * @return the next session owned by the connection that matches the
251  * mask, else NULL if no sessions match
252  */
253 PN_EXTERN pn_session_t *pn_session_next(pn_session_t *session, pn_state_t state);
254 
255 /** Retrieve the first Link that matches the given state mask.
256  *
257  * Examines the state of each Link owned by the connection and returns
258  * the first Link that matches the given state mask. If state contains
259  * both local and remote flags, then an exact match against those
260  * flags is performed. If state contains only local or only remote
261  * flags, then a match occurs if any of the local or remote flags are
262  * set respectively.
263  *
264  * @param[in] connection to be searched for matching Links
265  * @param[in] state mask to match
266  * @return the first Link owned by the connection that matches the
267  * mask, else NULL if no Links match
268  */
269 PN_EXTERN pn_link_t *pn_link_head(pn_connection_t *connection, pn_state_t state);
270 
271 /** Retrieve the next Link that matches the given state mask.
272  *
273  * When used with pn_link_head(), the application can access all Links
274  * on the connection that match the given state. See pn_link_head()
275  * for description of match behavior.
276  *
277  * @param[in] link the previous Link obtained from pn_link_head() or
278  * pn_link_next()
279  * @param[in] state mask to match
280  * @return the next session owned by the connection that matches the
281  * mask, else NULL if no sessions match
282  */
283 PN_EXTERN pn_link_t *pn_link_next(pn_link_t *link, pn_state_t state);
284 
289 
290 /** Access the application context that is associated with the
291  * connection.
292  *
293  * @param[in] connection the connection whose context is to be returned.
294  *
295  * @return the application context that was passed to pn_connection_set_context()
296  */
298 
299 /** Assign a new application context to the connection.
300  *
301  * @param[in] connection the connection which will hold the context.
302  * @param[in] context new application context to associate with the
303  * connection
304  */
305 PN_EXTERN void pn_connection_set_context(pn_connection_t *connection, void *context);
306 
307 
308 // transport
310 /* deprecated */
311 PN_EXTERN ssize_t pn_transport_input(pn_transport_t *transport, const char *bytes, size_t available);
312 /* deprecated */
313 PN_EXTERN ssize_t pn_transport_output(pn_transport_t *transport, char *bytes, size_t size);
314 
315 /** Report the amount of free space for input following the
316  * transport's tail pointer. If the engine is in an exceptional state
317  * such as encountering an error condition or reaching the end of
318  * stream state, a negative value will be returned indicating the
319  * condition. If an error is indicated, futher details can be obtained
320  * from ::pn_transport_error. Calls to ::pn_transport_process may
321  * alter the value of this pointer. See ::pn_transport_process for
322  * details.
323  *
324  * @param[in] transport the transport
325  * @return the free space in the transport, PN_EOS or error code if < 0
326  */
328 
329 /** Return the transport's tail pointer. The amount of free space
330  * following this pointer is reported by ::pn_transport_capacity.
331  * Calls to ::pn_transport_process may alther the value of this
332  * pointer. See ::pn_transport_process for details.
333  *
334  * @param[in] transport the transport
335  * @return a pointer to the transport's input buffer, NULL if no capacity available.
336  */
337 PN_EXTERN char *pn_transport_tail(pn_transport_t *transport);
338 
339 /** Pushes the supplied bytes into the tail of the transport. This is
340  * equivalent to copying ::size bytes afther the tail pointer and then
341  * calling ::pn_transport_process with an argument of ::size. It is an
342  * error to call this with a size larger than the capacity reported by
343  * ::pn_transport_capacity.
344  *
345  * @param[in] transport the transport
346  * @return 0 on success, or error code if < 0
347  */
348 PN_EXTERN int pn_transport_push(pn_transport_t *transport, const char *src, size_t size);
349 
350 /** Process input data following the tail pointer. Calling this
351  * function will cause the transport to consume ::size bytes of input
352  * occupying the free space following the tail pointer. Calls to this
353  * function may change the value of ::pn_transport_tail, as well as
354  * the amount of free space reported by ::pn_transport_capacity.
355  *
356  * @param[in] transport the transport
357  * @param[size] the amount of data written to the transport's input buffer
358  * @return 0 on success, or error code if < 0
359  */
360 PN_EXTERN int pn_transport_process(pn_transport_t *transport, size_t size);
361 
362 /** Indicate that the input has reached End Of Stream (EOS). This
363  * tells the transport that no more input will be forthcoming.
364  *
365  * @param[in] transport the transport
366  * @return 0 on success, or error code if < 0
367  */
369 
370 /** Report the number of pending output bytes following the
371  * transport's head pointer. If the engine is in an exceptional state
372  * such as encountering an error condition or reaching the end of
373  * stream state, a negative value will be returned indicating the
374  * condition. If an error is indicated, further details can be
375  * obtained from ::pn_transport_error. Calls to ::pn_transport_pop may
376  * alter the value of this pointer. See ::pn_transport_pop for
377  * details.
378  *
379  * @param[in] the transport
380  * @return the number of pending output bytes, or an error code
381  */
382 PN_EXTERN ssize_t pn_transport_pending(pn_transport_t *transport);
383 
384 /** Return the transport's head pointer. This pointer references
385  * queued output data. The ::pn_transport_pending function reports how
386  * many bytes of output data follow this pointer. Calls to
387  * ::pn_transport_pop may alter this pointer and any data it
388  * references. See ::pn_transport_pop for details.
389  *
390  * @param[in] transport the transport
391  * @return a pointer to the transport's output buffer, or NULL if no pending output.
392  */
393 PN_EXTERN const char *pn_transport_head(pn_transport_t *transport);
394 
395 /** Copies ::size bytes from the head of the transport to the ::dst
396  * pointer. It is an error to call this with a value of ::size that is
397  * greater than the value reported by ::pn_transport_pending.
398  *
399  * @param[in] transport the transport
400  * @return 0 on success, or error code if < 0
401  */
402 PN_EXTERN int pn_transport_peek(pn_transport_t *transport, char *dst, size_t size);
403 
404 /** Removes ::size bytes of output from the pending output queue
405  * following the transport's head pointer. Calls to this function may
406  * alter the transport's head pointer as well as the number of pending
407  * bytes reported by ::pn_transport_pending.
408  *
409  * @param[in] the transport
410  * @param[size] the number of bytes to remove
411  */
412 PN_EXTERN void pn_transport_pop(pn_transport_t *transport, size_t size);
413 
414 /** Indicate that the output has closed. This tells the transport
415  * that no more output will be popped.
416  *
417  * @param[in] transport the transport
418  * @return 0 on success, or error code if < 0
419  */
421 
422 
423 /** Process any pending transport timer events.
424  *
425  * This method should be called after all pending input has been processed by the
426  * transport (see ::pn_transport_input), and before generating output (see
427  * ::pn_transport_output). It returns the deadline for the next pending timer event, if
428  * any are present.
429  *
430  * @param[in] transport the transport to process.
431  *
432  * @return if non-zero, then the expiration time of the next pending timer event for the
433  * transport. The caller must invoke pn_transport_tick again at least once at or before
434  * this deadline occurs.
435  */
437 PN_EXTERN void pn_transport_trace(pn_transport_t *transport, pn_trace_t trace);
438 // max frame of zero means "unlimited"
440 PN_EXTERN void pn_transport_set_max_frame(pn_transport_t *transport, uint32_t size);
442 /* timeout of zero means "no timeout" */
446 PN_EXTERN uint64_t pn_transport_get_frames_output(const pn_transport_t *transport);
447 PN_EXTERN uint64_t pn_transport_get_frames_input(const pn_transport_t *transport);
450 
451 // session
452 PN_EXTERN pn_state_t pn_session_state(pn_session_t *session);
455 PN_EXTERN void pn_session_open(pn_session_t *session);
457 PN_EXTERN void pn_session_free(pn_session_t *session);
459 PN_EXTERN void pn_session_set_context(pn_session_t *session, void *context);
460 
461 // link
462 PN_EXTERN pn_link_t *pn_sender(pn_session_t *session, const char *name);
463 PN_EXTERN pn_link_t *pn_receiver(pn_session_t *session, const char *name);
464 PN_EXTERN const char *pn_link_name(pn_link_t *link);
467 PN_EXTERN pn_state_t pn_link_state(pn_link_t *link);
485 
489 
490 PN_EXTERN void pn_link_open(pn_link_t *sender);
491 PN_EXTERN void pn_link_close(pn_link_t *sender);
492 PN_EXTERN void pn_link_free(pn_link_t *sender);
494 PN_EXTERN void pn_link_set_context(pn_link_t *link, void *context);
495 
496 // sender
497 PN_EXTERN void pn_link_offered(pn_link_t *sender, int credit);
498 PN_EXTERN ssize_t pn_link_send(pn_link_t *sender, const char *bytes, size_t n);
499 PN_EXTERN void pn_link_drained(pn_link_t *sender);
500 //void pn_link_abort(pn_sender_t *sender);
501 
502 // receiver
503 PN_EXTERN void pn_link_flow(pn_link_t *receiver, int credit);
504 PN_EXTERN void pn_link_drain(pn_link_t *receiver, int credit);
505 PN_EXTERN ssize_t pn_link_recv(pn_link_t *receiver, char *bytes, size_t n);
506 
507 // terminus
510 
511 PN_EXTERN const char *pn_terminus_get_address(pn_terminus_t *terminus);
512 PN_EXTERN int pn_terminus_set_address(pn_terminus_t *terminus, const char *address);
515  pn_durability_t durability);
521 PN_EXTERN int pn_terminus_set_dynamic(pn_terminus_t *terminus, bool dynamic);
529 
530 // delivery
534 // how do we do delivery state?
545 PN_EXTERN void pn_delivery_update(pn_delivery_t *delivery, uint64_t state);
547 //int pn_delivery_format(pn_delivery_t *delivery);
551 PN_EXTERN void pn_delivery_set_context(pn_delivery_t *delivery, void *context);
552 
553 // disposition
554 PN_EXTERN uint64_t pn_disposition_type(pn_disposition_t *disposition);
557 PN_EXTERN void pn_disposition_set_section_number(pn_disposition_t *disposition, uint32_t section_number);
559 PN_EXTERN void pn_disposition_set_section_offset(pn_disposition_t *disposition, uint64_t section_offset);
561 PN_EXTERN void pn_disposition_set_failed(pn_disposition_t *disposition, bool failed);
563 PN_EXTERN void pn_disposition_set_undeliverable(pn_disposition_t *disposition, bool undeliverable);
565 
566 // conditions
569 
572 
575 
577 
580 
581 PN_EXTERN const char *pn_condition_get_name(pn_condition_t *condition);
582 PN_EXTERN int pn_condition_set_name(pn_condition_t *condition, const char *name);
583 
585 PN_EXTERN int pn_condition_set_description(pn_condition_t *condition, const char *description);
586 
588 
590 PN_EXTERN const char *pn_condition_redirect_host(pn_condition_t *condition);
592 
593 #ifdef __cplusplus
594 }
595 #endif
596 
597 #endif /* engine.h */