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 <stdbool.h>
26 #include <stddef.h>
27 #include <sys/types.h>
28 #include <proton/codec.h>
29 #include <proton/error.h>
30 
31 #ifdef __cplusplus
32 extern "C" {
33 #endif
34 
35 /** @file
36  * API for the proton Engine.
37  *
38  * @todo
39  */
40 
42 typedef struct pn_connection_t pn_connection_t; /**< Connection */
43 typedef struct pn_session_t pn_session_t; /**< Session */
44 typedef struct pn_link_t pn_link_t; /**< Link */
47 
48 typedef enum {
50  PN_SOURCE = 1,
51  PN_TARGET = 2,
54 typedef enum {
59 typedef enum {
66 
67 typedef struct pn_delivery_tag_t {
68  size_t size;
69  const char *bytes;
71 
72 #define pn_dtag(BYTES, SIZE) ((pn_delivery_tag_t) {(SIZE), (BYTES)})
73 
74 typedef int pn_state_t; /**< encodes the state of an endpoint */
75 
76 #define PN_LOCAL_UNINIT (1) /**< local endpoint requires initialization */
77 #define PN_LOCAL_ACTIVE (2) /**< local endpoint is active */
78 #define PN_LOCAL_CLOSED (4) /**< local endpoint is closed */
79 #define PN_REMOTE_UNINIT (8) /**< remote endpoint pending initialization by peer */
80 #define PN_REMOTE_ACTIVE (16) /**< remote endpoint is active */
81 #define PN_REMOTE_CLOSED (32) /**< remote endpoint has closed */
82 
83 #define PN_LOCAL_MASK (PN_LOCAL_UNINIT | PN_LOCAL_ACTIVE | PN_LOCAL_CLOSED)
84 #define PN_REMOTE_MASK (PN_REMOTE_UNINIT | PN_REMOTE_ACTIVE | PN_REMOTE_CLOSED)
85 
86 /** @enum pn_disposition_t
87  * The state/outcome of a message transfer.
88  *
89  * @todo document each value
90  */
91 typedef enum pn_disposition_t {
98 
99 typedef int pn_trace_t;
100 
101 #define PN_TRACE_OFF (0)
102 #define PN_TRACE_RAW (1)
103 #define PN_TRACE_FRM (2)
104 #define PN_TRACE_DRV (4)
105 
106 #define PN_SESSION_WINDOW (1024)
107 
108 // connection
109 
110 /** Factory to construct a new Connection.
111  *
112  * @return pointer to a new connection object.
113  */
115 
116 /** Retrieve the state of the connection.
117  *
118  * @param[in] connection the connection
119  * @return the connection's state flags
120  */
121 pn_state_t pn_connection_state(pn_connection_t *connection);
122 /** @todo: needs documentation */
124 /** @todo: needs documentation */
125 const char *pn_connection_get_container(pn_connection_t *connection);
126 /** @todo: needs documentation */
127 void pn_connection_set_container(pn_connection_t *connection, const char *container);
128 /** @todo: needs documentation */
129 const char *pn_connection_get_hostname(pn_connection_t *connection);
130 /** @todo: needs documentation */
131 void pn_connection_set_hostname(pn_connection_t *connection, const char *hostname);
132 const char *pn_connection_remote_container(pn_connection_t *connection);
133 const char *pn_connection_remote_hostname(pn_connection_t *connection);
138 
139 
140 /** Extracts the first delivery on the connection that has pending
141  * operations.
142  *
143  * Retrieves the first delivery on the Connection that has pending
144  * operations. A readable delivery indicates message data is waiting
145  * to be read. A writable delivery indicates that message data may be
146  * sent. An updated delivery indicates that the delivery's disposition
147  * has changed. A delivery will never be both readable and writible,
148  * but it may be both readable and updated or both writiable and
149  * updated.
150  *
151  * @param[in] connection the connection
152  * @return the first delivery object that needs to be serviced, else
153  * NULL if none
154  */
156 
157 /** Get the next delivery on the connection that needs has pending
158  * operations.
159  *
160  * @param[in] delivery the previous delivery retrieved from
161  * either pn_work_head() or pn_work_next()
162  * @return the next delivery that has pending operations, else
163  * NULL if none
164  */
166 
167 /** Factory for creating a new session on the connection.
168  *
169  * A new session is created for the connection, and is added to the
170  * set of sessions maintained by the connection.
171  *
172  * @param[in] connection the session will exist over this connection
173  * @return pointer to new session
174  */
176 
177 /** Factory for creating a transport.
178  *
179  * A transport to be used by a connection to interface with the
180  * network. There can only be one connection associated with a
181  * transport. See pn_transport_bind().
182  *
183  * @return pointer to new transport
184  */
186 
187 /** Binds the transport to an AMQP connection endpoint.
188  *
189  * @return an error code, or 0 on success
190  */
191 
192 int pn_transport_bind(pn_transport_t *transport, pn_connection_t *connection);
193 
194 int pn_transport_unbind(pn_transport_t *transport);
195 
196 /** Retrieve the first Session that matches the given state mask.
197  *
198  * Examines the state of each session owned by the connection, and
199  * returns the first Session that matches the given state mask. If
200  * state contains both local and remote flags, then an exact match
201  * against those flags is performed. If state contains only local or
202  * only remote flags, then a match occurs if any of the local or
203  * remote flags are set respectively.
204  *
205  * @param[in] connection to be searched for matching sessions
206  * @param[in] state mask to match
207  * @return the first session owned by the connection that matches the
208  * mask, else NULL if no sessions match
209  */
210 pn_session_t *pn_session_head(pn_connection_t *connection, pn_state_t state);
211 
212 /** Retrieve the next Session that matches the given state mask.
213  *
214  * When used with pn_session_head(), application can access all
215  * Sessions on the connection that match the given state. See
216  * pn_session_head() for description of match behavior.
217  *
218  * @param[in] session the previous session obtained from
219  * pn_session_head() or pn_session_next()
220  * @param[in] state mask to match.
221  * @return the next session owned by the connection that matches the
222  * mask, else NULL if no sessions match
223  */
224 pn_session_t *pn_session_next(pn_session_t *session, pn_state_t state);
225 
226 /** Retrieve the first Link that matches the given state mask.
227  *
228  * Examines the state of each Link owned by the connection and returns
229  * the first Link that matches the given state mask. If state contains
230  * both local and remote flags, then an exact match against those
231  * flags is performed. If state contains only local or only remote
232  * flags, then a match occurs if any of the local or remote flags are
233  * set respectively.
234  *
235  * @param[in] connection to be searched for matching Links
236  * @param[in] state mask to match
237  * @return the first Link owned by the connection that matches the
238  * mask, else NULL if no Links match
239  */
240 pn_link_t *pn_link_head(pn_connection_t *connection, pn_state_t state);
241 
242 /** Retrieve the next Link that matches the given state mask.
243  *
244  * When used with pn_link_head(), the application can access all Links
245  * on the connection that match the given state. See pn_link_head()
246  * for description of match behavior.
247  *
248  * @param[in] link the previous Link obtained from pn_link_head() or
249  * pn_link_next()
250  * @param[in] state mask to match
251  * @return the next session owned by the connection that matches the
252  * mask, else NULL if no sessions match
253  */
254 pn_link_t *pn_link_next(pn_link_t *link, pn_state_t state);
255 
256 void pn_connection_reset(pn_connection_t *connection);
257 void pn_connection_open(pn_connection_t *connection);
258 void pn_connection_close(pn_connection_t *connection);
259 void pn_connection_free(pn_connection_t *connection);
260 
261 /** Access the application context that is associated with the
262  * connection.
263  *
264  * @param[in] connection the connection whose context is to be returned.
265  *
266  * @return the application context that was passed to pn_connection_set_context()
267  */
268 void *pn_connection_get_context(pn_connection_t *connection);
269 
270 /** Assign a new application context to the connection.
271  *
272  * @param[in] connection the connection which will hold the context.
273  * @param[in] context new application context to associate with the
274  * connection
275  */
276 void pn_connection_set_context(pn_connection_t *connection, void *context);
277 
278 
279 // transport
281 ssize_t pn_transport_input(pn_transport_t *transport, const char *bytes, size_t available);
282 ssize_t pn_transport_output(pn_transport_t *transport, char *bytes, size_t size);
283 /** Process any pending transport timer events.
284  *
285  * This method should be called after all pending input has been processed by the
286  * transport (see ::pn_transport_input), and before generating output (see
287  * ::pn_transport_output). It returns the deadline for the next pending timer event, if
288  * any are present.
289  *
290  * @param[in] transport the transport to process.
291  *
292  * @return if non-zero, then the expiration time of the next pending timer event for the
293  * transport. The caller must invoke pn_transport_tick again at least once at or before
294  * this deadline occurs.
295  */
297 void pn_transport_trace(pn_transport_t *transport, pn_trace_t trace);
298 // max frame of zero means "unlimited"
299 uint32_t pn_transport_get_max_frame(pn_transport_t *transport);
300 void pn_transport_set_max_frame(pn_transport_t *transport, uint32_t size);
302 /* timeout of zero means "no timeout" */
306 uint64_t pn_transport_get_frames_output(const pn_transport_t *transport);
307 uint64_t pn_transport_get_frames_input(const pn_transport_t *transport);
308 void pn_transport_free(pn_transport_t *transport);
309 
310 // session
311 pn_state_t pn_session_state(pn_session_t *session);
314 void pn_session_open(pn_session_t *session);
315 void pn_session_close(pn_session_t *session);
316 void pn_session_free(pn_session_t *session);
317 void *pn_session_get_context(pn_session_t *session);
318 void pn_session_set_context(pn_session_t *session, void *context);
319 
320 // link
321 pn_link_t *pn_sender(pn_session_t *session, const char *name);
322 pn_link_t *pn_receiver(pn_session_t *session, const char *name);
323 const char *pn_link_name(pn_link_t *link);
324 bool pn_link_is_sender(pn_link_t *link);
325 bool pn_link_is_receiver(pn_link_t *link);
326 pn_state_t pn_link_state(pn_link_t *link);
334 bool pn_link_advance(pn_link_t *link);
335 int pn_link_credit(pn_link_t *link);
336 int pn_link_queued(pn_link_t *link);
337 int pn_link_available(pn_link_t *link);
338 
339 int pn_link_unsettled(pn_link_t *link);
342 
343 void pn_link_open(pn_link_t *sender);
344 void pn_link_close(pn_link_t *sender);
345 void pn_link_free(pn_link_t *sender);
346 void *pn_link_get_context(pn_link_t *link);
347 void pn_link_set_context(pn_link_t *link, void *context);
348 
349 // sender
350 void pn_link_offered(pn_link_t *sender, int credit);
351 ssize_t pn_link_send(pn_link_t *sender, const char *bytes, size_t n);
352 void pn_link_drained(pn_link_t *sender);
353 //void pn_link_abort(pn_sender_t *sender);
354 
355 // receiver
356 void pn_link_flow(pn_link_t *receiver, int credit);
357 void pn_link_drain(pn_link_t *receiver, int credit);
358 ssize_t pn_link_recv(pn_link_t *receiver, char *bytes, size_t n);
359 
360 // terminus
363 
364 const char *pn_terminus_get_address(pn_terminus_t *terminus);
365 int pn_terminus_set_address(pn_terminus_t *terminus, const char *address);
368  pn_durability_t durability);
373 bool pn_terminus_is_dynamic(pn_terminus_t *terminus);
374 int pn_terminus_set_dynamic(pn_terminus_t *terminus, bool dynamic);
379 int pn_terminus_copy(pn_terminus_t *terminus, pn_terminus_t *src);
380 
381 // delivery
385 // how do we do delivery state?
388 bool pn_delivery_settled(pn_delivery_t *delivery);
389 size_t pn_delivery_pending(pn_delivery_t *delivery);
390 bool pn_delivery_partial(pn_delivery_t *delivery);
391 bool pn_delivery_writable(pn_delivery_t *delivery);
392 bool pn_delivery_readable(pn_delivery_t *delivery);
393 bool pn_delivery_updated(pn_delivery_t *delivery);
394 void pn_delivery_update(pn_delivery_t *delivery, pn_disposition_t disposition);
395 void pn_delivery_clear(pn_delivery_t *delivery);
396 //int pn_delivery_format(pn_delivery_t *delivery);
397 void pn_delivery_settle(pn_delivery_t *delivery);
398 void pn_delivery_dump(pn_delivery_t *delivery);
399 void *pn_delivery_get_context(pn_delivery_t *delivery);
400 void pn_delivery_set_context(pn_delivery_t *delivery, void *context);
401 
404 
407 
410 
411 bool pn_condition_is_set(pn_condition_t *condition);
412 void pn_condition_clear(pn_condition_t *condition);
413 
414 const char *pn_condition_get_name(pn_condition_t *condition);
415 int pn_condition_set_name(pn_condition_t *condition, const char *name);
416 
417 const char *pn_condition_get_description(pn_condition_t *condition);
418 int pn_condition_set_description(pn_condition_t *condition, const char *description);
419 
421 
423 const char *pn_condition_redirect_host(pn_condition_t *condition);
425 
426 #ifdef __cplusplus
427 }
428 #endif
429 
430 #endif /* engine.h */