proton  0
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
connection.h
Go to the documentation of this file.
1 #ifndef PROTON_CONNECTION_H
2 #define PROTON_CONNECTION_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/codec.h>
27 #include <proton/condition.h>
28 #include <proton/error.h>
29 #include <proton/type_compat.h>
30 #include <proton/types.h>
31 
32 #include <stddef.h>
33 #include <sys/types.h>
34 
35 #ifdef __cplusplus
36 extern "C" {
37 #endif
38 
39 /**
40  * @file
41  *
42  * Connection API for the proton Engine.
43  *
44  * @defgroup connection Connection
45  * @ingroup engine
46  * @{
47  */
48 
49 /**
50  * The local @link pn_state_t endpoint state @endlink is uninitialized.
51  */
52 #define PN_LOCAL_UNINIT (1)
53 /**
54  * The local @link pn_state_t endpoint state @endlink is active.
55  */
56 #define PN_LOCAL_ACTIVE (2)
57 /**
58  * The local @link pn_state_t endpoint state @endlink is closed.
59  */
60 #define PN_LOCAL_CLOSED (4)
61 /**
62  * The remote @link pn_state_t endpoint state @endlink is uninitialized.
63  */
64 #define PN_REMOTE_UNINIT (8)
65 /**
66  * The remote @link pn_state_t endpoint state @endlink is active.
67  */
68 #define PN_REMOTE_ACTIVE (16)
69 /**
70  * The remote @link pn_state_t endpoint state @endlink is closed.
71  */
72 #define PN_REMOTE_CLOSED (32)
73 
74 /**
75  * A mask for values of ::pn_state_t that preserves only the local
76  * bits of an endpoint's state.
77  */
78 #define PN_LOCAL_MASK (PN_LOCAL_UNINIT | PN_LOCAL_ACTIVE | PN_LOCAL_CLOSED)
79 
80 /**
81  * A mask for values of ::pn_state_t that preserves only the remote
82  * bits of an endpoint's state.
83  */
84 #define PN_REMOTE_MASK (PN_REMOTE_UNINIT | PN_REMOTE_ACTIVE | PN_REMOTE_CLOSED)
85 
86 /**
87  * Factory to construct a new Connection.
88  *
89  * @return pointer to a new connection object.
90  */
92 
93 /**
94  * Free a connection object.
95  *
96  * When a connection object is freed, all ::pn_session_t, ::pn_link_t,
97  * and ::pn_delivery_t objects associated with the connection are also
98  * freed.
99  *
100  * @param[in] connection the connection object to free (or NULL)
101  */
103 
104 /**
105  * Get additional error information associated with the connection.
106  *
107  * Whenever a connection operation fails (i.e. returns an error code),
108  * additional error details can be obtained using this function. The
109  * error object that is returned may also be used to clear the error
110  * condition.
111  *
112  * The pointer returned by this operation is valid until the
113  * connection object is freed.
114  *
115  * @param[in] connection the connection object
116  * @return the connection's error object
117  */
119 
120 /**
121  * Associate a connection object with an event collector.
122  *
123  * By associating a connection object with an event collector, key
124  * changes in endpoint state are reported to the collector via
125  * ::pn_event_t objects that can be inspected and processed. See
126  * ::pn_event_t for more details on the kinds of events.
127  *
128  * Note that by registering a collector, the user is requesting that
129  * an indefinite number of events be queued up on his behalf. This
130  * means that unless the application eventually processes these
131  * events, the storage requirements for keeping them will grow without
132  * bound. In other words, don't register a collector with a connection
133  * if you never intend to process any of the events.
134  *
135  * @param[in] connection the connection object
136  * @param[in] collector the event collector
137  */
138 PN_EXTERN void pn_connection_collect(pn_connection_t *connection, pn_collector_t *collector);
139 
140 /**
141  * Get the application context that is associated with a connection
142  * object.
143  *
144  * The application context for a connection may be set using
145  * ::pn_connection_set_context.
146  *
147  * @param[in] connection the connection whose context is to be returned.
148  * @return the application context for the connection object
149  */
151 
152 /**
153  * Set a new application context for a connection object.
154  *
155  * The application context for a connection object may be retrieved
156  * using ::pn_connection_get_context.
157  *
158  * @param[in] connection the connection object
159  * @param[in] context the application context
160  */
161 PN_EXTERN void pn_connection_set_context(pn_connection_t *connection, void *context);
162 
163 /**
164  * Get the endpoint state flags for a connection.
165  *
166  * @param[in] connection the connection
167  * @return the connection's state flags
168  */
170 
171 /**
172  * Open a connection.
173  *
174  * Once this operation has completed, the PN_LOCAL_ACTIVE state flag
175  * will be set.
176  *
177  * @param[in] connection a connection object
178  */
180 
181 /**
182  * Close a connection.
183  *
184  * Once this operation has completed, the PN_LOCAL_CLOSED state flag
185  * will be set. This may be called without calling
186  * ::pn_connection_open, in this case it is equivalent to calling
187  * ::pn_connection_open followed by ::pn_connection_close.
188  *
189  * @param[in] connection a connection object
190  */
192 
193 /**
194  * Reset a connection object back to the uninitialized state.
195  *
196  * Note that this does *not* remove any contained ::pn_session_t,
197  * ::pn_link_t, and ::pn_delivery_t objects.
198  *
199  * @param[in] connection a connection object
200  */
202 
203 /**
204  * Get the local condition associated with the connection endpoint.
205  *
206  * The ::pn_condition_t object retrieved may be modified prior to
207  * closing the connection in order to indicate a particular condition
208  * exists when the connection closes. This is normally used to
209  * communicate error conditions to the remote peer, however it may
210  * also be used in non error cases such as redirects. See
211  * ::pn_condition_t for more details.
212  *
213  * The pointer returned by this operation is valid until the
214  * connection object is freed.
215  *
216  * @param[in] connection the connection object
217  * @return the connection's local condition object
218  */
220 
221 /**
222  * Get the remote condition associated with the connection endpoint.
223  *
224  * The ::pn_condition_t object retrieved may be examined in order to
225  * determine whether the remote peer was indicating some sort of
226  * exceptional condition when the remote connection endpoint was
227  * closed. The ::pn_condition_t object returned may not be modified.
228  *
229  * The pointer returned by this operation is valid until the
230  * connection object is freed.
231  *
232  * @param[in] connection the connection object
233  * @return the connection's remote condition object
234  */
236 
237 /**
238  * Get the AMQP Container name advertised by a connection object.
239  *
240  * The pointer returned by this operation is valid until
241  * ::pn_connection_set_container is called, or until the connection
242  * object is freed, whichever happens sooner.
243  *
244  * @param[in] connection the connection object
245  * @return a pointer to the container name
246  */
247 PN_EXTERN const char *pn_connection_get_container(pn_connection_t *connection);
248 
249 /**
250  * Set the AMQP Container name advertised by a connection object.
251  *
252  * @param[in] connection the connection object
253  * @param[in] container the container name
254  */
255 PN_EXTERN void pn_connection_set_container(pn_connection_t *connection, const char *container);
256 
257 /**
258  * Get the value of the AMQP Hostname used by a connection object.
259  *
260  * The pointer returned by this operation is valid until
261  * ::pn_connection_set_hostname is called, or until the connection
262  * object is freed, whichever happens sooner.
263  *
264  * @param[in] connection the connection object
265  * @return a pointer to the hostname
266  */
267 PN_EXTERN const char *pn_connection_get_hostname(pn_connection_t *connection);
268 
269 /**
270  * Set the value of the AMQP Hostname used by a connection object.
271  *
272  * @param[in] connection the connection object
273  * @param[in] hostname the hostname
274  */
275 PN_EXTERN void pn_connection_set_hostname(pn_connection_t *connection, const char *hostname);
276 
277 /**
278  * Get the AMQP Container name advertised by the remote connection
279  * endpoint.
280  *
281  * This will return NULL until the ::PN_REMOTE_ACTIVE state is
282  * reached. See ::pn_state_t for more details on endpoint state.
283  *
284  * Any non null pointer returned by this operation will be valid until
285  * the connection object is unbound from a transport or freed,
286  * whichever happens sooner.
287  *
288  * @param[in] connection the connection object
289  * @return a pointer to the remote container name
290  */
292 
293 /**
294  * Get the AMQP Hostname set by the remote connection endpoint.
295  *
296  * This will return NULL until the ::PN_REMOTE_ACTIVE state is
297  * reached. See ::pn_state_t for more details on endpoint state.
298  *
299  * Any non null pointer returned by this operation will be valid until
300  * the connection object is unbound from a transport or freed,
301  * whichever happens sooner.
302  *
303  * @param[in] connection the connection object
304  * @return a pointer to the remote hostname
305  */
307 
308 /**
309  * Access/modify the AMQP offered capabilities data for a connection
310  * object.
311  *
312  * This operation will return a pointer to a ::pn_data_t object that
313  * is valid until the connection object is freed. Any data contained
314  * by the ::pn_data_t object will be sent as the offered capabilites
315  * for the parent connection object. Note that this MUST take the form
316  * of an array of symbols to be valid.
317  *
318  * The ::pn_data_t pointer returned is valid until the connection
319  * object is freed.
320  *
321  * @param[in] connection the connection object
322  * @return a pointer to a pn_data_t representing the offered capabilities
323  */
325 
326 /**
327  * Access/modify the AMQP desired capabilities data for a connection
328  * object.
329  *
330  * This operation will return a pointer to a ::pn_data_t object that
331  * is valid until the connection object is freed. Any data contained
332  * by the ::pn_data_t object will be sent as the desired capabilites
333  * for the parent connection object. Note that this MUST take the form
334  * of an array of symbols to be valid.
335  *
336  * The ::pn_data_t pointer returned is valid until the connection
337  * object is freed.
338  *
339  * @param[in] connection the connection object
340  * @return a pointer to a pn_data_t representing the desired capabilities
341  */
343 
344 /**
345  * Access/modify the AMQP properties data for a connection object.
346  *
347  * This operation will return a pointer to a ::pn_data_t object that
348  * is valid until the connection object is freed. Any data contained
349  * by the ::pn_data_t object will be sent as the AMQP properties for
350  * the parent connection object. Note that this MUST take the form of
351  * a symbol keyed map to be valid.
352  *
353  * The ::pn_data_t pointer returned is valid until the connection
354  * object is freed.
355  *
356  * @param[in] connection the connection object
357  * @return a pointer to a pn_data_t representing the connection properties
358  */
360 
361 /**
362  * Access the AMQP offered capabilites supplied by the remote
363  * connection endpoint.
364  *
365  * This operation will return a pointer to a ::pn_data_t object that
366  * is valid until the connection object is freed. This data object
367  * will be empty until the remote connection is opened as indicated by
368  * the ::PN_REMOTE_ACTIVE flag.
369  *
370  * @param[in] connection the connection object
371  * @return the remote offered capabilities
372  */
374 
375 /**
376  * Access the AMQP desired capabilites supplied by the remote
377  * connection endpoint.
378  *
379  * This operation will return a pointer to a ::pn_data_t object that
380  * is valid until the connection object is freed. This data object
381  * will be empty until the remote connection is opened as indicated by
382  * the ::PN_REMOTE_ACTIVE flag.
383  *
384  * @param[in] connection the connection object
385  * @return the remote desired capabilities
386  */
388 
389 /**
390  * Access the AMQP connection properties supplied by the remote
391  * connection endpoint.
392  *
393  * This operation will return a pointer to a ::pn_data_t object that
394  * is valid until the connection object is freed. This data object
395  * will be empty until the remote connection is opened as indicated by
396  * the ::PN_REMOTE_ACTIVE flag.
397  *
398  * @param[in] connection the connection object
399  * @return the remote connection properties
400  */
402 
403 /**
404  * Get the transport bound to a connection object.
405  *
406  * If the connection is unbound, then this operation will return NULL.
407  *
408  * @param[in] connection the connection object
409  * @return the transport bound to a connection, or NULL if the
410  * connection is unbound
411  */
413 
414 /** @}
415  */
416 
417 #ifdef __cplusplus
418 }
419 #endif
420 
421 #endif /* connection.h */
PN_EXTERN pn_data_t * pn_connection_remote_offered_capabilities(pn_connection_t *connection)
Access the AMQP offered capabilites supplied by the remote connection endpoint.
struct pn_error_t pn_error_t
Definition: error.h:32
PN_EXTERN pn_data_t * pn_connection_remote_desired_capabilities(pn_connection_t *connection)
Access the AMQP desired capabilites supplied by the remote connection endpoint.
PN_EXTERN void pn_connection_free(pn_connection_t *connection)
Free a connection object.
PN_EXTERN pn_data_t * pn_connection_remote_properties(pn_connection_t *connection)
Access the AMQP connection properties supplied by the remote connection endpoint. ...
PN_EXTERN void pn_connection_open(pn_connection_t *connection)
Open a connection.
The Condition API for the proton Engine.
struct pn_collector_t pn_collector_t
An event collector.
Definition: types.h:243
PN_EXTERN pn_condition_t * pn_connection_remote_condition(pn_connection_t *connection)
Get the remote condition associated with the connection endpoint.
#define PN_EXTERN
Definition: import_export.h:53
PN_EXTERN void * pn_connection_get_context(pn_connection_t *connection)
Get the application context that is associated with a connection object.
struct pn_data_t pn_data_t
Definition: codec.h:92
PN_EXTERN pn_transport_t * pn_connection_transport(pn_connection_t *connection)
Get the transport bound to a connection object.
PN_EXTERN void pn_connection_close(pn_connection_t *connection)
Close a connection.
PN_EXTERN pn_state_t pn_connection_state(pn_connection_t *connection)
Get the endpoint state flags for a connection.
PN_EXTERN const char * pn_connection_get_container(pn_connection_t *connection)
Get the AMQP Container name advertised by a connection object.
PN_EXTERN const char * pn_connection_remote_hostname(pn_connection_t *connection)
Get the AMQP Hostname set by the remote connection endpoint.
PN_EXTERN void pn_connection_set_context(pn_connection_t *connection, void *context)
Set a new application context for a connection object.
PN_EXTERN void pn_connection_set_hostname(pn_connection_t *connection, const char *hostname)
Set the value of the AMQP Hostname used by a connection object.
struct pn_condition_t pn_condition_t
An AMQP Condition object.
Definition: condition.h:65
PN_EXTERN pn_data_t * pn_connection_desired_capabilities(pn_connection_t *connection)
Access/modify the AMQP desired capabilities data for a connection object.
PN_EXTERN void pn_connection_reset(pn_connection_t *connection)
Reset a connection object back to the uninitialized state.
PN_EXTERN void pn_connection_set_container(pn_connection_t *connection, const char *container)
Set the AMQP Container name advertised by a connection object.
PN_EXTERN pn_data_t * pn_connection_offered_capabilities(pn_connection_t *connection)
Access/modify the AMQP offered capabilities data for a connection object.
PN_EXTERN pn_error_t * pn_connection_error(pn_connection_t *connection)
Get additional error information associated with the connection.
struct pn_connection_t pn_connection_t
An AMQP Connection object.
Definition: types.h:111
PN_EXTERN pn_data_t * pn_connection_properties(pn_connection_t *connection)
Access/modify the AMQP properties data for a connection object.
int pn_state_t
Holds the state flags for an AMQP endpoint.
Definition: types.h:96
PN_EXTERN const char * pn_connection_get_hostname(pn_connection_t *connection)
Get the value of the AMQP Hostname used by a connection object.
PN_EXTERN void pn_connection_collect(pn_connection_t *connection, pn_collector_t *collector)
Associate a connection object with an event collector.
PN_EXTERN pn_condition_t * pn_connection_condition(pn_connection_t *connection)
Get the local condition associated with the connection endpoint.
PN_EXTERN const char * pn_connection_remote_container(pn_connection_t *connection)
Get the AMQP Container name advertised by the remote connection endpoint.
PN_EXTERN pn_connection_t * pn_connection(void)
Factory to construct a new Connection.
struct pn_transport_t pn_transport_t
An AMQP Transport object.
Definition: types.h:255