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
session.h
Go to the documentation of this file.
1
#ifndef PROTON_SESSION_H
2
#define PROTON_SESSION_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/type_compat.h
>
27
#include <stddef.h>
28
#include <sys/types.h>
29
30
#ifdef __cplusplus
31
extern
"C"
{
32
#endif
33
34
/** @file
35
* Session API for the proton Engine.
36
*
37
* @defgroup session Session
38
* @ingroup engine
39
* @{
40
*/
41
42
/**
43
* Factory for creating a new session on a given connection object.
44
*
45
* Creates a new session object and adds it to the set of sessions
46
* maintained by the connection object.
47
*
48
* @param[in] connection the connection object
49
* @return a pointer to the new session
50
*/
51
PN_EXTERN
pn_session_t
*
pn_session
(
pn_connection_t
*connection);
52
53
/**
54
* Free a session object.
55
*
56
* When a session object is freed, all ::pn_link_t, and
57
* ::pn_delivery_t objects associated with the session are also
58
* freed.
59
*
60
* @param[in] session a session object to free (or NULL)
61
*/
62
PN_EXTERN
void
pn_session_free
(
pn_session_t
*session);
63
64
/**
65
* Get the application context that is associated with a session
66
* object.
67
*
68
* The application context for a session may be set using
69
* ::pn_session_set_context.
70
*
71
* @param[in] session the session whose context is to be returned.
72
* @return the application context for the session object
73
*/
74
PN_EXTERN
void
*
pn_session_get_context
(
pn_session_t
*session);
75
76
/**
77
* Set a new application context for a session object.
78
*
79
* The application context for a session object may be retrieved
80
* using ::pn_session_get_context.
81
*
82
* @param[in] session the session object
83
* @param[in] context the application context
84
*/
85
PN_EXTERN
void
pn_session_set_context
(
pn_session_t
*session,
void
*context);
86
87
/**
88
* Get the endpoint state flags for a session.
89
*
90
* @param[in] session the session
91
* @return the session's state flags
92
*/
93
PN_EXTERN
pn_state_t
pn_session_state
(
pn_session_t
*session);
94
95
/**
96
* Get additional error information associated with the session.
97
*
98
* Whenever a session operation fails (i.e. returns an error code),
99
* additional error details can be obtained using this function. The
100
* error object that is returned may also be used to clear the error
101
* condition.
102
*
103
* The pointer returned by this operation is valid until the
104
* session object is freed.
105
*
106
* @param[in] session the sesion object
107
* @return the session's error object
108
*/
109
PN_EXTERN
pn_error_t
*
pn_session_error
(
pn_session_t
*session);
110
111
/**
112
* Get the local condition associated with the session endpoint.
113
*
114
* The ::pn_condition_t object retrieved may be modified prior to
115
* closing the session in order to indicate a particular condition
116
* exists when the session closes. This is normally used to
117
* communicate error conditions to the remote peer, however it may
118
* also be used in non error cases. See ::pn_condition_t for more
119
* details.
120
*
121
* The pointer returned by this operation is valid until the session
122
* object is freed.
123
*
124
* @param[in] session the session object
125
* @return the session's local condition object
126
*/
127
PN_EXTERN
pn_condition_t
*
pn_session_condition
(
pn_session_t
*session);
128
129
/**
130
* Get the remote condition associated with the session endpoint.
131
*
132
* The ::pn_condition_t object retrieved may be examined in order to
133
* determine whether the remote peer was indicating some sort of
134
* exceptional condition when the remote session endpoint was
135
* closed. The ::pn_condition_t object returned may not be modified.
136
*
137
* The pointer returned by this operation is valid until the
138
* session object is freed.
139
*
140
* @param[in] session the session object
141
* @return the session's remote condition object
142
*/
143
PN_EXTERN
pn_condition_t
*
pn_session_remote_condition
(
pn_session_t
*session);
144
145
/**
146
* Get the parent connection for a session object.
147
*
148
* This operation retrieves the parent pn_connection_t object that
149
* contains the given pn_session_t object.
150
*
151
* @param[in] session the session object
152
* @return the parent connection object
153
*/
154
PN_EXTERN
pn_connection_t
*
pn_session_connection
(
pn_session_t
*session);
155
156
/**
157
* Open a session.
158
*
159
* Once this operation has completed, the PN_LOCAL_ACTIVE state flag
160
* will be set.
161
*
162
* @param[in] session a session object
163
*/
164
PN_EXTERN
void
pn_session_open
(
pn_session_t
*session);
165
166
/**
167
* Close a session.
168
*
169
* Once this operation has completed, the PN_LOCAL_CLOSED state flag
170
* will be set. This may be called without calling
171
* ::pn_session_open, in this case it is equivalent to calling
172
* ::pn_session_open followed by ::pn_session_close.
173
*
174
* @param[in] session a session object
175
*/
176
PN_EXTERN
void
pn_session_close
(
pn_session_t
*session);
177
178
/**
179
* Get the incoming capacity of the session measured in bytes.
180
*
181
* The incoming capacity of a session determines how much incoming
182
* message data the session will buffer. Note that if this value is
183
* less than the negotiated frame size of the transport, it will be
184
* rounded up to one full frame.
185
*
186
* @param[in] session the session object
187
* @return the incoming capacity of the session in bytes
188
*/
189
PN_EXTERN
size_t
pn_session_get_incoming_capacity
(
pn_session_t
*session);
190
191
/**
192
* Set the incoming capacity for a session object.
193
*
194
* The incoming capacity of a session determines how much incoming
195
* message data the session will buffer. Note that if this value is
196
* less than the negotiated frame size of the transport, it will be
197
* rounded up to one full frame.
198
*
199
* @param[in] session the session object
200
* @param[in] capacity the incoming capacity for the session
201
*/
202
PN_EXTERN
void
pn_session_set_incoming_capacity
(
pn_session_t
*session,
size_t
capacity);
203
204
/**
205
* Get the number of outgoing bytes currently buffered by a session.
206
*
207
* @param[in] session a session object
208
* @return the number of outgoing bytes currently buffered
209
*/
210
PN_EXTERN
size_t
pn_session_outgoing_bytes
(
pn_session_t
*session);
211
212
/**
213
* Get the number of incoming bytes currently buffered by a session.
214
*
215
* @param[in] session a session object
216
* @return the number of incoming bytes currently buffered
217
*/
218
PN_EXTERN
size_t
pn_session_incoming_bytes
(
pn_session_t
*session);
219
220
/**
221
* Retrieve the first session from a given connection that matches the
222
* specified state mask.
223
*
224
* Examines the state of each session owned by the connection, and
225
* returns the first session that matches the given state mask. If
226
* state contains both local and remote flags, then an exact match
227
* against those flags is performed. If state contains only local or
228
* only remote flags, then a match occurs if any of the local or
229
* remote flags are set respectively.
230
*
231
* @param[in] connection to be searched for matching sessions
232
* @param[in] state mask to match
233
* @return the first session owned by the connection that matches the
234
* mask, else NULL if no sessions match
235
*/
236
PN_EXTERN
pn_session_t
*
pn_session_head
(
pn_connection_t
*connection,
pn_state_t
state);
237
238
/**
239
* Retrieve the next session from a given connection that matches the
240
* specified state mask.
241
*
242
* When used with ::pn_session_head, application can access all
243
* sessions on the connection that match the given state. See
244
* ::pn_session_head for description of match behavior.
245
*
246
* @param[in] session the previous session obtained from
247
* ::pn_session_head or ::pn_session_next
248
* @param[in] state mask to match.
249
* @return the next session owned by the connection that matches the
250
* mask, else NULL if no sessions match
251
*/
252
PN_EXTERN
pn_session_t
*
pn_session_next
(
pn_session_t
*session,
pn_state_t
state);
253
254
/** @}
255
*/
256
257
#ifdef __cplusplus
258
}
259
#endif
260
261
#endif
/* session.h */
Generated on Mon Jun 2 2014 22:59:05 for proton by
1.8.1.2