proton
0
Main Page
Related Pages
Modules
Data Structures
Files
File List
Globals
All
Data Structures
Files
Functions
Variables
Typedefs
Enumerations
Enumerator
Macros
Groups
Pages
include
proton
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
;
52
typedef
struct
pn_listener_t
pn_listener_t
;
53
typedef
struct
pn_connector_t
pn_connector_t
;
54
55
typedef
enum
{
56
PN_CONNECTOR_WRITABLE
,
57
PN_CONNECTOR_READABLE
58
}
pn_activate_criteria_t
;
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
*/
65
PN_EXTERN
pn_driver_t
*
pn_driver
(
void
);
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
*/
73
PN_EXTERN
int
pn_driver_errno
(
pn_driver_t
*d);
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
*/
97
PN_EXTERN
int
pn_driver_wakeup
(
pn_driver_t
*driver);
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
*/
114
PN_EXTERN
pn_listener_t
*
pn_driver_listener
(
pn_driver_t
*driver);
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
*/
124
PN_EXTERN
pn_connector_t
*
pn_driver_connector
(
pn_driver_t
*driver);
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
*/
155
PN_EXTERN
pn_listener_t
*
pn_listener_head
(
pn_driver_t
*driver);
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
*/
164
PN_EXTERN
pn_listener_t
*
pn_listener_next
(
pn_listener_t
*listener);
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
*/
176
PN_EXTERN
pn_connector_t
*
pn_listener_accept
(
pn_listener_t
*listener);
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
*/
184
PN_EXTERN
void
*
pn_listener_context
(
pn_listener_t
*listener);
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
*/
192
PN_EXTERN
void
pn_listener_close
(
pn_listener_t
*listener);
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
*/
201
PN_EXTERN
void
pn_listener_free
(
pn_listener_t
*listener);
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
*/
226
PN_EXTERN
pn_connector_t
*
pn_connector_head
(
pn_driver_t
*driver);
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
*/
235
PN_EXTERN
pn_connector_t
*
pn_connector_next
(
pn_connector_t
*connector);
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
*/
251
PN_EXTERN
void
pn_connector_process
(
pn_connector_t
*connector);
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
*/
260
PN_EXTERN
pn_listener_t
*
pn_connector_listener
(
pn_connector_t
*connector);
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
*/
269
PN_EXTERN
pn_sasl_t
*
pn_connector_sasl
(
pn_connector_t
*connector);
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
*/
277
PN_EXTERN
pn_connection_t
*
pn_connector_connection
(
pn_connector_t
*connector);
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
*/
285
PN_EXTERN
void
pn_connector_set_connection
(
pn_connector_t
*connector,
pn_connection_t
*connection);
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
*/
294
PN_EXTERN
void
*
pn_connector_context
(
pn_connector_t
*connector);
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
*/
316
PN_EXTERN
pn_transport_t
*
pn_connector_transport
(
pn_connector_t
*connector);
317
318
/** Close the socket used by the connector.
319
*
320
* @param[in] connector the connector whose socket will be closed
321
*/
322
PN_EXTERN
void
pn_connector_close
(
pn_connector_t
*connector);
323
324
/** Determine if the connector is closed.
325
*
326
* @return True if closed, otherwise false
327
*/
328
PN_EXTERN
bool
pn_connector_closed
(
pn_connector_t
*connector);
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
*/
337
PN_EXTERN
void
pn_connector_free
(
pn_connector_t
*connector);
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
*/
347
PN_EXTERN
void
pn_connector_activate
(
pn_connector_t
*connector,
pn_activate_criteria_t
criteria);
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
*/
363
PN_EXTERN
bool
pn_connector_activated
(
pn_connector_t
*connector,
pn_activate_criteria_t
criteria);
364
365
366
#ifdef __cplusplus
367
}
368
#endif
369
370
#endif
/* driver.h */
Generated on Thu Jul 10 2014 02:10:59 for proton by
1.8.3.1