proton  0
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
driver.h
Go to the documentation of this file.
1 #ifndef PROTON_DRIVER_H
2 #define PROTON_DRIVER_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/error.h>
27 #include <proton/sasl.h>
28 #include <proton/selectable.h>
29 #include <proton/ssl.h>
30 #include <proton/transport.h>
31 #include <proton/types.h>
32 
33 #ifdef __cplusplus
34 extern "C" {
35 #endif
36 
37 /** @file
38  * API for the Driver Layer.
39  *
40  * The driver library provides a simple implementation of a driver for
41  * the proton engine. A driver is responsible for providing input,
42  * output, and tick events to the bottom half of the engine API. See
43  * ::pn_transport_input, ::pn_transport_output, and
44  * ::pn_transport_tick. The driver also provides an interface for the
45  * application to access the top half of the API when the state of the
46  * engine may have changed due to I/O or timing events. Additionally
47  * the driver incorporates the SASL engine as well in order to provide
48  * a complete network stack: AMQP over SASL over TCP.
49  *
50  */
51 
52 typedef struct pn_driver_t pn_driver_t;
55 
56 typedef enum {
60 
61 /** Construct a driver
62  *
63  * Call pn_driver_free() to release the driver object.
64  * @return new driver object, NULL if error
65  */
67 
68 /** Return the most recent error code.
69  *
70  * @param[in] d the driver
71  *
72  * @return the most recent error text for d
73  */
75 
76 /** Get additional error information associated with the driver.
77  *
78  * Whenever a driver operation fails, additional error information can
79  * be obtained using this function. The error object that is returned
80  * may also be used to clear the error condition.
81  *
82  * The pointer returned by this operation is valid until the
83  * driver object is freed.
84  *
85  * @param[in] d the driver
86  *
87  * @return the driver's error object
88  */
90 
91 /** Set the tracing level for the given driver.
92  *
93  * @param[in] driver the driver to trace
94  * @param[in] trace the trace level to use.
95  * @todo pn_trace_t needs documentation
96  */
97 PN_EXTERN void pn_driver_trace(pn_driver_t *driver, pn_trace_t trace);
98 
99 /** Force pn_driver_wait() to return
100  *
101  * @param[in] driver the driver to wake up
102  *
103  * @return zero on success, an error code on failure
104  */
106 
107 /** Wait for an active connector or listener
108  *
109  * @param[in] driver the driver to wait on
110  * @param[in] timeout maximum time in milliseconds to wait, -1 means
111  * infinite wait
112  *
113  * @return zero on success, an error code on failure
114  */
115 PN_EXTERN int pn_driver_wait(pn_driver_t *driver, int timeout);
116 
117 /** Get the next listener with pending data in the driver.
118  *
119  * @param[in] driver the driver
120  * @return NULL if no active listener available
121  */
123 
124 /** Get the next active connector in the driver.
125  *
126  * Returns the next connector with pending inbound data, available
127  * capacity for outbound data, or pending tick.
128  *
129  * @param[in] driver the driver
130  * @return NULL if no active connector available
131  */
133 
134 /** Free the driver allocated via pn_driver, and all associated
135  * listeners and connectors.
136  *
137  * @param[in] driver the driver to free, no longer valid on
138  * return
139  */
140 PN_EXTERN void pn_driver_free(pn_driver_t *driver);
141 
142 
143 /** pn_listener - the server API **/
144 
145 /** Construct a listener for the given address.
146  *
147  * @param[in] driver driver that will 'own' this listener
148  * @param[in] host local host address to listen on
149  * @param[in] port local port to listen on
150  * @param[in] context application-supplied, can be accessed via
151  * pn_listener_context()
152  * @return a new listener on the given host:port, NULL if error
153  */
154 PN_EXTERN pn_listener_t *pn_listener(pn_driver_t *driver, const char *host,
155  const char *port, void* context);
156 
157 /** Access the head listener for a driver.
158  *
159  * @param[in] driver the driver whose head listener will be returned
160  *
161  * @return the head listener for driver or NULL if there is none
162  */
164 
165 /** Access the next listener.
166  *
167  * @param[in] listener the listener whose next listener will be
168  * returned
169  *
170  * @return the next listener
171  */
173 
174 /**
175  * @todo pn_listener_trace needs documentation
176  */
177 PN_EXTERN void pn_listener_trace(pn_listener_t *listener, pn_trace_t trace);
178 
179 /** Accept a connection that is pending on the listener.
180  *
181  * @param[in] listener the listener to accept the connection on
182  * @return a new connector for the remote, or NULL on error
183  */
185 
186 /** Access the application context that is associated with the listener.
187  *
188  * @param[in] listener the listener whose context is to be returned
189  * @return the application context that was passed to pn_listener() or
190  * pn_listener_fd()
191  */
193 
194 PN_EXTERN void pn_listener_set_context(pn_listener_t *listener, void *context);
195 
196 /** Close the socket used by the listener.
197  *
198  * @param[in] listener the listener whose socket will be closed.
199  */
201 
202 /** Frees the given listener.
203  *
204  * Assumes the listener's socket has been closed prior to call.
205  *
206  * @param[in] listener the listener object to free, no longer valid
207  * on return
208  */
210 
211 
212 
213 
214 /** pn_connector - the client API **/
215 
216 /** Construct a connector to the given remote address.
217  *
218  * @param[in] driver owner of this connection.
219  * @param[in] host remote host to connect to.
220  * @param[in] port remote port to connect to.
221  * @param[in] context application supplied, can be accessed via
222  * pn_connector_context() @return a new connector
223  * to the given remote, or NULL on error.
224  */
225 PN_EXTERN pn_connector_t *pn_connector(pn_driver_t *driver, const char *host,
226  const char *port, void* context);
227 
228 /** Access the head connector for a driver.
229  *
230  * @param[in] driver the driver whose head connector will be returned
231  *
232  * @return the head connector for driver or NULL if there is none
233  */
235 
236 /** Access the next connector.
237  *
238  * @param[in] connector the connector whose next connector will be
239  * returned
240  *
241  * @return the next connector
242  */
244 
245 /** Set the tracing level for the given connector.
246  *
247  * @param[in] connector the connector to trace
248  * @param[in] trace the trace level to use.
249  */
250 PN_EXTERN void pn_connector_trace(pn_connector_t *connector, pn_trace_t trace);
251 
252 /** Service the given connector.
253  *
254  * Handle any inbound data, outbound data, or timing events pending on
255  * the connector.
256  *
257  * @param[in] connector the connector to process.
258  */
260 
261 /** Access the listener which opened this connector.
262  *
263  * @param[in] connector connector whose listener will be returned.
264  * @return the listener which created this connector, or NULL if the
265  * connector has no listener (e.g. an outbound client
266  * connection)
267  */
269 
270 /** Access the Authentication and Security context of the connector.
271  *
272  * @param[in] connector connector whose security context will be
273  * returned
274  * @return the Authentication and Security context for the connector,
275  * or NULL if none
276  */
278 
279 /** Access the AMQP Connection associated with the connector.
280  *
281  * @param[in] connector the connector whose connection will be
282  * returned
283  * @return the connection context for the connector, or NULL if none
284  */
286 
287 /** Assign the AMQP Connection associated with the connector.
288  *
289  * @param[in] connector the connector whose connection will be set.
290  * @param[in] connection the connection to associate with the
291  * connector
292  */
294 
295 /** Access the application context that is associated with the
296  * connector.
297  *
298  * @param[in] connector the connector whose context is to be returned.
299  * @return the application context that was passed to pn_connector()
300  * or pn_connector_fd()
301  */
303 
304 /** Assign a new application context to the connector.
305  *
306  * @param[in] connector the connector which will hold the context.
307  * @param[in] context new application context to associate with the
308  * connector
309  */
310 PN_EXTERN void pn_connector_set_context(pn_connector_t *connector, void *context);
311 
312 /** Access the name of the connector
313  *
314  * @param[in] connector the connector which will hole the name
315  * @return the name of the connector in the form of a null-terminated character string.
316  */
317 PN_EXTERN const char *pn_connector_name(const pn_connector_t *connector);
318 
319 /** Access the transport used by this connector.
320  *
321  * @param[in] connector connector whose transport will be returned
322  * @return the transport, or NULL if none
323  */
325 
326 /** Close the socket used by the connector.
327  *
328  * @param[in] connector the connector whose socket will be closed
329  */
331 
332 /** Determine if the connector is closed.
333  *
334  * @return True if closed, otherwise false
335  */
337 
338 /** Destructor for the given connector.
339  *
340  * Assumes the connector's socket has been closed prior to call.
341  *
342  * @param[in] connector the connector object to free. No longer
343  * valid on return
344  */
346 
347 /** Activate a connector when a criteria is met
348  *
349  * Set a criteria for a connector (i.e. it's transport is writable) that, once met,
350  * the connector shall be placed in the driver's work queue.
351  *
352  * @param[in] connector The connector object to activate
353  * @param[in] criteria The criteria that must be met prior to activating the connector
354  */
356 
357 /** Return the activation status of the connector for a criteria
358  *
359  * Return the activation status (i.e. readable, writable) for the connector. This function
360  * has the side-effect of canceling the activation of the criteria.
361  *
362  * Please note that this function must not be used for normal AMQP connectors. It is only
363  * used for connectors created so the driver can track non-AMQP file descriptors. Such
364  * connectors are never passed into pn_connector_process.
365  *
366  * @param[in] connector The connector object to activate
367  * @param[in] criteria The criteria to test. "Is this the reason the connector appeared
368  * in the work list?"
369  * @return true iff the criteria is activated on the connector.
370  */
372 
373 
374 #ifdef __cplusplus
375 }
376 #endif
377 
378 #endif /* driver.h */
PN_EXTERN pn_driver_t * pn_driver(void)
Construct a driver.
PN_EXTERN void pn_driver_free(pn_driver_t *driver)
Free the driver allocated via pn_driver, and all associated listeners and connectors.
struct pn_error_t pn_error_t
Definition: error.h:32
struct pn_connector_t pn_connector_t
Definition: driver.h:54
PN_EXTERN void pn_listener_trace(pn_listener_t *listener, pn_trace_t trace)
PN_EXTERN int pn_driver_errno(pn_driver_t *d)
Return the most recent error code.
PN_EXTERN void pn_connector_activate(pn_connector_t *connector, pn_activate_criteria_t criteria)
Activate a connector when a criteria is met.
PN_EXTERN pn_listener_t * pn_listener_head(pn_driver_t *driver)
Access the head listener for a driver.
PN_EXTERN pn_connection_t * pn_connector_connection(pn_connector_t *connector)
Access the AMQP Connection associated with the connector.
PN_EXTERN void * pn_listener_context(pn_listener_t *listener)
Access the application context that is associated with the listener.
#define PN_EXTERN
Definition: import_export.h:53
The selectable API provides an interface for integration with third party event loops.
PN_EXTERN pn_listener_t * pn_driver_listener(pn_driver_t *driver)
Get the next listener with pending data in the driver.
PN_EXTERN void pn_listener_set_context(pn_listener_t *listener, void *context)
PN_EXTERN pn_connector_t * pn_listener_accept(pn_listener_t *listener)
Accept a connection that is pending on the listener.
PN_EXTERN void pn_connector_close(pn_connector_t *connector)
Close the socket used by the connector.
API for using SSL with the Transport Layer.
PN_EXTERN bool pn_connector_closed(pn_connector_t *connector)
Determine if the connector is closed.
PN_EXTERN int pn_driver_wait(pn_driver_t *driver, int timeout)
Wait for an active connector or listener.
PN_EXTERN void pn_listener_close(pn_listener_t *listener)
Close the socket used by the listener.
PN_EXTERN pn_listener_t * pn_connector_listener(pn_connector_t *connector)
Access the listener which opened this connector.
PN_EXTERN void pn_connector_trace(pn_connector_t *connector, pn_trace_t trace)
Set the tracing level for the given connector.
PN_EXTERN pn_connector_t * pn_connector_head(pn_driver_t *driver)
Access the head connector for a driver.
pn_activate_criteria_t
Definition: driver.h:56
PN_EXTERN pn_connector_t * pn_connector_next(pn_connector_t *connector)
Access the next connector.
PN_EXTERN void pn_connector_process(pn_connector_t *connector)
Service the given connector.
PN_EXTERN bool pn_connector_activated(pn_connector_t *connector, pn_activate_criteria_t criteria)
Return the activation status of the connector for a criteria.
PN_EXTERN void pn_connector_set_context(pn_connector_t *connector, void *context)
Assign a new application context to the connector.
struct pn_sasl_t pn_sasl_t
Definition: sasl.h:48
Definition: driver.h:57
PN_EXTERN void pn_driver_trace(pn_driver_t *driver, pn_trace_t trace)
Set the tracing level for the given driver.
PN_EXTERN pn_sasl_t * pn_connector_sasl(pn_connector_t *connector)
Access the Authentication and Security context of the connector.
PN_EXTERN void pn_connector_free(pn_connector_t *connector)
Destructor for the given connector.
PN_EXTERN pn_listener_t * pn_listener_next(pn_listener_t *listener)
Access the next listener.
PN_EXTERN void pn_listener_free(pn_listener_t *listener)
Frees the given listener.
Transport API for the proton Engine.
struct pn_connection_t pn_connection_t
An AMQP Connection object.
Definition: types.h:111
struct pn_driver_t pn_driver_t
Definition: driver.h:52
PN_EXTERN int pn_driver_wakeup(pn_driver_t *driver)
Force pn_driver_wait() to return.
API for the SASL Secure Transport Layer.
PN_EXTERN pn_connector_t * pn_driver_connector(pn_driver_t *driver)
Get the next active connector in the driver.
PN_EXTERN pn_error_t * pn_driver_error(pn_driver_t *d)
Get additional error information associated with the driver.
PN_EXTERN pn_transport_t * pn_connector_transport(pn_connector_t *connector)
Access the transport used by this connector.
PN_EXTERN pn_connector_t * pn_connector(pn_driver_t *driver, const char *host, const char *port, void *context)
pn_connector - the client API
struct pn_listener_t pn_listener_t
Definition: driver.h:53
PN_EXTERN const char * pn_connector_name(const pn_connector_t *connector)
Access the name of the connector.
int pn_trace_t
Holds the trace flags for an AMQP transport.
Definition: transport.h:58
PN_EXTERN pn_listener_t * pn_listener(pn_driver_t *driver, const char *host, const char *port, void *context)
pn_listener - the server API
Definition: driver.h:58
PN_EXTERN void * pn_connector_context(pn_connector_t *connector)
Access the application context that is associated with the connector.
struct pn_transport_t pn_transport_t
An AMQP Transport object.
Definition: types.h:255
PN_EXTERN void pn_connector_set_connection(pn_connector_t *connector, pn_connection_t *connection)
Assign the AMQP Connection associated with the connector.