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 {
69 
70 typedef struct pn_delivery_tag_t {
71  size_t size;
72  const char *bytes;
74 
75 #ifndef SWIG // older versions of SWIG choke on this:
76 static inline pn_delivery_tag_t pn_dtag(const char *bytes, size_t size) {
77  pn_delivery_tag_t dtag = {size, bytes};
78  return dtag;
79 }
80 #endif
81 
82 typedef int pn_state_t; /**< encodes the state of an endpoint */
83 
84 #define PN_LOCAL_UNINIT (1) /**< local endpoint requires initialization */
85 #define PN_LOCAL_ACTIVE (2) /**< local endpoint is active */
86 #define PN_LOCAL_CLOSED (4) /**< local endpoint is closed */
87 #define PN_REMOTE_UNINIT (8) /**< remote endpoint pending initialization by peer */
88 #define PN_REMOTE_ACTIVE (16) /**< remote endpoint is active */
89 #define PN_REMOTE_CLOSED (32) /**< remote endpoint has closed */
90 
91 #define PN_LOCAL_MASK (PN_LOCAL_UNINIT | PN_LOCAL_ACTIVE | PN_LOCAL_CLOSED)
92 #define PN_REMOTE_MASK (PN_REMOTE_UNINIT | PN_REMOTE_ACTIVE | PN_REMOTE_CLOSED)
93 
94 /** @enum pn_disposition_t
95  * The state/outcome of a message transfer.
96  *
97  * @todo document each value
98  */
99 typedef enum pn_disposition_t {
106 
107 typedef int pn_trace_t;
108 
109 #define PN_TRACE_OFF (0)
110 #define PN_TRACE_RAW (1)
111 #define PN_TRACE_FRM (2)
112 #define PN_TRACE_DRV (4)
113 
114 #define PN_SESSION_WINDOW (1024)
115 
116 // connection
117 
118 /** Factory to construct a new Connection.
119  *
120  * @return pointer to a new connection object.
121  */
123 
124 /** Retrieve the state of the connection.
125  *
126  * @param[in] connection the connection
127  * @return the connection's state flags
128  */
129 PN_EXTERN pn_state_t pn_connection_state(pn_connection_t *connection);
130 /** @todo: needs documentation */
132 /** @todo: needs documentation */
133 PN_EXTERN const char *pn_connection_get_container(pn_connection_t *connection);
134 /** @todo: needs documentation */
135 PN_EXTERN void pn_connection_set_container(pn_connection_t *connection, const char *container);
136 /** @todo: needs documentation */
137 PN_EXTERN const char *pn_connection_get_hostname(pn_connection_t *connection);
138 /** @todo: needs documentation */
139 PN_EXTERN void pn_connection_set_hostname(pn_connection_t *connection, const char *hostname);
146 
147 
148 /** Extracts the first delivery on the connection that has pending
149  * operations.
150  *
151  * Retrieves the first delivery on the Connection that has pending
152  * operations. A readable delivery indicates message data is waiting
153  * to be read. A writable delivery indicates that message data may be
154  * sent. An updated delivery indicates that the delivery's disposition
155  * has changed. A delivery will never be both readable and writible,
156  * but it may be both readable and updated or both writiable and
157  * updated.
158  *
159  * @param[in] connection the connection
160  * @return the first delivery object that needs to be serviced, else
161  * NULL if none
162  */
164 
165 /** Get the next delivery on the connection that needs has pending
166  * operations.
167  *
168  * @param[in] delivery the previous delivery retrieved from
169  * either pn_work_head() or pn_work_next()
170  * @return the next delivery that has pending operations, else
171  * NULL if none
172  */
174 
175 /** Factory for creating a new session on the connection.
176  *
177  * A new session is created for the connection, and is added to the
178  * set of sessions maintained by the connection.
179  *
180  * @param[in] connection the session will exist over this connection
181  * @return pointer to new session
182  */
184 
185 /** Factory for creating a transport.
186  *
187  * A transport to be used by a connection to interface with the
188  * network. There can only be one connection associated with a
189  * transport. See pn_transport_bind().
190  *
191  * @return pointer to new transport
192  */
194 
195 /** Binds the transport to an AMQP connection endpoint.
196  *
197  * @return an error code, or 0 on success
198  */
199 
200 PN_EXTERN int pn_transport_bind(pn_transport_t *transport, pn_connection_t *connection);
201 
203 
204 /** Retrieve the first Session that matches the given state mask.
205  *
206  * Examines the state of each session owned by the connection, and
207  * returns the first Session that matches the given state mask. If
208  * state contains both local and remote flags, then an exact match
209  * against those flags is performed. If state contains only local or
210  * only remote flags, then a match occurs if any of the local or
211  * remote flags are set respectively.
212  *
213  * @param[in] connection to be searched for matching sessions
214  * @param[in] state mask to match
215  * @return the first session owned by the connection that matches the
216  * mask, else NULL if no sessions match
217  */
218 PN_EXTERN pn_session_t *pn_session_head(pn_connection_t *connection, pn_state_t state);
219 
220 /** Retrieve the next Session that matches the given state mask.
221  *
222  * When used with pn_session_head(), application can access all
223  * Sessions on the connection that match the given state. See
224  * pn_session_head() for description of match behavior.
225  *
226  * @param[in] session the previous session obtained from
227  * pn_session_head() or pn_session_next()
228  * @param[in] state mask to match.
229  * @return the next session owned by the connection that matches the
230  * mask, else NULL if no sessions match
231  */
232 PN_EXTERN pn_session_t *pn_session_next(pn_session_t *session, pn_state_t state);
233 
234 /** Retrieve the first Link that matches the given state mask.
235  *
236  * Examines the state of each Link owned by the connection and returns
237  * the first Link that matches the given state mask. If state contains
238  * both local and remote flags, then an exact match against those
239  * flags is performed. If state contains only local or only remote
240  * flags, then a match occurs if any of the local or remote flags are
241  * set respectively.
242  *
243  * @param[in] connection to be searched for matching Links
244  * @param[in] state mask to match
245  * @return the first Link owned by the connection that matches the
246  * mask, else NULL if no Links match
247  */
248 PN_EXTERN pn_link_t *pn_link_head(pn_connection_t *connection, pn_state_t state);
249 
250 /** Retrieve the next Link that matches the given state mask.
251  *
252  * When used with pn_link_head(), the application can access all Links
253  * on the connection that match the given state. See pn_link_head()
254  * for description of match behavior.
255  *
256  * @param[in] link the previous Link obtained from pn_link_head() or
257  * pn_link_next()
258  * @param[in] state mask to match
259  * @return the next session owned by the connection that matches the
260  * mask, else NULL if no sessions match
261  */
262 PN_EXTERN pn_link_t *pn_link_next(pn_link_t *link, pn_state_t state);
263 
268 
269 /** Access the application context that is associated with the
270  * connection.
271  *
272  * @param[in] connection the connection whose context is to be returned.
273  *
274  * @return the application context that was passed to pn_connection_set_context()
275  */
277 
278 /** Assign a new application context to the connection.
279  *
280  * @param[in] connection the connection which will hold the context.
281  * @param[in] context new application context to associate with the
282  * connection
283  */
284 PN_EXTERN void pn_connection_set_context(pn_connection_t *connection, void *context);
285 
286 
287 // transport
289 /* deprecated */
290 PN_EXTERN ssize_t pn_transport_input(pn_transport_t *transport, const char *bytes, size_t available);
291 /* deprecated */
292 PN_EXTERN ssize_t pn_transport_output(pn_transport_t *transport, char *bytes, size_t size);
293 
294 /** Report the amount of free space for input following the
295  * transport's tail pointer. If the engine is in an exceptional state
296  * such as encountering an error condition or reaching the end of
297  * stream state, a negative value will be returned indicating the
298  * condition. If an error is indicated, futher details can be obtained
299  * from ::pn_transport_error. Calls to ::pn_transport_push may alter
300  * the value of this pointer. See ::pn_transport_push for details.
301  *
302  * @param[in] transport the transport
303  * @return the free space in the transport, PN_EOS or error code if < 0
304  */
306 
307 /** Return the transport's tail pointer. The amount of free space
308  * following this pointer is reported by ::pn_transport_capacity.
309  * Calls to ::pn_transport_push may alther the value of this pointer.
310  * See ::pn_transport_push for details.
311  *
312  * @param[in] transport the transport
313  * @return a pointer to the transport's input buffer, NULL if no capacity available.
314  */
315 PN_EXTERN char *pn_transport_tail(pn_transport_t *transport);
316 
317 /** Push input data following the tail pointer into the transport.
318  * Calling this function will cause the transport to consume ::size
319  * bytes of input occupying the free space following the tail pointer.
320  * Calls to this function may change the value of ::pn_transport_tail,
321  * as well as the amount of free space reported by
322  * ::pn_transport_capacity.
323  *
324  * @param[in] transport the transport
325  * @param[size] the amount of data written to the transport's input buffer
326  * @return 0 on success, or error code if < 0
327  */
328 PN_EXTERN int pn_transport_push(pn_transport_t *transport, size_t size);
329 
330 /** Indicate that the input has reached End Of Stream (EOS). This
331  * tells the transport that no more input will be forthcoming.
332  *
333  * @param[in] transport the transport
334  * @return 0 on success, or error code if < 0
335  */
337 
338 /** Report the number of pending output bytes following the
339  * transport's head pointer. If the engine is in an exceptional state
340  * such as encountering an error condition or reaching the end of
341  * stream state, a negative value will be returned indicating the
342  * condition. If an error is indicated, further details can be
343  * obtained from ::pn_transport_error. Calls to ::pn_transport_pop may
344  * alter the value of this pointer. See ::pn_transport_pop for
345  * details.
346  *
347  * @param[in] the transport
348  * @return the number of pending output bytes, or an error code
349  */
350 PN_EXTERN ssize_t pn_transport_pending(pn_transport_t *transport);
351 
352 /** Return the transport's head pointer. This pointer references
353  * queued output data. The ::pn_transport_pending function reports how
354  * many bytes of output data follow this pointer. Calls to
355  * ::pn_transport_pop may alter this pointer and any data it
356  * references. See ::pn_transport_pop for details.
357  *
358  * @param[in] the transport
359  * @return a pointer to the transport's output buffer, or NULL if no pending output.
360  */
361 PN_EXTERN const char *pn_transport_head(pn_transport_t *transport);
362 
363 /** Removes ::size bytes of output from the pending output queue
364  * following the transport's head pointer. Calls to this function may
365  * alter the transport's head pointer as well as the number of pending
366  * bytes reported by ::pn_transport_pending.
367  *
368  * @param[in] the transport
369  * @param[size] the number of bytes to remove
370  */
371 PN_EXTERN void pn_transport_pop(pn_transport_t *transport, size_t size);
372 
373 /** Indicate that the output has closed. This tells the transport
374  * that no more output will be popped.
375  *
376  * @param[in] transport the transport
377  * @return 0 on success, or error code if < 0
378  */
380 
381 
382 /** Process any pending transport timer events.
383  *
384  * This method should be called after all pending input has been processed by the
385  * transport (see ::pn_transport_input), and before generating output (see
386  * ::pn_transport_output). It returns the deadline for the next pending timer event, if
387  * any are present.
388  *
389  * @param[in] transport the transport to process.
390  *
391  * @return if non-zero, then the expiration time of the next pending timer event for the
392  * transport. The caller must invoke pn_transport_tick again at least once at or before
393  * this deadline occurs.
394  */
396 PN_EXTERN void pn_transport_trace(pn_transport_t *transport, pn_trace_t trace);
397 // max frame of zero means "unlimited"
399 PN_EXTERN void pn_transport_set_max_frame(pn_transport_t *transport, uint32_t size);
401 /* timeout of zero means "no timeout" */
405 PN_EXTERN uint64_t pn_transport_get_frames_output(const pn_transport_t *transport);
406 PN_EXTERN uint64_t pn_transport_get_frames_input(const pn_transport_t *transport);
409 
410 // session
411 PN_EXTERN pn_state_t pn_session_state(pn_session_t *session);
414 PN_EXTERN void pn_session_open(pn_session_t *session);
416 PN_EXTERN void pn_session_free(pn_session_t *session);
418 PN_EXTERN void pn_session_set_context(pn_session_t *session, void *context);
419 
420 // link
421 PN_EXTERN pn_link_t *pn_sender(pn_session_t *session, const char *name);
422 PN_EXTERN pn_link_t *pn_receiver(pn_session_t *session, const char *name);
423 PN_EXTERN const char *pn_link_name(pn_link_t *link);
426 PN_EXTERN pn_state_t pn_link_state(pn_link_t *link);
438 
442 
443 PN_EXTERN void pn_link_open(pn_link_t *sender);
444 PN_EXTERN void pn_link_close(pn_link_t *sender);
445 PN_EXTERN void pn_link_free(pn_link_t *sender);
447 PN_EXTERN void pn_link_set_context(pn_link_t *link, void *context);
448 
449 // sender
450 PN_EXTERN void pn_link_offered(pn_link_t *sender, int credit);
451 PN_EXTERN ssize_t pn_link_send(pn_link_t *sender, const char *bytes, size_t n);
452 PN_EXTERN void pn_link_drained(pn_link_t *sender);
453 //void pn_link_abort(pn_sender_t *sender);
454 
455 // receiver
456 PN_EXTERN void pn_link_flow(pn_link_t *receiver, int credit);
457 PN_EXTERN void pn_link_drain(pn_link_t *receiver, int credit);
458 PN_EXTERN ssize_t pn_link_recv(pn_link_t *receiver, char *bytes, size_t n);
459 
460 // terminus
463 
464 PN_EXTERN const char *pn_terminus_get_address(pn_terminus_t *terminus);
465 PN_EXTERN int pn_terminus_set_address(pn_terminus_t *terminus, const char *address);
468  pn_durability_t durability);
474 PN_EXTERN int pn_terminus_set_dynamic(pn_terminus_t *terminus, bool dynamic);
480 
481 // delivery
485 // how do we do delivery state?
494 PN_EXTERN void pn_delivery_update(pn_delivery_t *delivery, pn_disposition_t disposition);
496 //int pn_delivery_format(pn_delivery_t *delivery);
500 PN_EXTERN void pn_delivery_set_context(pn_delivery_t *delivery, void *context);
501 
504 
507 
510 
513 
514 PN_EXTERN const char *pn_condition_get_name(pn_condition_t *condition);
515 PN_EXTERN int pn_condition_set_name(pn_condition_t *condition, const char *name);
516 
518 PN_EXTERN int pn_condition_set_description(pn_condition_t *condition, const char *description);
519 
521 
523 PN_EXTERN const char *pn_condition_redirect_host(pn_condition_t *condition);
525 
526 #ifdef __cplusplus
527 }
528 #endif
529 
530 #endif /* engine.h */