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