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