session.h
Go to the documentation of this file.
#ifndef PROTON_SESSION_H
#define PROTON_SESSION_H 1
/*
*
* Licensed to the Apache Software Foundation (ASF) under one
* or more contributor license agreements. See the NOTICE file
* distributed with this work for additional information
* regarding copyright ownership. The ASF licenses this file
* to you under the Apache License, Version 2.0 (the
* "License"); you may not use this file except in compliance
* with the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing,
* software distributed under the License is distributed on an
* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
* KIND, either express or implied. See the License for the
* specific language governing permissions and limitations
* under the License.
*
*/
#include <proton/import_export.h>
#include <proton/type_compat.h>
#include <proton/types.h>
#include <proton/object.h>
#include <proton/error.h>
#include <proton/condition.h>
#include <stddef.h>
#ifdef __cplusplus
extern "C" {
#endif
/** @file
* Session API for the proton Engine.
*
* @defgroup session Session
* @ingroup engine
* @{
*/
/**
* Factory for creating a new session on a given connection object.
*
* Creates a new session object and adds it to the set of sessions
* maintained by the connection object.
*
* @param[in] connection the connection object
* @return a pointer to the new session
*/
PN_EXTERN pn_session_t *pn_session(pn_connection_t *connection);
/**
* Free a session object.
*
* When a session is freed it will no longer be retained by the
* connection once any internal references to the session are no
* longer needed. Freeing a session will free all links on that
* session and settle any deliveries on those links.
*
* @param[in] session a session object to free (or NULL)
*/
PN_EXTERN void pn_session_free(pn_session_t *session);
/**
* @deprecated
* Get the application context that is associated with a session
* object.
*
* The application context for a session may be set using
* ::pn_session_set_context.
*
* @param[in] session the session whose context is to be returned.
* @return the application context for the session object
*/
PN_EXTERN void *pn_session_get_context(pn_session_t *session);
/**
* @deprecated
* Set a new application context for a session object.
*
* The application context for a session object may be retrieved
* using ::pn_session_get_context.
*
* @param[in] session the session object
* @param[in] context the application context
*/
PN_EXTERN void pn_session_set_context(pn_session_t *session, void *context);
/**
* Get the attachments that are associated with a session object.
*
* @param[in] session the session whose attachments are to be returned.
* @return the attachments for the session object
*/
PN_EXTERN pn_record_t *pn_session_attachments(pn_session_t *session);
/**
* Get the endpoint state flags for a session.
*
* @param[in] session the session
* @return the session's state flags
*/
PN_EXTERN pn_state_t pn_session_state(pn_session_t *session);
/**
* Get additional error information associated with the session.
*
* Whenever a session operation fails (i.e. returns an error code),
* additional error details can be obtained using this function. The
* error object that is returned may also be used to clear the error
* condition.
*
* The pointer returned by this operation is valid until the
* session object is freed.
*
* @param[in] session the sesion object
* @return the session's error object
*/
PN_EXTERN pn_error_t *pn_session_error(pn_session_t *session);
/**
* Get the local condition associated with the session endpoint.
*
* The ::pn_condition_t object retrieved may be modified prior to
* closing the session in order to indicate a particular condition
* exists when the session closes. This is normally used to
* communicate error conditions to the remote peer, however it may
* also be used in non error cases. See ::pn_condition_t for more
* details.
*
* The pointer returned by this operation is valid until the session
* object is freed.
*
* @param[in] session the session object
* @return the session's local condition object
*/
PN_EXTERN pn_condition_t *pn_session_condition(pn_session_t *session);
/**
* Get the remote condition associated with the session endpoint.
*
* The ::pn_condition_t object retrieved may be examined in order to
* determine whether the remote peer was indicating some sort of
* exceptional condition when the remote session endpoint was
* closed. The ::pn_condition_t object returned may not be modified.
*
* The pointer returned by this operation is valid until the
* session object is freed.
*
* @param[in] session the session object
* @return the session's remote condition object
*/
PN_EXTERN pn_condition_t *pn_session_remote_condition(pn_session_t *session);
/**
* Get the parent connection for a session object.
*
* This operation retrieves the parent pn_connection_t object that
* contains the given pn_session_t object.
*
* @param[in] session the session object
* @return the parent connection object
*/
PN_EXTERN pn_connection_t *pn_session_connection(pn_session_t *session);
/**
* Open a session.
*
* Once this operation has completed, the PN_LOCAL_ACTIVE state flag
* will be set.
*
* @param[in] session a session object
*/
PN_EXTERN void pn_session_open(pn_session_t *session);
/**
* Close a session.
*
* Once this operation has completed, the PN_LOCAL_CLOSED state flag
* will be set. This may be called without calling
* ::pn_session_open, in this case it is equivalent to calling
* ::pn_session_open followed by ::pn_session_close.
*
* @param[in] session a session object
*/
PN_EXTERN void pn_session_close(pn_session_t *session);
/**
* Get the incoming capacity of the session measured in bytes.
*
* The incoming capacity of a session determines how much incoming
* message data the session will buffer. Note that if this value is
* less than the negotiated frame size of the transport, it will be
* rounded up to one full frame.
*
* @param[in] session the session object
* @return the incoming capacity of the session in bytes
*/
PN_EXTERN size_t pn_session_get_incoming_capacity(pn_session_t *session);
/**
* Set the incoming capacity for a session object.
*
* The incoming capacity of a session determines how much incoming
* message data the session will buffer. Note that if this value is
* less than the negotiated frame size of the transport, it will be
* rounded up to one full frame.
*
* @param[in] session the session object
* @param[in] capacity the incoming capacity for the session
*/
PN_EXTERN void pn_session_set_incoming_capacity(pn_session_t *session, size_t capacity);
/**
* Get the outgoing window for a session object.
*
* @param[in] session the session object
* @return the outgoing window for the session
*/
PN_EXTERN size_t pn_session_get_outgoing_window(pn_session_t *session);
/**
* Set the outgoing window for a session object.
*
* @param[in] session the session object
* @param[in] window the outgoing window for the session
*/
PN_EXTERN void pn_session_set_outgoing_window(pn_session_t *session, size_t window);
/**
* Get the number of outgoing bytes currently buffered by a session.
*
* @param[in] session a session object
* @return the number of outgoing bytes currently buffered
*/
PN_EXTERN size_t pn_session_outgoing_bytes(pn_session_t *session);
/**
* Get the number of incoming bytes currently buffered by a session.
*
* @param[in] session a session object
* @return the number of incoming bytes currently buffered
*/
PN_EXTERN size_t pn_session_incoming_bytes(pn_session_t *session);
/**
* Retrieve the first session from a given connection that matches the
* specified state mask.
*
* Examines the state of each session owned by the connection, and
* returns the first session that matches the given state mask. If
* state contains both local and remote flags, then an exact match
* against those flags is performed. If state contains only local or
* only remote flags, then a match occurs if any of the local or
* remote flags are set respectively.
*
* @param[in] connection to be searched for matching sessions
* @param[in] state mask to match
* @return the first session owned by the connection that matches the
* mask, else NULL if no sessions match
*/
PN_EXTERN pn_session_t *pn_session_head(pn_connection_t *connection, pn_state_t state);
/**
* Retrieve the next session from a given connection that matches the
* specified state mask.
*
* When used with ::pn_session_head, application can access all
* sessions on the connection that match the given state. See
* ::pn_session_head for description of match behavior.
*
* @param[in] session the previous session obtained from
* ::pn_session_head or ::pn_session_next
* @param[in] state mask to match.
* @return the next session owned by the connection that matches the
* mask, else NULL if no sessions match
*/
PN_EXTERN pn_session_t *pn_session_next(pn_session_t *session, pn_state_t state);
/** @}
*/
#ifdef __cplusplus
}
#endif
#endif /* session.h */
pn_session_state
PN_EXTERN pn_state_t pn_session_state(pn_session_t *session)
Get the endpoint state flags for a session.
types.h
pn_session_get_incoming_capacity
PN_EXTERN size_t pn_session_get_incoming_capacity(pn_session_t *session)
Get the incoming capacity of the session measured in bytes.
pn_session_close
PN_EXTERN void pn_session_close(pn_session_t *session)
Close a session.
pn_session_remote_condition
PN_EXTERN pn_condition_t * pn_session_remote_condition(pn_session_t *session)
Get the remote condition associated with the session endpoint.
import_export.h
pn_session_get_outgoing_window
PN_EXTERN size_t pn_session_get_outgoing_window(pn_session_t *session)
Get the outgoing window for a session object.
pn_record_t
struct pn_record_t pn_record_t
Definition: object.h:46
pn_session_free
PN_EXTERN void pn_session_free(pn_session_t *session)
Free a session object.
pn_session_set_incoming_capacity
PN_EXTERN void pn_session_set_incoming_capacity(pn_session_t *session, size_t capacity)
Set the incoming capacity for a session object.
pn_session_outgoing_bytes
PN_EXTERN size_t pn_session_outgoing_bytes(pn_session_t *session)
Get the number of outgoing bytes currently buffered by a session.
pn_session_set_outgoing_window
PN_EXTERN void pn_session_set_outgoing_window(pn_session_t *session, size_t window)
Set the outgoing window for a session object.
type_compat.h
PN_EXTERN
#define PN_EXTERN
Definition: import_export.h:53
pn_session_t
struct pn_session_t pn_session_t
An AMQP Session object.
Definition: types.h:129
error.h
pn_session_next
PN_EXTERN pn_session_t * pn_session_next(pn_session_t *session, pn_state_t state)
Retrieve the next session from a given connection that matches the specified state mask...
pn_session_error
PN_EXTERN pn_error_t * pn_session_error(pn_session_t *session)
Get additional error information associated with the session.
pn_session_incoming_bytes
PN_EXTERN size_t pn_session_incoming_bytes(pn_session_t *session)
Get the number of incoming bytes currently buffered by a session.
pn_session_condition
PN_EXTERN pn_condition_t * pn_session_condition(pn_session_t *session)
Get the local condition associated with the session endpoint.
pn_session_get_context
PN_EXTERN void * pn_session_get_context(pn_session_t *session)
condition.h
The Condition API for the proton Engine.
pn_session_open
PN_EXTERN void pn_session_open(pn_session_t *session)
Open a session.
pn_session_attachments
PN_EXTERN pn_record_t * pn_session_attachments(pn_session_t *session)
Get the attachments that are associated with a session object.
pn_session_set_context
PN_EXTERN void pn_session_set_context(pn_session_t *session, void *context)
object.h
pn_error_t
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_connection_t
struct pn_connection_t pn_connection_t
An AMQP Connection object.
Definition: types.h:118
pn_condition_t
struct pn_condition_t pn_condition_t
An AMQP Condition object.
Definition: condition.h:64
pn_session_connection
PN_EXTERN pn_connection_t * pn_session_connection(pn_session_t *session)
Get the parent connection for a session object.
pn_state_t
int pn_state_t
Holds the state flags for an AMQP endpoint.
Definition: types.h:103
pn_session_head
PN_EXTERN pn_session_t * pn_session_head(pn_connection_t *connection, pn_state_t state)
Retrieve the first session from a given connection that matches the specified state mask...
pn_session
PN_EXTERN pn_session_t * pn_session(pn_connection_t *connection)
Factory for creating a new session on a given connection object.