event.h
Go to the documentation of this file.
#ifndef PROTON_EVENT_H
#define PROTON_EVENT_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/object.h>
#include <stddef.h>
#ifdef __cplusplus
extern "C" {
#endif
/**
* @file
*
* Event API for the proton Engine.
*
* @defgroup event Event
* @ingroup engine
* @{
*/
/**
* An event provides notification of a state change within the
* protocol engine's object model.
*
* The AMQP endpoint state modeled by the protocol engine is captured
* by the following object types: @link pn_delivery_t Deliveries
* @endlink, @link pn_link_t Links @endlink, @link pn_session_t
* Sessions @endlink, @link pn_connection_t Connections @endlink, and
* @link pn_transport_t Transports @endlink. These objects are related
* as follows:
*
* - @link pn_delivery_t Deliveries @endlink always have a single
* parent Link
* - @link pn_link_t Links @endlink always have a single parent
* Session
* - @link pn_session_t Sessions @endlink always have a single parent
* Connection
* - @link pn_connection_t Connections @endlink optionally have at
* most one associated Transport
* - @link pn_transport_t Transports @endlink optionally have at most
* one associated Connection
*
* Every event has a type (see ::pn_event_type_t) that identifies what
* sort of state change has occurred along with a pointer to the
* object whose state has changed (as well as its associated objects).
*
* Events are accessed by creating a @link pn_collector_t Collector
* @endlink with ::pn_collector() and registering it with the @link
* pn_connection_t Connection @endlink of interest through use of
* ::pn_connection_collect(). Once a collector has been registered,
* ::pn_collector_peek() and ::pn_collector_pop() are used to access
* and process events.
*/
typedef struct pn_event_t pn_event_t;
/**
* An event type.
*/
typedef enum {
/**
* Defined as a programming convenience. No event of this type will
* ever be generated.
*/
PN_EVENT_NONE = 0,
/**
* A reactor has been started. Events of this type point to the reactor.
*/
PN_REACTOR_INIT,
/**
* A reactor has no more events to process. Events of this type
* point to the reactor.
*/
PN_REACTOR_QUIESCED,
/**
* A reactor has been stopped. Events of this type point to the reactor.
*/
PN_REACTOR_FINAL,
/**
* A timer event has occurred.
*/
PN_TIMER_TASK,
/**
* The connection has been created. This is the first event that
* will ever be issued for a connection. Events of this type point
* to the relevant connection.
*/
PN_CONNECTION_INIT,
/**
* The connection has been bound to a transport. This event is
* issued when the ::pn_transport_bind() operation is invoked.
*/
PN_CONNECTION_BOUND,
/**
* The connection has been unbound from its transport. This event is
* issued when the ::pn_transport_unbind() operation is invoked.
*/
PN_CONNECTION_UNBOUND,
/**
* The local connection endpoint has been closed. Events of this
* type point to the relevant connection.
*/
PN_CONNECTION_LOCAL_OPEN,
/**
* The remote endpoint has opened the connection. Events of this
* type point to the relevant connection.
*/
PN_CONNECTION_REMOTE_OPEN,
/**
* The local connection endpoint has been closed. Events of this
* type point to the relevant connection.
*/
PN_CONNECTION_LOCAL_CLOSE,
/**
* The remote endpoint has closed the connection. Events of this
* type point to the relevant connection.
*/
PN_CONNECTION_REMOTE_CLOSE,
/**
* The connection has been freed and any outstanding processing has
* been completed. This is the final event that will ever be issued
* for a connection.
*/
PN_CONNECTION_FINAL,
/**
* The session has been created. This is the first event that will
* ever be issued for a session.
*/
PN_SESSION_INIT,
/**
* The local session endpoint has been opened. Events of this type
* point ot the relevant session.
*/
PN_SESSION_LOCAL_OPEN,
/**
* The remote endpoint has opened the session. Events of this type
* point to the relevant session.
*/
PN_SESSION_REMOTE_OPEN,
/**
* The local session endpoint has been closed. Events of this type
* point ot the relevant session.
*/
PN_SESSION_LOCAL_CLOSE,
/**
* The remote endpoint has closed the session. Events of this type
* point to the relevant session.
*/
PN_SESSION_REMOTE_CLOSE,
/**
* The session has been freed and any outstanding processing has
* been completed. This is the final event that will ever be issued
* for a session.
*/
PN_SESSION_FINAL,
/**
* The link has been created. This is the first event that will ever
* be issued for a link.
*/
PN_LINK_INIT,
/**
* The local link endpoint has been opened. Events of this type
* point ot the relevant link.
*/
PN_LINK_LOCAL_OPEN,
/**
* The remote endpoint has opened the link. Events of this type
* point to the relevant link.
*/
PN_LINK_REMOTE_OPEN,
/**
* The local link endpoint has been closed. Events of this type
* point ot the relevant link.
*/
PN_LINK_LOCAL_CLOSE,
/**
* The remote endpoint has closed the link. Events of this type
* point to the relevant link.
*/
PN_LINK_REMOTE_CLOSE,
/**
* The local link endpoint has been detached. Events of this type
* point to the relevant link.
*/
PN_LINK_LOCAL_DETACH,
/**
* The remote endpoint has detached the link. Events of this type
* point to the relevant link.
*/
PN_LINK_REMOTE_DETACH,
/**
* The flow control state for a link has changed. Events of this
* type point to the relevant link.
*/
PN_LINK_FLOW,
/**
* The link has been freed and any outstanding processing has been
* completed. This is the final event that will ever be issued for a
* link. Events of this type point to the relevant link.
*/
PN_LINK_FINAL,
/**
* A delivery has been created or updated. Events of this type point
* to the relevant delivery.
*/
PN_DELIVERY,
/**
* The transport has new data to read and/or write. Events of this
* type point to the relevant transport.
*/
PN_TRANSPORT,
/**
* The transport has authenticated, if this is received by a server
* the associated transport has authenticated an incoming connection
* and pn_transport_get_user() can be used to obtain the authenticated
* user.
*/
PN_TRANSPORT_AUTHENTICATED,
/**
* Indicates that a transport error has occurred. Use
* ::pn_transport_condition() to access the details of the error
* from the associated transport.
*/
PN_TRANSPORT_ERROR,
/**
* Indicates that the head of the transport has been closed. This
* means the transport will never produce more bytes for output to
* the network. Events of this type point to the relevant transport.
*/
PN_TRANSPORT_HEAD_CLOSED,
/**
* Indicates that the tail of the transport has been closed. This
* means the transport will never be able to process more bytes from
* the network. Events of this type point to the relevant transport.
*/
PN_TRANSPORT_TAIL_CLOSED,
/**
* Indicates that the both the head and tail of the transport are
* closed. Events of this type point to the relevant transport.
*/
PN_TRANSPORT_CLOSED,
PN_SELECTABLE_INIT,
PN_SELECTABLE_UPDATED,
PN_SELECTABLE_READABLE,
PN_SELECTABLE_WRITABLE,
PN_SELECTABLE_ERROR,
PN_SELECTABLE_EXPIRED,
PN_SELECTABLE_FINAL
} pn_event_type_t;
/**
* Get a human readable name for an event type.
*
* @param[in] type an event type
* @return a human readable name
*/
PN_EXTERN const char *pn_event_type_name(pn_event_type_t type);
/**
* Construct a collector.
*
* A collector is used to register interest in events produced by one
* or more ::pn_connection_t objects. Collectors are not currently
* thread safe, so synchronization must be used if they are to be
* shared between multiple connection objects.
*/
PN_EXTERN pn_collector_t *pn_collector(void);
/**
* Free a collector.
*
* @param[in] collector a collector to free, or NULL
*/
PN_EXTERN void pn_collector_free(pn_collector_t *collector);
/**
* Release a collector. Once in a released state a collector will
* drain any internally queued events (thereby releasing any pointers
* they may hold), shrink it's memory footprint to a minimum, and
* discard any newly created events.
*
* @param[in] collector a collector object
*/
PN_EXTERN void pn_collector_release(pn_collector_t *collector);
/**
* Place a new event on a collector.
*
* This operation will create a new event of the given type and
* context and return a pointer to the newly created event. In some
* cases an event of the given type and context can be elided. When
* this happens, this operation will return a NULL pointer.
*
* @param[in] collector a collector object
* @param[in] type the event type
* @param[in] context the event context
*
* @return a pointer to the newly created event or NULL if the event
* was elided
*/
PN_EXTERN pn_event_t *pn_collector_put(pn_collector_t *collector,
const pn_class_t *clazz, void *context,
pn_event_type_t type);
/**
* Access the head event contained by a collector.
*
* This operation will continue to return the same event until it is
* cleared by using ::pn_collector_pop. The pointer return by this
* operation will be valid until ::pn_collector_pop is invoked or
* ::pn_collector_free is called, whichever happens sooner.
*
* @param[in] collector a collector object
* @return a pointer to the head event contained in the collector
*/
PN_EXTERN pn_event_t *pn_collector_peek(pn_collector_t *collector);
/**
* Clear the head event on a collector.
*
* @param[in] collector a collector object
* @return true if the event was popped, false if the collector is empty
*/
PN_EXTERN bool pn_collector_pop(pn_collector_t *collector);
/**
* Check if there are more events after the current event. If this
* returns true, then pn_collector_peek() will return an event even
* after pn_collector_pop() is called.
*
* @param[in] collector a collector object
* @return true if the collector has more than the current event
*/
PN_EXTERN bool pn_collector_more(pn_collector_t *collector);
/**
* Get the type of an event.
*
* @param[in] event an event object
* @return the type of the event
*/
PN_EXTERN pn_event_type_t pn_event_type(pn_event_t *event);
/**
* Get the class associated with the event context.
*
* @param[in] event an event object
* @return the class associated with the event context
*/
PN_EXTERN const pn_class_t *pn_event_class(pn_event_t *event);
/**
* Get the context associated with an event.
*/
PN_EXTERN void *pn_event_context(pn_event_t *event);
/**
* Get the connection associated with an event.
*
* @param[in] event an event object
* @return the connection associated with the event (or NULL)
*/
PN_EXTERN pn_connection_t *pn_event_connection(pn_event_t *event);
/**
* Get the session associated with an event.
*
* @param[in] event an event object
* @return the session associated with the event (or NULL)
*/
PN_EXTERN pn_session_t *pn_event_session(pn_event_t *event);
/**
* Get the link associated with an event.
*
* @param[in] event an event object
* @return the link associated with the event (or NULL)
*/
PN_EXTERN pn_link_t *pn_event_link(pn_event_t *event);
/**
* Get the delivery associated with an event.
*
* @param[in] event an event object
* @return the delivery associated with the event (or NULL)
*/
PN_EXTERN pn_delivery_t *pn_event_delivery(pn_event_t *event);
/**
* Get the transport associated with an event.
*
* @param[in] event an event object
* @return the transport associated with the event (or NULL)
*/
PN_EXTERN pn_transport_t *pn_event_transport(pn_event_t *event);
/**
* Get any attachments associated with an event.
*
* @param[in] event an event object
* @return the record holding the attachments
*/
PN_EXTERN pn_record_t *pn_event_attachments(pn_event_t *event);
#ifdef __cplusplus
}
#endif
/** @}
*/
#endif /* event.h */
import_export.h
PN_SESSION_REMOTE_CLOSE
The remote endpoint has closed the session.
Definition: event.h:188
PN_CONNECTION_BOUND
The connection has been bound to a transport.
Definition: event.h:121
type_compat.h
PN_DELIVERY
A delivery has been created or updated.
Definition: event.h:256
PN_LINK_LOCAL_DETACH
The local link endpoint has been detached.
Definition: event.h:231
pn_event_transport
PN_EXTERN pn_transport_t * pn_event_transport(pn_event_t *event)
Get the transport associated with an event.
pn_event_context
PN_EXTERN void * pn_event_context(pn_event_t *event)
Get the context associated with an event.
PN_SESSION_LOCAL_CLOSE
The local session endpoint has been closed.
Definition: event.h:182
pn_collector_release
PN_EXTERN void pn_collector_release(pn_collector_t *collector)
Release a collector.
PN_SELECTABLE_ERROR
Definition: event.h:303
PN_CONNECTION_LOCAL_OPEN
The local connection endpoint has been closed.
Definition: event.h:133
pn_connection_t
struct pn_connection_t pn_connection_t
An AMQP Connection object.
Definition: types.h:111
PN_TRANSPORT
The transport has new data to read and/or write.
Definition: event.h:262
PN_REACTOR_INIT
A reactor has been started.
Definition: event.h:92
pn_delivery_t
struct pn_delivery_t pn_delivery_t
An AMQP Delivery object.
Definition: types.h:231
PN_SELECTABLE_INIT
Definition: event.h:299
PN_SELECTABLE_WRITABLE
Definition: event.h:302
pn_event_attachments
PN_EXTERN pn_record_t * pn_event_attachments(pn_event_t *event)
Get any attachments associated with an event.
PN_CONNECTION_LOCAL_CLOSE
The local connection endpoint has been closed.
Definition: event.h:145
PN_LINK_LOCAL_OPEN
The local link endpoint has been opened.
Definition: event.h:207
pn_event_t
struct pn_event_t pn_event_t
An event provides notification of a state change within the protocol engine&#39;s object model...
Definition: event.h:77
pn_collector_put
PN_EXTERN pn_event_t * pn_collector_put(pn_collector_t *collector, const pn_class_t *clazz, void *context, pn_event_type_t type)
Place a new event on a collector.
PN_LINK_REMOTE_OPEN
The remote endpoint has opened the link.
Definition: event.h:213
pn_event_type_t
pn_event_type_t
An event type.
Definition: event.h:82
pn_class_t
Definition: object.h:48
PN_REACTOR_FINAL
A reactor has been stopped.
Definition: event.h:103
pn_collector_t
struct pn_collector_t pn_collector_t
An event collector.
Definition: types.h:243
PN_SELECTABLE_EXPIRED
Definition: event.h:304
PN_LINK_LOCAL_CLOSE
The local link endpoint has been closed.
Definition: event.h:219
pn_link_t
struct pn_link_t pn_link_t
An AMQP Link object.
Definition: types.h:141
PN_LINK_REMOTE_DETACH
The remote endpoint has detached the link.
Definition: event.h:237
PN_LINK_REMOTE_CLOSE
The remote endpoint has closed the link.
Definition: event.h:225
PN_SELECTABLE_UPDATED
Definition: event.h:300
PN_SESSION_INIT
The session has been created.
Definition: event.h:164
PN_EVENT_NONE
Defined as a programming convenience.
Definition: event.h:87
PN_LINK_FLOW
The flow control state for a link has changed.
Definition: event.h:243
pn_collector
PN_EXTERN pn_collector_t * pn_collector(void)
Construct a collector.
PN_SESSION_FINAL
The session has been freed and any outstanding processing has been completed.
Definition: event.h:195
PN_LINK_FINAL
The link has been freed and any outstanding processing has been completed.
Definition: event.h:250
pn_collector_free
PN_EXTERN void pn_collector_free(pn_collector_t *collector)
Free a collector.
PN_CONNECTION_REMOTE_OPEN
The remote endpoint has opened the connection.
Definition: event.h:139
pn_event_delivery
PN_EXTERN pn_delivery_t * pn_event_delivery(pn_event_t *event)
Get the delivery associated with an event.
PN_SESSION_LOCAL_OPEN
The local session endpoint has been opened.
Definition: event.h:170
pn_event_type_name
PN_EXTERN const char * pn_event_type_name(pn_event_type_t type)
Get a human readable name for an event type.
pn_collector_more
PN_EXTERN bool pn_collector_more(pn_collector_t *collector)
Check if there are more events after the current event.
pn_event_link
PN_EXTERN pn_link_t * pn_event_link(pn_event_t *event)
Get the link associated with an event.
PN_TIMER_TASK
A timer event has occurred.
Definition: event.h:108
PN_CONNECTION_INIT
The connection has been created.
Definition: event.h:115
PN_TRANSPORT_HEAD_CLOSED
Indicates that the head of the transport has been closed.
Definition: event.h:284
PN_CONNECTION_FINAL
The connection has been freed and any outstanding processing has been completed.
Definition: event.h:158
PN_SELECTABLE_FINAL
Definition: event.h:305
pn_event_class
PN_EXTERN const pn_class_t * pn_event_class(pn_event_t *event)
Get the class associated with the event context.
pn_record_t
struct pn_record_t pn_record_t
Definition: object.h:46
PN_LINK_INIT
The link has been created.
Definition: event.h:201
PN_CONNECTION_REMOTE_CLOSE
The remote endpoint has closed the connection.
Definition: event.h:151
pn_event_session
PN_EXTERN pn_session_t * pn_event_session(pn_event_t *event)
Get the session associated with an event.
pn_event_type
PN_EXTERN pn_event_type_t pn_event_type(pn_event_t *event)
Get the type of an event.
pn_session_t
struct pn_session_t pn_session_t
An AMQP Session object.
Definition: types.h:122
pn_collector_peek
PN_EXTERN pn_event_t * pn_collector_peek(pn_collector_t *collector)
Access the head event contained by a collector.
PN_REACTOR_QUIESCED
A reactor has no more events to process.
Definition: event.h:98
PN_SELECTABLE_READABLE
Definition: event.h:301
PN_EXTERN
#define PN_EXTERN
Definition: import_export.h:53
pn_event_connection
PN_EXTERN pn_connection_t * pn_event_connection(pn_event_t *event)
Get the connection associated with an event.
object.h
PN_TRANSPORT_AUTHENTICATED
The transport has authenticated, if this is received by a server the associated transport has authent...
Definition: event.h:270
PN_SESSION_REMOTE_OPEN
The remote endpoint has opened the session.
Definition: event.h:176
pn_collector_pop
PN_EXTERN bool pn_collector_pop(pn_collector_t *collector)
Clear the head event on a collector.
PN_TRANSPORT_CLOSED
Indicates that the both the head and tail of the transport are closed.
Definition: event.h:297
PN_TRANSPORT_ERROR
Indicates that a transport error has occurred.
Definition: event.h:277
PN_CONNECTION_UNBOUND
The connection has been unbound from its transport.
Definition: event.h:127
pn_transport_t
struct pn_transport_t pn_transport_t
An AMQP Transport object.
Definition: types.h:255
PN_TRANSPORT_TAIL_CLOSED
Indicates that the tail of the transport has been closed.
Definition: event.h:291