proton  0
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 
34 #ifdef __cplusplus
35 extern "C" {
36 #endif
37 
38 /**
39  * @file
40  *
41  * Connection API for the proton Engine.
42  *
43  * @defgroup connection Connection
44  * @ingroup engine
45  * @{
46  */
47 
48 /**
49  * The local @link pn_state_t endpoint state @endlink is uninitialized.
50  */
51 #define PN_LOCAL_UNINIT (1)
52 /**
53  * The local @link pn_state_t endpoint state @endlink is active.
54  */
55 #define PN_LOCAL_ACTIVE (2)
56 /**
57  * The local @link pn_state_t endpoint state @endlink is closed.
58  */
59 #define PN_LOCAL_CLOSED (4)
60 /**
61  * The remote @link pn_state_t endpoint state @endlink is uninitialized.
62  */
63 #define PN_REMOTE_UNINIT (8)
64 /**
65  * The remote @link pn_state_t endpoint state @endlink is active.
66  */
67 #define PN_REMOTE_ACTIVE (16)
68 /**
69  * The remote @link pn_state_t endpoint state @endlink is closed.
70  */
71 #define PN_REMOTE_CLOSED (32)
72 
73 /**
74  * A mask for values of ::pn_state_t that preserves only the local
75  * bits of an endpoint's state.
76  */
77 #define PN_LOCAL_MASK (PN_LOCAL_UNINIT | PN_LOCAL_ACTIVE | PN_LOCAL_CLOSED)
78 
79 /**
80  * A mask for values of ::pn_state_t that preserves only the remote
81  * bits of an endpoint's state.
82  */
83 #define PN_REMOTE_MASK (PN_REMOTE_UNINIT | PN_REMOTE_ACTIVE | PN_REMOTE_CLOSED)
84 
85 /**
86  * Factory to construct a new Connection.
87  *
88  * @return pointer to a new connection object.
89  */
91 
92 /**
93  * Free a connection object.
94  *
95  * When a connection object is freed, all ::pn_session_t, ::pn_link_t,
96  * and ::pn_delivery_t objects associated with the connection are also
97  * freed.
98  *
99  * @param[in] connection the connection object to free (or NULL)
100  */
102 
103 /**
104  * Release a connection object.
105  *
106  * When a connection object is released, all ::pn_session_t and
107  * ::pn_link_t, objects associated with the connection are also
108  * released and all ::pn_delivery_t objects are settled.
109  *
110  * @param[in] connection the connection object to be released
111  */
113 
114 /**
115  * Get additional error information associated with the connection.
116  *
117  * Whenever a connection operation fails (i.e. returns an error code),
118  * additional error details can be obtained using this function. The
119  * error object that is returned may also be used to clear the error
120  * condition.
121  *
122  * The pointer returned by this operation is valid until the
123  * connection object is freed.
124  *
125  * @param[in] connection the connection object
126  * @return the connection's error object
127  */
129 
130 /**
131  * Associate a connection object with an event collector.
132  *
133  * By associating a connection object with an event collector, key
134  * changes in endpoint state are reported to the collector via
135  * ::pn_event_t objects that can be inspected and processed. See
136  * ::pn_event_t for more details on the kinds of events.
137  *
138  * Note that by registering a collector, the user is requesting that
139  * an indefinite number of events be queued up on his behalf. This
140  * means that unless the application eventually processes these
141  * events, the storage requirements for keeping them will grow without
142  * bound. In other words, don't register a collector with a connection
143  * if you never intend to process any of the events.
144  *
145  * @param[in] connection the connection object
146  * @param[in] collector the event collector
147  */
148 PN_EXTERN void pn_connection_collect(pn_connection_t *connection, pn_collector_t *collector);
149 
150 /**
151  * @deprecated
152  * Get the application context that is associated with a connection
153  * object.
154  *
155  * The application context for a connection may be set using
156  * ::pn_connection_set_context.
157  *
158  * @param[in] connection the connection whose context is to be returned.
159  * @return the application context for the connection object
160  */
162 
163 /**
164  * @deprecated
165  * Set a new application context for a connection object.
166  *
167  * The application context for a connection object may be retrieved
168  * using ::pn_connection_get_context.
169  *
170  * @param[in] connection the connection object
171  * @param[in] context the application context
172  */
173 PN_EXTERN void pn_connection_set_context(pn_connection_t *connection, void *context);
174 
175 /**
176  * Get the attachments that are associated with a connection object.
177  *
178  * @param[in] connection the connection whose attachments are to be returned.
179  * @return the attachments for the connection object
180  */
182 
183 /**
184  * Get the endpoint state flags for a connection.
185  *
186  * @param[in] connection the connection
187  * @return the connection's state flags
188  */
190 
191 /**
192  * Open a connection.
193  *
194  * Once this operation has completed, the PN_LOCAL_ACTIVE state flag
195  * will be set.
196  *
197  * @param[in] connection a connection object
198  */
200 
201 /**
202  * Close a connection.
203  *
204  * Once this operation has completed, the PN_LOCAL_CLOSED state flag
205  * will be set. This may be called without calling
206  * ::pn_connection_open, in this case it is equivalent to calling
207  * ::pn_connection_open followed by ::pn_connection_close.
208  *
209  * @param[in] connection a connection object
210  */
212 
213 /**
214  * Reset a connection object back to the uninitialized state.
215  *
216  * Note that this does *not* remove any contained ::pn_session_t,
217  * ::pn_link_t, and ::pn_delivery_t objects.
218  *
219  * @param[in] connection a connection object
220  */
222 
223 /**
224  * Get the local condition associated with the connection endpoint.
225  *
226  * The ::pn_condition_t object retrieved may be modified prior to
227  * closing the connection in order to indicate a particular condition
228  * exists when the connection closes. This is normally used to
229  * communicate error conditions to the remote peer, however it may
230  * also be used in non error cases such as redirects. See
231  * ::pn_condition_t for more details.
232  *
233  * The pointer returned by this operation is valid until the
234  * connection object is freed.
235  *
236  * @param[in] connection the connection object
237  * @return the connection's local condition object
238  */
240 
241 /**
242  * Get the remote condition associated with the connection endpoint.
243  *
244  * The ::pn_condition_t object retrieved may be examined in order to
245  * determine whether the remote peer was indicating some sort of
246  * exceptional condition when the remote connection endpoint was
247  * closed. The ::pn_condition_t object returned may not be modified.
248  *
249  * The pointer returned by this operation is valid until the
250  * connection object is freed.
251  *
252  * @param[in] connection the connection object
253  * @return the connection's remote condition object
254  */
256 
257 /**
258  * Get the AMQP Container name advertised by a connection object.
259  *
260  * The pointer returned by this operation is valid until
261  * ::pn_connection_set_container 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 container name
266  */
267 PN_EXTERN const char *pn_connection_get_container(pn_connection_t *connection);
268 
269 /**
270  * Set the AMQP Container name advertised by a connection object.
271  *
272  * @param[in] connection the connection object
273  * @param[in] container the container name
274  */
275 PN_EXTERN void pn_connection_set_container(pn_connection_t *connection, const char *container);
276 
277 /**
278  * Set the authentication username for a client connection
279  *
280  * It is necessary to set the username and password before binding the connection
281  * to a trasnport and it isn't allowed to change them after the binding.
282  *
283  * If not set then no authentication will be negotiated unless the client
284  * sasl layer is explicitly created (this would be for sometting like Kerberos
285  * where the credentials are implicit in the environment, or to explicitly use
286  * the ANONYMOUS SASL mechanism)
287  *
288  * @param[in] connection the connection
289  * @param[in] user the username
290  */
291 PN_EXTERN void pn_connection_set_user(pn_connection_t *connection, const char *user);
292 
293 /**
294  * Set the authentication password for a client connection
295  *
296  * It is necessary to set the username and password before binding the connection
297  * to a trasnport and it isn't allowed to change them after the binding.
298  *
299  * Note that the password is write only and has no accessor as the underlying
300  * implementation should be zeroing the password after use to avoid the password
301  * being present in memory longer than necessary
302  *
303  * @param[in] connection the connection
304  * @param[in] password the password corresponding to the username - this will be copied and zeroed out after use
305  */
306 PN_EXTERN void pn_connection_set_password(pn_connection_t *connection, const char *password);
307 
308 /**
309  * Get the authentication username for a client connection
310  *
311  * @param[in] connection the connection
312  * @return the username passed into the connection
313  */
314 PN_EXTERN const char *pn_connection_get_user(pn_connection_t *connection);
315 
316 /**
317  * Get the value of the AMQP Hostname used by a connection object.
318  *
319  * The pointer returned by this operation is valid until
320  * ::pn_connection_set_hostname is called, or until the connection
321  * object is freed, whichever happens sooner.
322  *
323  * @param[in] connection the connection object
324  * @return a pointer to the hostname
325  */
326 PN_EXTERN const char *pn_connection_get_hostname(pn_connection_t *connection);
327 
328 /**
329  * Set the name of the virtual host (either fully qualified or relative) to
330  * which this connection is connecting to. This information may be used by the
331  * remote peer to determine the correct back-end service to connect the client
332  * to. This value will be sent in the Open performative, and will be used by
333  * SSL and SASL layers to identify the peer.
334  *
335  * @note Note: the virtual host string is passed verbatim, it is not parsed as
336  * a URL or modified in any way. It should not contain numeric IP addresses or
337  * port numbers unless that is what you intend to send as the virtual host name
338  * @param[in] connection the connection object
339  * @param[in] hostname the virtual host name
340  */
341 PN_EXTERN void pn_connection_set_hostname(pn_connection_t *connection, const char *hostname);
342 
343 /**
344  * Get the AMQP Container name advertised by the remote connection
345  * endpoint.
346  *
347  * This will return NULL until the ::PN_REMOTE_ACTIVE state is
348  * reached. See ::pn_state_t for more details on endpoint state.
349  *
350  * Any non null pointer returned by this operation will be valid until
351  * the connection object is unbound from a transport or freed,
352  * whichever happens sooner.
353  *
354  * @param[in] connection the connection object
355  * @return a pointer to the remote container name
356  */
358 
359 /**
360  * Get the AMQP Hostname set by the remote connection endpoint.
361  *
362  * This will return NULL until the ::PN_REMOTE_ACTIVE state is
363  * reached. See ::pn_state_t for more details on endpoint state.
364  *
365  * Any non null pointer returned by this operation will be valid until
366  * the connection object is unbound from a transport or freed,
367  * whichever happens sooner.
368  *
369  * @param[in] connection the connection object
370  * @return a pointer to the remote hostname
371  */
373 
374 /**
375  * Access/modify the AMQP offered capabilities data for a connection
376  * object.
377  *
378  * This operation will return a pointer to a ::pn_data_t object that
379  * is valid until the connection object is freed. Any data contained
380  * by the ::pn_data_t object will be sent as the offered capabilites
381  * for the parent connection object. Note that this MUST take the form
382  * of an array of symbols to be valid.
383  *
384  * The ::pn_data_t pointer returned is valid until the connection
385  * object is freed.
386  *
387  * @param[in] connection the connection object
388  * @return a pointer to a pn_data_t representing the offered capabilities
389  */
391 
392 /**
393  * Access/modify the AMQP desired capabilities data for a connection
394  * object.
395  *
396  * This operation will return a pointer to a ::pn_data_t object that
397  * is valid until the connection object is freed. Any data contained
398  * by the ::pn_data_t object will be sent as the desired capabilites
399  * for the parent connection object. Note that this MUST take the form
400  * of an array of symbols to be valid.
401  *
402  * The ::pn_data_t pointer returned is valid until the connection
403  * object is freed.
404  *
405  * @param[in] connection the connection object
406  * @return a pointer to a pn_data_t representing the desired capabilities
407  */
409 
410 /**
411  * Access/modify the AMQP properties data for a connection object.
412  *
413  * This operation will return a pointer to a ::pn_data_t object that
414  * is valid until the connection object is freed. Any data contained
415  * by the ::pn_data_t object will be sent as the AMQP properties for
416  * the parent connection object. Note that this MUST take the form of
417  * a symbol keyed map to be valid.
418  *
419  * The ::pn_data_t pointer returned is valid until the connection
420  * object is freed.
421  *
422  * @param[in] connection the connection object
423  * @return a pointer to a pn_data_t representing the connection properties
424  */
426 
427 /**
428  * Access the AMQP offered capabilites supplied by the remote
429  * connection endpoint.
430  *
431  * This operation will return a pointer to a ::pn_data_t object that
432  * is valid until the connection object is freed. This data object
433  * will be empty until the remote connection is opened as indicated by
434  * the ::PN_REMOTE_ACTIVE flag.
435  *
436  * @param[in] connection the connection object
437  * @return the remote offered capabilities
438  */
440 
441 /**
442  * Access the AMQP desired capabilites supplied by the remote
443  * connection endpoint.
444  *
445  * This operation will return a pointer to a ::pn_data_t object that
446  * is valid until the connection object is freed. This data object
447  * will be empty until the remote connection is opened as indicated by
448  * the ::PN_REMOTE_ACTIVE flag.
449  *
450  * @param[in] connection the connection object
451  * @return the remote desired capabilities
452  */
454 
455 /**
456  * Access the AMQP connection properties supplied by the remote
457  * connection endpoint.
458  *
459  * This operation will return a pointer to a ::pn_data_t object that
460  * is valid until the connection object is freed. This data object
461  * will be empty until the remote connection is opened as indicated by
462  * the ::PN_REMOTE_ACTIVE flag.
463  *
464  * @param[in] connection the connection object
465  * @return the remote connection properties
466  */
468 
469 /**
470  * Get the transport bound to a connection object.
471  *
472  * If the connection is unbound, then this operation will return NULL.
473  *
474  * @param[in] connection the connection object
475  * @return the transport bound to a connection, or NULL if the
476  * connection is unbound
477  */
479 
480 /** @}
481  */
482 
483 #ifdef __cplusplus
484 }
485 #endif
486 
487 #endif /* connection.h */
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 pn_connection_t * pn_connection(void)
Factory to construct a new Connection.
PN_EXTERN const char * pn_connection_get_user(pn_connection_t *connection)
Get the authentication username for a client connection.
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 void pn_connection_release(pn_connection_t *connection)
Release a connection object.
struct pn_record_t pn_record_t
Definition: object.h:46
struct pn_transport_t pn_transport_t
An AMQP Transport object.
Definition: types.h:262
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_set_hostname(pn_connection_t *connection, const char *hostname)
Set the name of the virtual host (either fully qualified or relative) to which this connection is con...
PN_EXTERN void pn_connection_set_password(pn_connection_t *connection, const char *password)
Set the authentication password for a client connection.
Data API for proton.
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_collect(pn_connection_t *connection, pn_collector_t *collector)
Associate a connection object with an event collector.
PN_EXTERN void pn_connection_free(pn_connection_t *connection)
Free a connection object.
PN_EXTERN const char * pn_connection_get_container(pn_connection_t *connection)
Get the AMQP Container name advertised by a connection object.
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)
struct pn_collector_t pn_collector_t
An event collector.
Definition: types.h:250
PN_EXTERN void pn_connection_set_container(pn_connection_t *connection, const char *container)
Set the AMQP Container name advertised by a connection object.
The Condition API for the proton Engine.
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 const char * pn_connection_get_hostname(pn_connection_t *connection)
Get the value of the AMQP Hostname used by a connection object.
PN_EXTERN pn_condition_t * pn_connection_condition(pn_connection_t *connection)
Get the local condition associated with the connection endpoint.
struct pn_data_t pn_data_t
An AMQP Data object.
Definition: codec.h:358
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 pn_data_t * pn_connection_remote_offered_capabilities(pn_connection_t *connection)
Access the AMQP offered capabilites supplied by the remote connection endpoint.
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 pn_record_t * pn_connection_attachments(pn_connection_t *connection)
Get the attachments that are associated with a connection object.
PN_EXTERN pn_data_t * pn_connection_properties(pn_connection_t *connection)
Access/modify the AMQP properties data for a connection object.
struct pn_error_t pn_error_t
A pn_error_t has an int error code and some string text to describe the error.
Definition: error.h:33
PN_EXTERN pn_state_t pn_connection_state(pn_connection_t *connection)
Get the endpoint state flags for a connection.
struct pn_connection_t pn_connection_t
An AMQP Connection object.
Definition: types.h:118
struct pn_condition_t pn_condition_t
An AMQP Condition object.
Definition: condition.h:64
PN_EXTERN void pn_connection_open(pn_connection_t *connection)
Open a connection.
int pn_state_t
Holds the state flags for an AMQP endpoint.
Definition: types.h:103
PN_EXTERN void pn_connection_close(pn_connection_t *connection)
Close a connection.
PN_EXTERN void pn_connection_set_context(pn_connection_t *connection, void *context)
PN_EXTERN void pn_connection_set_user(pn_connection_t *connection, const char *user)
Set the authentication username for a client connection.
PN_EXTERN pn_error_t * pn_connection_error(pn_connection_t *connection)
Get additional error information associated with the connection.