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
proton-c
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 Mon Jun 2 2014 22:59:05 for proton by
1.8.1.2