disposition.h
Go to the documentation of this file.
#ifndef PROTON_DISPOSITION_H
#define PROTON_DISPOSITION_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/condition.h>
#include <stddef.h>
#ifdef __cplusplus
extern "C" {
#endif
/**
* @file
*
* Disposition API for the proton Engine.
*
* @defgroup disposition Disposition
* @ingroup delivery
* @{
*/
/**
* Dispositions record the current state and/or final outcome of a
* transfer. Every delivery contains both a local and remote
* disposition. The local disposition holds the local state of the
* delivery, and the remote disposition holds the last known remote
* state of the delivery.
*/
typedef struct pn_disposition_t pn_disposition_t;
/**
* The PN_RECEIVED delivery state is a non terminal state indicating
* how much (if any) message data has been received for a delivery.
*/
#define PN_RECEIVED (0x0000000000000023)
/**
* The PN_ACCEPTED delivery state is a terminal state indicating that
* the delivery was successfully processed. Once in this state there
* will be no further state changes prior to the delivery being
* settled.
*/
#define PN_ACCEPTED (0x0000000000000024)
/**
* The PN_REJECTED delivery state is a terminal state indicating that
* the delivery could not be processed due to some error condition.
* Once in this state there will be no further state changes prior to
* the delivery being settled.
*/
#define PN_REJECTED (0x0000000000000025)
/**
* The PN_RELEASED delivery state is a terminal state indicating that
* the delivery is being returned to the sender. Once in this state
* there will be no further state changes prior to the delivery being
* settled.
*/
#define PN_RELEASED (0x0000000000000026)
/**
* The PN_MODIFIED delivery state is a terminal state indicating that
* the delivery is being returned to the sender and should be
* annotated by the sender prior to further delivery attempts. Once in
* this state there will be no further state changes prior to the
* delivery being settled.
*/
#define PN_MODIFIED (0x0000000000000027)
/**
* Get the type of a disposition.
*
* Defined values are:
*
* - ::PN_RECEIVED
* - ::PN_ACCEPTED
* - ::PN_REJECTED
* - ::PN_RELEASED
* - ::PN_MODIFIED
*
* @param[in] disposition a disposition object
* @return the type of the disposition
*/
PN_EXTERN uint64_t pn_disposition_type(pn_disposition_t *disposition);
/**
* Access the condition object associated with a disposition.
*
* The ::pn_condition_t object retrieved by this operation may be
* modified prior to updating a delivery. When a delivery is updated,
* the condition described by the disposition is reported to the peer
* if applicable to the current delivery state, e.g. states such as
* ::PN_REJECTED.
*
* The pointer returned by this operation is valid until the parent
* delivery is settled.
*
* @param[in] disposition a disposition object
* @return a pointer to the disposition condition
*/
PN_EXTERN pn_condition_t *pn_disposition_condition(pn_disposition_t *disposition);
/**
* Access the disposition as a raw pn_data_t.
*
* Dispositions are an extension point in the AMQP protocol. The
* disposition interface provides setters/getters for those
* dispositions that are predefined by the specification, however
* access to the raw disposition data is provided so that other
* dispositions can be used.
*
* The ::pn_data_t pointer returned by this operation is valid until
* the parent delivery is settled.
*
* @param[in] disposition a disposition object
* @return a pointer to the raw disposition data
*/
PN_EXTERN pn_data_t *pn_disposition_data(pn_disposition_t *disposition);
/**
* Get the section number associated with a disposition.
*
* @param[in] disposition a disposition object
* @return a section number
*/
PN_EXTERN uint32_t pn_disposition_get_section_number(pn_disposition_t *disposition);
/**
* Set the section number associated with a disposition.
*
* @param[in] disposition a disposition object
* @param[in] section_number a section number
*/
PN_EXTERN void pn_disposition_set_section_number(pn_disposition_t *disposition, uint32_t section_number);
/**
* Get the section offset associated with a disposition.
*
* @param[in] disposition a disposition object
* @return a section offset
*/
PN_EXTERN uint64_t pn_disposition_get_section_offset(pn_disposition_t *disposition);
/**
* Set the section offset associated with a disposition.
*
* @param[in] disposition a disposition object
* @param[in] section_offset a section offset
*/
PN_EXTERN void pn_disposition_set_section_offset(pn_disposition_t *disposition, uint64_t section_offset);
/**
* Check if a disposition has the failed flag set.
*
* @param[in] disposition a disposition object
* @return true if the disposition has the failed flag set, false otherwise
*/
PN_EXTERN bool pn_disposition_is_failed(pn_disposition_t *disposition);
/**
* Set the failed flag on a disposition.
*
* @param[in] disposition a disposition object
* @param[in] failed the value of the failed flag
*/
PN_EXTERN void pn_disposition_set_failed(pn_disposition_t *disposition, bool failed);
/**
* Check if a disposition has the undeliverable flag set.
*
* @param[in] disposition a disposition object
* @return true if the disposition has the undeliverable flag set, false otherwise
*/
PN_EXTERN bool pn_disposition_is_undeliverable(pn_disposition_t *disposition);
/**
* Set the undeliverable flag on a disposition.
*
* @param[in] disposition a disposition object
* @param[in] undeliverable the value of the undeliverable flag
*/
PN_EXTERN void pn_disposition_set_undeliverable(pn_disposition_t *disposition, bool undeliverable);
/**
* Access the annotations associated with a disposition.
*
* The ::pn_data_t object retrieved by this operation may be modified
* prior to updating a delivery. When a delivery is updated, the
* annotations described by the ::pn_data_t are reported to the peer
* if applicable to the current delivery state, e.g. states such as
* ::PN_MODIFIED. The ::pn_data_t must be empty or contain a symbol
* keyed map.
*
* The pointer returned by this operation is valid until the parent
* delivery is settled.
*
* @param[in] disposition a disposition object
* @return the annotations associated with the disposition
*/
PN_EXTERN pn_data_t *pn_disposition_annotations(pn_disposition_t *disposition);
/** @}
*/
#ifdef __cplusplus
}
#endif
#endif /* disposition.h */
pn_disposition_type
PN_EXTERN uint64_t pn_disposition_type(pn_disposition_t *disposition)
Get the type of a disposition.
import_export.h
pn_disposition_set_undeliverable
PN_EXTERN void pn_disposition_set_undeliverable(pn_disposition_t *disposition, bool undeliverable)
Set the undeliverable flag on a disposition.
type_compat.h
pn_disposition_condition
PN_EXTERN pn_condition_t * pn_disposition_condition(pn_disposition_t *disposition)
Access the condition object associated with a disposition.
PN_EXTERN
#define PN_EXTERN
Definition: import_export.h:53
condition.h
The Condition API for the proton Engine.
pn_disposition_get_section_number
PN_EXTERN uint32_t pn_disposition_get_section_number(pn_disposition_t *disposition)
Get the section number associated with a disposition.
pn_disposition_data
PN_EXTERN pn_data_t * pn_disposition_data(pn_disposition_t *disposition)
Access the disposition as a raw pn_data_t.
pn_disposition_get_section_offset
PN_EXTERN uint64_t pn_disposition_get_section_offset(pn_disposition_t *disposition)
Get the section offset associated with a disposition.
pn_disposition_t
struct pn_disposition_t pn_disposition_t
Dispositions record the current state and/or final outcome of a transfer.
Definition: disposition.h:51
pn_data_t
struct pn_data_t pn_data_t
An AMQP Data object.
Definition: codec.h:358
pn_disposition_set_failed
PN_EXTERN void pn_disposition_set_failed(pn_disposition_t *disposition, bool failed)
Set the failed flag on a disposition.
pn_disposition_is_undeliverable
PN_EXTERN bool pn_disposition_is_undeliverable(pn_disposition_t *disposition)
Check if a disposition has the undeliverable flag set.
pn_disposition_set_section_offset
PN_EXTERN void pn_disposition_set_section_offset(pn_disposition_t *disposition, uint64_t section_offset)
Set the section offset associated with a disposition.
pn_disposition_annotations
PN_EXTERN pn_data_t * pn_disposition_annotations(pn_disposition_t *disposition)
Access the annotations associated with a disposition.
pn_disposition_is_failed
PN_EXTERN bool pn_disposition_is_failed(pn_disposition_t *disposition)
Check if a disposition has the failed flag set.
pn_condition_t
struct pn_condition_t pn_condition_t
An AMQP Condition object.
Definition: condition.h:64
pn_disposition_set_section_number
PN_EXTERN void pn_disposition_set_section_number(pn_disposition_t *disposition, uint32_t section_number)
Set the section number associated with a disposition.