| #ifndef PROTON_ENGINE_H |
| #define PROTON_ENGINE_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 <stdbool.h> |
| #include <stddef.h> |
| #include <sys/types.h> |
| #include <proton/codec.h> |
| #include <proton/error.h> |
| |
| #ifdef __cplusplus |
| extern "C" { |
| #endif |
| |
| /** @file |
| * API for the proton Engine. |
| * |
| * @todo |
| */ |
| |
| typedef struct pn_transport_t pn_transport_t; |
| typedef struct pn_connection_t pn_connection_t; /**< Connection */ |
| typedef struct pn_session_t pn_session_t; /**< Session */ |
| typedef struct pn_link_t pn_link_t; /**< Link */ |
| typedef struct pn_terminus_t pn_terminus_t; |
| typedef enum { |
| PN_UNSPECIFIED = 0, |
| PN_SOURCE = 1, |
| PN_TARGET = 2, |
| PN_COORDINATOR = 3 |
| } pn_terminus_type_t; |
| typedef enum { |
| PN_NONDURABLE = 0, |
| PN_CONFIGURATION = 1, |
| PN_DELIVERIES = 2 |
| } pn_durability_t; |
| typedef enum { |
| PN_LINK_CLOSE, |
| PN_SESSION_CLOSE, |
| PN_CONNECTION_CLOSE, |
| PN_NEVER |
| } pn_expiry_policy_t; |
| typedef struct pn_delivery_t pn_delivery_t; |
| |
| typedef struct pn_delivery_tag_t { |
| size_t size; |
| const char *bytes; |
| } pn_delivery_tag_t; |
| |
| #define pn_dtag(BYTES, SIZE) ((pn_delivery_tag_t) {(SIZE), (BYTES)}) |
| |
| typedef int pn_state_t; /**< encodes the state of an endpoint */ |
| |
| #define PN_LOCAL_UNINIT (1) /**< local endpoint requires initialization */ |
| #define PN_LOCAL_ACTIVE (2) /**< local endpoint is active */ |
| #define PN_LOCAL_CLOSED (4) /**< local endpoint is closed */ |
| #define PN_REMOTE_UNINIT (8) /**< remote endpoint pending initialization by peer */ |
| #define PN_REMOTE_ACTIVE (16) /**< remote endpoint is active */ |
| #define PN_REMOTE_CLOSED (32) /**< remote endpoint has closed */ |
| |
| #define PN_LOCAL_MASK (PN_LOCAL_UNINIT | PN_LOCAL_ACTIVE | PN_LOCAL_CLOSED) |
| #define PN_REMOTE_MASK (PN_REMOTE_UNINIT | PN_REMOTE_ACTIVE | PN_REMOTE_CLOSED) |
| |
| /** @enum pn_disposition_t |
| * The state/outcome of a message transfer. |
| * |
| * @todo document each value |
| */ |
| typedef enum pn_disposition_t { |
| PN_RECEIVED=1, |
| PN_ACCEPTED=2, |
| PN_REJECTED=3, |
| PN_RELEASED=4, |
| PN_MODIFIED=5 |
| } pn_disposition_t; |
| |
| typedef int pn_trace_t; |
| |
| #define PN_TRACE_OFF (0) |
| #define PN_TRACE_RAW (1) |
| #define PN_TRACE_FRM (2) |
| #define PN_TRACE_DRV (4) |
| |
| #define PN_SESSION_WINDOW (1024) |
| |
| // connection |
| |
| /** Factory to construct a new Connection. |
| * |
| * @return pointer to a new connection object. |
| */ |
| pn_connection_t *pn_connection(void); |
| |
| /** Retrieve the state of the connection. |
| * |
| * @param[in] connection the connection |
| * @return the connection's state flags |
| */ |
| pn_state_t pn_connection_state(pn_connection_t *connection); |
| /** @todo: needs documentation */ |
| pn_error_t *pn_connection_error(pn_connection_t *connection); |
| /** @todo: needs documentation */ |
| const char *pn_connection_get_container(pn_connection_t *connection); |
| /** @todo: needs documentation */ |
| void pn_connection_set_container(pn_connection_t *connection, const char *container); |
| /** @todo: needs documentation */ |
| const char *pn_connection_get_hostname(pn_connection_t *connection); |
| /** @todo: needs documentation */ |
| void pn_connection_set_hostname(pn_connection_t *connection, const char *hostname); |
| const char *pn_connection_remote_container(pn_connection_t *connection); |
| const char *pn_connection_remote_hostname(pn_connection_t *connection); |
| pn_data_t *pn_connection_offered_capabilities(pn_connection_t *connection); |
| pn_data_t *pn_connection_desired_capabilities(pn_connection_t *connection); |
| pn_data_t *pn_connection_remote_offered_capabilities(pn_connection_t *connection); |
| pn_data_t *pn_connection_remote_desired_capabilities(pn_connection_t *connection); |
| |
| |
| /** Extracts the first delivery on the connection that has pending |
| * operations. |
| * |
| * Retrieves the first delivery on the Connection that has pending |
| * operations. A readable delivery indicates message data is waiting |
| * to be read. A writable delivery indicates that message data may be |
| * sent. An updated delivery indicates that the delivery's disposition |
| * has changed. A delivery will never be both readable and writible, |
| * but it may be both readable and updated or both writiable and |
| * updated. |
| * |
| * @param[in] connection the connection |
| * @return the first delivery object that needs to be serviced, else |
| * NULL if none |
| */ |
| pn_delivery_t *pn_work_head(pn_connection_t *connection); |
| |
| /** Get the next delivery on the connection that needs has pending |
| * operations. |
| * |
| * @param[in] delivery the previous delivery retrieved from |
| * either pn_work_head() or pn_work_next() |
| * @return the next delivery that has pending operations, else |
| * NULL if none |
| */ |
| pn_delivery_t *pn_work_next(pn_delivery_t *delivery); |
| |
| /** Factory for creating a new session on the connection. |
| * |
| * A new session is created for the connection, and is added to the |
| * set of sessions maintained by the connection. |
| * |
| * @param[in] connection the session will exist over this connection |
| * @return pointer to new session |
| */ |
| pn_session_t *pn_session(pn_connection_t *connection); |
| |
| /** Factory for creating a transport. |
| * |
| * A transport to be used by a connection to interface with the |
| * network. There can only be one connection associated with a |
| * transport. See pn_transport_bind(). |
| * |
| * @return pointer to new transport |
| */ |
| pn_transport_t *pn_transport(void); |
| |
| /** Binds the transport to an AMQP connection endpoint. |
| * |
| * @return an error code, or 0 on success |
| */ |
| |
| int pn_transport_bind(pn_transport_t *transport, pn_connection_t *connection); |
| |
| /** Retrieve the first Session that matches the given 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_session_t *pn_session_head(pn_connection_t *connection, pn_state_t state); |
| |
| /** Retrieve the next Session that matches the given 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_session_t *pn_session_next(pn_session_t *session, pn_state_t state); |
| |
| /** Retrieve the first Link that matches the given state mask. |
| * |
| * Examines the state of each Link owned by the connection and returns |
| * the first Link 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 Links |
| * @param[in] state mask to match |
| * @return the first Link owned by the connection that matches the |
| * mask, else NULL if no Links match |
| */ |
| pn_link_t *pn_link_head(pn_connection_t *connection, pn_state_t state); |
| |
| /** Retrieve the next Link that matches the given state mask. |
| * |
| * When used with pn_link_head(), the application can access all Links |
| * on the connection that match the given state. See pn_link_head() |
| * for description of match behavior. |
| * |
| * @param[in] link the previous Link obtained from pn_link_head() or |
| * pn_link_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_link_t *pn_link_next(pn_link_t *link, pn_state_t state); |
| |
| void pn_connection_open(pn_connection_t *connection); |
| void pn_connection_close(pn_connection_t *connection); |
| void pn_connection_free(pn_connection_t *connection); |
| |
| /** Access the application context that is associated with the |
| * connection. |
| * |
| * @param[in] connection the connection whose context is to be returned. |
| * |
| * @return the application context that was passed to pn_connection_set_context() |
| */ |
| void *pn_connection_get_context(pn_connection_t *connection); |
| |
| /** Assign a new application context to the connection. |
| * |
| * @param[in] connection the connection which will hold the context. |
| * @param[in] context new application context to associate with the |
| * connection |
| */ |
| void pn_connection_set_context(pn_connection_t *connection, void *context); |
| |
| |
| // transport |
| pn_error_t *pn_transport_error(pn_transport_t *transport); |
| ssize_t pn_transport_input(pn_transport_t *transport, const char *bytes, size_t available); |
| ssize_t pn_transport_output(pn_transport_t *transport, char *bytes, size_t size); |
| time_t pn_transport_tick(pn_transport_t *transport, time_t now); |
| void pn_transport_trace(pn_transport_t *transport, pn_trace_t trace); |
| // max frame of zero means "unlimited" |
| uint32_t pn_transport_get_max_frame(pn_transport_t *transport); |
| void pn_transport_set_max_frame(pn_transport_t *transport, uint32_t size); |
| uint32_t pn_transport_get_remote_max_frame(pn_transport_t *transport); |
| void pn_transport_free(pn_transport_t *transport); |
| |
| // session |
| pn_state_t pn_session_state(pn_session_t *session); |
| pn_error_t *pn_session_error(pn_session_t *session); |
| pn_connection_t *pn_session_connection(pn_session_t *session); |
| void pn_session_open(pn_session_t *session); |
| void pn_session_close(pn_session_t *session); |
| void pn_session_free(pn_session_t *session); |
| void *pn_session_get_context(pn_session_t *session); |
| void pn_session_set_context(pn_session_t *session, void *context); |
| |
| // link |
| pn_link_t *pn_sender(pn_session_t *session, const char *name); |
| pn_link_t *pn_receiver(pn_session_t *session, const char *name); |
| const char *pn_link_name(pn_link_t *link); |
| bool pn_link_is_sender(pn_link_t *link); |
| bool pn_link_is_receiver(pn_link_t *link); |
| pn_state_t pn_link_state(pn_link_t *link); |
| pn_error_t *pn_link_error(pn_link_t *link); |
| pn_session_t *pn_link_session(pn_link_t *link); |
| pn_terminus_t *pn_link_source(pn_link_t *link); |
| pn_terminus_t *pn_link_target(pn_link_t *link); |
| pn_terminus_t *pn_link_remote_source(pn_link_t *link); |
| pn_terminus_t *pn_link_remote_target(pn_link_t *link); |
| pn_delivery_t *pn_link_current(pn_link_t *link); |
| bool pn_link_advance(pn_link_t *link); |
| int pn_link_credit(pn_link_t *link); |
| int pn_link_queued(pn_link_t *link); |
| int pn_link_available(pn_link_t *link); |
| |
| int pn_link_unsettled(pn_link_t *link); |
| pn_delivery_t *pn_unsettled_head(pn_link_t *link); |
| pn_delivery_t *pn_unsettled_next(pn_delivery_t *delivery); |
| |
| void pn_link_open(pn_link_t *sender); |
| void pn_link_close(pn_link_t *sender); |
| void pn_link_free(pn_link_t *sender); |
| void *pn_link_get_context(pn_link_t *link); |
| void pn_link_set_context(pn_link_t *link, void *context); |
| |
| // sender |
| void pn_link_offered(pn_link_t *sender, int credit); |
| ssize_t pn_link_send(pn_link_t *sender, const char *bytes, size_t n); |
| void pn_link_drained(pn_link_t *sender); |
| //void pn_link_abort(pn_sender_t *sender); |
| |
| // receiver |
| void pn_link_flow(pn_link_t *receiver, int credit); |
| void pn_link_drain(pn_link_t *receiver, int credit); |
| ssize_t pn_link_recv(pn_link_t *receiver, char *bytes, size_t n); |
| |
| // terminus |
| pn_terminus_type_t pn_terminus_get_type(pn_terminus_t *terminus); |
| int pn_terminus_set_type(pn_terminus_t *terminus, pn_terminus_type_t type); |
| |
| const char *pn_terminus_get_address(pn_terminus_t *terminus); |
| int pn_terminus_set_address(pn_terminus_t *terminus, const char *address); |
| pn_durability_t pn_terminus_get_durability(pn_terminus_t *terminus); |
| int pn_terminus_set_durability(pn_terminus_t *terminus, |
| pn_durability_t durability); |
| pn_expiry_policy_t pn_terminus_get_expiry_policy(pn_terminus_t *terminus); |
| int pn_terminus_set_expiry_policy(pn_terminus_t *terminus, pn_expiry_policy_t policy); |
| pn_seconds_t pn_terminus_get_timeout(pn_terminus_t *terminus); |
| int pn_terminus_set_timeout(pn_terminus_t *terminus, pn_seconds_t); |
| bool pn_terminus_is_dynamic(pn_terminus_t *terminus); |
| int pn_terminus_set_dynamic(pn_terminus_t *terminus, bool dynamic); |
| pn_data_t *pn_terminus_properties(pn_terminus_t *terminus); |
| pn_data_t *pn_terminus_capabilities(pn_terminus_t *terminus); |
| pn_data_t *pn_terminus_outcomes(pn_terminus_t *terminus); |
| pn_data_t *pn_terminus_filter(pn_terminus_t *terminus); |
| int pn_terminus_copy(pn_terminus_t *terminus, pn_terminus_t *src); |
| |
| // delivery |
| pn_delivery_t *pn_delivery(pn_link_t *link, pn_delivery_tag_t tag); |
| pn_delivery_tag_t pn_delivery_tag(pn_delivery_t *delivery); |
| pn_link_t *pn_delivery_link(pn_delivery_t *delivery); |
| // how do we do delivery state? |
| pn_disposition_t pn_delivery_local_state(pn_delivery_t *delivery); |
| pn_disposition_t pn_delivery_remote_state(pn_delivery_t *delivery); |
| bool pn_delivery_settled(pn_delivery_t *delivery); |
| size_t pn_delivery_pending(pn_delivery_t *delivery); |
| bool pn_delivery_partial(pn_delivery_t *delivery); |
| bool pn_delivery_writable(pn_delivery_t *delivery); |
| bool pn_delivery_readable(pn_delivery_t *delivery); |
| bool pn_delivery_updated(pn_delivery_t *delivery); |
| void pn_delivery_update(pn_delivery_t *delivery, pn_disposition_t disposition); |
| void pn_delivery_clear(pn_delivery_t *delivery); |
| //int pn_delivery_format(pn_delivery_t *delivery); |
| void pn_delivery_settle(pn_delivery_t *delivery); |
| void pn_delivery_dump(pn_delivery_t *delivery); |
| void *pn_delivery_get_context(pn_delivery_t *delivery); |
| void pn_delivery_set_context(pn_delivery_t *delivery, void *context); |
| |
| #ifdef __cplusplus |
| } |
| #endif |
| |
| #endif /* engine.h */ |