Crate qpid_proton_sys[][src]

Structs

pn_bytes_t
pn_condition_t
pn_connection_t
pn_data_t
pn_delivery_t
pn_delivery_tag_t
pn_error_t
pn_event_batch_t
pn_event_t
pn_link_t
pn_logger_t
pn_message_t
pn_messenger_t
pn_proactor_t
pn_rwbytes_t
pn_sasl_t
pn_session_t
pn_ssl_domain_t
pn_ssl_t
pn_string_t
pn_subscription_t
pn_terminus_t
pn_transport_t

Enums

pn_event_type_t
pn_log_level_t
pn_log_subsystem_t
pn_ssl_mode_t
pn_status_t

Describes all the possible states for a message associated with a given tracker.

pn_type_t

Identifies an AMQP type.

Functions

pn_bytes

Create a pn_bytes_t.

pn_condition_get_description

Gets the description associated with the exceptional condition.

pn_condition_get_name

Returns the name associated with the exceptional condition, or NULL if there is no conditional information set.

pn_connection

Factory to construct a new Connection.

pn_connection_close

Close a connection. Once this operation has completed, the PN_LOCAL_CLOSED state flag will be set. This may be called without calling pn_connection_open, in this case it is equivalent to calling pn_connection_open followed by pn_connection_close.

pn_connection_open

Open a connection. Once this operation has completed, the PN_LOCAL_ACTIVE state flag will be set.

pn_connection_set_container

Set the AMQP Container name advertised by a connection object.

pn_connection_set_hostname

Set the name of the virtual host (either fully qualified or relative) to which this connection is connecting to. This information may be used by the remote peer to determine the correct back-end service to connect the client to. This value will be sent in the Open performative, and will be used by SSL and SASL layers to identify the peer.

pn_connection_set_password

Set the authentication password for a client connection. It is necessary to set the username and password before binding the connection to a transport and it isn’t allowed to change them after the binding. Note that the password is write only and has no accessor as the underlying implementation should be zeroing the password after use to avoid the password being present in memory longer than necessary

pn_connection_set_user

Set the authentication username for a client connection. It is necessary to set the username and password before binding the connection to a transport and it isn’t allowed to change them after the binding. If not set then no authentication will be negotiated unless the client sasl layer is explicitly created (this would be for something like Kerberos where the credentials are implicit in the environment, or to explicitly use the ANONYMOUS SASL mechanism)

pn_data_dump

Dumps a debug representation of the internal state of the pn_data_t object that includes its navigational state to stdout for debugging purposes.

pn_data_encode

Writes the contents of a data object to the given buffer as an AMQP data stream.

pn_data_enter
pn_data_exit
pn_data_get_binary
pn_data_get_bytes
pn_data_get_symbol
pn_data_is_described
pn_data_is_null
pn_data_next

Advances the current node to its next sibling and returns true. If there is no next sibling the current node remains unchanged and false is returned.

pn_data_prev

Moves the current node to its previous sibling and returns true. If there is no previous sibling the current node remains unchanged and false is returned.

pn_data_put_array

Puts an empty array value into a pn_data_t. Elements may be filled by entering the array node and putting the element values. The values must all be of the specified array element type. If an array is described then the first child value of the array is the descriptor and may be of any type.

pn_data_put_binary

Puts a PN_BINARY value. The bytes referenced by the pn_bytes_t argument are copied and stored inside the pn_data_t object.

pn_data_put_char

Puts a PN_CHAR value.

pn_data_put_described

Puts a described value into a pn_data_t object. A described node has two children, the descriptor and the value. These are specified by entering the node and putting the desired values.

pn_data_put_int

Puts a PN_INT value.

pn_data_put_long

Puts a PN_LONG value.

pn_data_put_map

Puts an empty map value into a pn_data_t. Elements may be filled by entering the map node and putting alternating key value pairs.

pn_data_put_string

Puts a PN_STRING value. The bytes referenced by the pn_bytes_t argument are copied and stored inside the pn_data_t object.

pn_data_put_symbol

Puts a PN_SYMBOL value. The bytes referenced by the pn_bytes_t argument are copied and stored inside the pn_data_t object.

pn_data_put_uint

Puts a PN_UINT value.

pn_data_type

Access the type of the current node. Returns PN_INVALID if there is no current node.

pn_delivery

Create a delivery on a link. Every delivery object within a link must be supplied with a unique tag. Links maintain a sequence of delivery object in the order that they are created.

pn_delivery_link

Get the parent link for a delivery object.

pn_delivery_pending

Get the amount of pending message data for a delivery.

pn_delivery_readable

Check if a delivery is readable. A delivery is considered readable if it is the current delivery on an incoming link.

pn_delivery_remote_state

Get the remote disposition state for a delivery.

pn_delivery_settle

Settle a delivery. A settled delivery can never be used again.

pn_delivery_update

Update the disposition of a delivery. When update is invoked the updated disposition of the delivery will be communicated to the peer.

pn_dtag

Construct a delivery tag.

pn_error_set

Set the error code and text. Makes a copy of text.

pn_error_text

Get the error text. The returned pointer is owned by the pn_error_t.

pn_event_batch_next

Remove the next event from the batch and return it. NULL means the batch is empty. The returned event pointer is valid until pn_event_batch_next() is called again on the same batch.

pn_event_connection

Get the connection associated with an event.

pn_event_delivery

Get the delivery associated with an event.

pn_event_link

Get the link associated with an event.

pn_event_session

Get the session associated with an event.

pn_event_type

Get the type of an event.

pn_link_advance

Advance the current delivery of a link to the next delivery on the link. For sending links this operation is used to finish sending message data for the current outgoing delivery and move on to the next outgoing delivery (if any). For receiving links, this operation is used to finish accessing message data from the current incoming delivery and move on to the next incoming delivery (if any). Each link maintains a sequence of deliveries in the order they were created, along with a pointer to the current delivery. The pn_link_advance operation will modify the current delivery on the link to point to the next delivery in the sequence. If there is no next delivery in the sequence, the current delivery will be set to NULL. This operation will return true if invoking it caused the value of the current delivery to change, even if it was set to NULL.

pn_link_credit

Get the credit balance for a link. Links use a credit based flow control scheme. Every receiver maintains a credit balance that corresponds to the number of deliveries that the receiver can accept at any given moment. As more capacity becomes available at the receiver (see pn_link_flow), it adds credit to this balance and communicates the new balance to the sender. Whenever a delivery is sent/received, the credit balance maintained by the link is decremented by one. Once the credit balance at the sender reaches zero, the sender must pause sending until more credit is obtained from the receiver. Note that a sending link may still be used to send deliveries even if pn_link_credit reaches zero, however those deliveries will end up being buffered by the link until enough credit is obtained from the receiver to send them over the wire. In this case the balance reported by pn_link_credit will go negative.

pn_link_flow

Grant credit for incoming deliveries on a receiver.

pn_link_open

Open a link. Once this operation has completed, the PN_LOCAL_ACTIVE state flag will be set.

pn_link_recv

Receive message data for the current delivery on a link. Use pn_delivery_pending on the current delivery to figure out how much buffer space is needed. Note that the link API can be used to stream large messages across the network, so just because there is no data to read does not imply the message is complete. To ensure the entirety of the message data has been read, either invoke pn_link_recv until PN_EOS is returned, or verify that (!pn_delivery_partial(d) && !pn_delivery_aborted(d) && pn_delivery_pending(d)==0)

pn_link_send

Send message data for the current delivery on a link.

pn_link_source

Access the locally defined source definition for a link. The pointer returned by this operation is valid until the link object is freed.

pn_link_target

Access the locally defined target definition for a link. The pointer returned by this operation is valid until the link object is freed.

pn_logger_set_mask

Set a logger’s tracing flags. Set individual trace flags to control what a logger logs. The trace flags for a logger control what sort of information is logged. See pn_log_level_t and pn_log_subsystem_t for more details. Note that log messages with a level of PN_LEVEL_CRITICAL will always be logged. Otherwise log message are only logged if the subsystem and level flags both match a flag in the masks held by the logger. If you don’t want to affect the subsystem flags then you can set subsystem to PN_SUBSYSTEM_NONE. likewise level to PN_LEVEL_NONE if you don’t want to affect the level flags.

pn_message

Construct a new pn_message_t. Every message that is constructed must be freed using pn_message_free().

pn_message_annotations

Get/set the annotations for a message. This operation returns a pointer to a pn_data_t representing the content of the annotations section of a message. The pointer is valid until the message is freed and may be used to both access and modify the content of the annotations section of a message. The pn_data_t must either be empty or consist of a symbol keyed map in order to be considered valid message annotations.

pn_message_body

Get and set the body of a message. This operation returns a pointer to a pn_data_t representing the body of a message. The pointer is valid until the message is freed and may be used to both access and modify the content of the message body.

pn_message_clear

Clears the content of a pn_message_t. When pn_message_clear returns, the supplied pn_message_t will be emptied of all content and effectively returned to the same state as if it was just created.

pn_message_data

Save message content into a pn_data_t object data. The data object will first be cleared.

pn_message_decode

Decode/load message content from AMQP formatted binary data. Upon invoking this operation, any existing message content will be cleared and replaced with the content from the provided binary data.

pn_message_encode

Encode a message as AMQP formatted binary data. If the buffer space provided is insufficient to store the content held in the message, the operation will fail and return a PN_OVERFLOW error code.

pn_message_error

Free a previously constructed pn_message_t.

pn_message_free

Free a previously constructed pn_message_t.

pn_message_get_content_type

Get the content_type for a message. This operation will return NULL if no content_type has been set or if the content_type has been set to NULL. The pointer returned by this operation is valid until any one of the following operations occur: pn_message_free() pn_message_clear() pn_message_set_content_type()

pn_message_id

Get/set the id for a message. The message id provides a globally unique identifier for a message. A message id can be an a string, an unsigned long, a uuid or a binary value. This operation returns a pointer to a pn_data_t that can be used to access and/or modify the value of the message id. The pointer is valid until the message is freed. See pn_data_t for details on how to get/set the value.

pn_message_instructions

Get/set the delivery instructions for a message. This operation returns a pointer to a pn_data_t representing the content of the delivery instructions section of a message. The pointer is valid until the message is freed and may be used to both access and modify the content of the delivery instructions section of a message. The pn_data_t must either be empty or consist of a symbol keyed map in order to be considered valid delivery instructions.

pn_message_properties

Get and set the properties for a message. This operation returns a pointer to a pn_data_t representing the content of the properties section of a message. The pointer is valid until the message is freed and may be used to both access and modify the content of the properties section of a message. The pn_data_t must either be empty or consist of a string keyed map in order to be considered valid message properties.

pn_message_send

Encode and send a message on a sender link. Performs the following steps: call pn_message_encode2() to encode the message to a buffer call pn_link_send() to send the encoded message bytes call pn_link_advance() to indicate the message is complete Note: you must create a delivery for the message before calling pn_message_send() see pn_delivery()

pn_message_set_address

Set the address for a message. The supplied address pointer must either be NULL or reference a NUL terminated string. When the pointer is NULL, the address of the message is set to NULL. When the pointer is non NULL, the contents are copied into the message.

pn_message_set_content_encoding

Set the content_encoding for a message. The supplied content_encoding pointer must either be NULL or reference a NUL terminated string. When the pointer is NULL, the content_encoding is set to NULL. When the pointer is non NULL, the contents are copied into the message. Returns zero on success or an error code on failure

pn_message_set_content_type

Set the content_type for a message. The supplied content_type pointer must either be NULL or reference a NUL terminated string. When the pointer is NULL, the content_type is set to NULL. When the pointer is non NULL, the contents are copied into the message.

pn_message_set_inferred

Set the inferred flag for a message. See pn_message_is_inferred() for a description of what the inferred flag is.

pn_messenger

Construct a new pn_messenger_t with the given name. The name is global. If a NULL name is supplied, a UUID based name will be chosen.

pn_messenger_errno

Get the code for a messenger’s most recent error. The error code is initialized to zero at messenger creation. The error number is “sticky” i.e. error codes are not reset to 0 at the end of successful API calls. You can use pn_messenger_error to access the messenger’s error object and clear explicitly if desired.

pn_messenger_free

Frees a Messenger.

pn_messenger_get

Get the next message from the head of a messenger’s incoming queue. The get operation copies the message data from the head of the messenger’s incoming queue into the provided pn_message_t object. If provided pn_message_t pointer is NULL, the head message will be discarded. This operation will return PN_EOS if there are no messages left on the incoming queue.

pn_messenger_is_blocking

Check if a messenger is in blocking mode.

pn_messenger_outgoing_tracker

Get a tracker for the outgoing message most recently given to pn_messenger_put. This tracker may be used with pn_messenger_status to determine the delivery status of the message, as long as the message is still within your outgoing window.

pn_messenger_put

Puts a message onto the messenger’s outgoing queue. The message may also be sent if transmission would not cause blocking. This call will not block.

pn_messenger_recv

Retrieve messages into a messenger’s incoming queue. Instructs a messenger to receive up to limit messages into the incoming message queue of a messenger. If limit is -1, the messenger will receive as many messages as it can buffer internally. If the messenger is in blocking mode, this call will block until at least one message is available in the incoming queue. Each call to pn_messenger_recv replaces the previous receive operation, so pn_messenger_recv(messenger, 0) will cancel any outstanding receive. After receiving messages onto your incoming queue use pn_messenger_get() to access message content.

pn_messenger_send

Send messages from a messenger’s outgoing queue. If a messenger is in blocking mode (see pn_messenger_is_blocking()), this operation will block until N messages have been sent from the outgoing queue. A value of -1 for N means “all messages in the outgoing queue”. See below for a full definition of what sent from the outgoing queue means. Any blocking will end once the messenger’s configured timeout (if any) has been reached. When this happens an error code of PN_TIMEOUT is returned. If the messenger is in non blocking mode, this call will return an error code of PN_INPROGRESS if it is unable to send the requested number of messages without blocking. A message is considered to be sent from the outgoing queue when its status has been fully determined. This does not necessarily mean the message was successfully sent to the final recipient though, for example of the receiver rejects the message, the final status will be PN_STATUS_REJECTED. Similarly, if a message is sent to an invalid address, it may be removed from the outgoing queue without ever even being transmitted. In this case the final status will be PN_STATUS_ABORTED.

pn_messenger_set_blocking

Enable or disable blocking behavior for a messenger during calls to pn_messenger_send and pn_messenger_recv.

pn_messenger_set_flags

Sets control flags to enable additional function for the Messenger.

pn_messenger_set_outgoing_window

Set the size of a messenger’s outgoing window. See pn_messenger_get_outgoing_window() for details.

pn_messenger_set_tracer

Set the tracer associated with a messenger.

pn_messenger_start

Currently a no-op placeholder. For future compatibility, do not send or receive messages before starting the messenger.

pn_messenger_status

Track the status of a delivery. Get the current status of the delivery associated with the supplied tracker. This may return PN_STATUS_UNKOWN if the tracker has fallen outside the incoming/outgoing tracking windows of the messenger.

pn_messenger_stop

Stops a messenger. Stopping a messenger will perform an orderly shutdown of all underlying connections. This may require some time. If the messenger is in non blocking mode (see pn_messenger_is_blocking), this operation will return PN_INPROGRESS if it cannot finish immediately. In that case, you can use pn_messenger_stopped() to determine when the messenger has finished stopping.

pn_messenger_subscribe

Subscribes a messenger to messages from the specified source.

pn_proactor

Create a proactor. Must be freed with pn_proactor_free()

pn_proactor_addr

Format a host:port address string for pn_proactor_connect() or pn_proactor_listen()

pn_proactor_connect2

Free the proactor. Abort open connections/listeners, clean up all resources.

pn_proactor_done

Call when finished handling a batch of events. Must be called exactly once to match each call to pn_proactor_wait().

pn_proactor_free

Free the proactor. Abort open connections/listeners, clean up all resources.

pn_proactor_wait

Wait until there are Proactor events to handle. You must call pn_proactor_done() when you are finished with the batch, you must not use the batch pointer after calling pn_proactor_done(). Normally it is most efficient to handle the entire batch in the calling thread and then call pn_proactor_done(), but see pn_proactor_done() for more options. pn_proactor_get() is a non-blocking version of this call.

pn_receiver

Construct a new receiver on a session. Each receiving link between two AMQP containers must be uniquely named. Note that this uniqueness cannot be enforced at the API level, so some consideration should be taken in choosing link names.

pn_rwbytes

Create a pn_rwbytes_t.

pn_sasl

Construct an Authentication and Security Layer object. This will return the SASL layer object for the supplied transport object. If there is currently no SASL layer one will be created. On the client side of an AMQP connection this will have the effect of ensuring that the AMQP SASL layer is used for that connection.

pn_sasl_allowed_mechs

SASL mechanisms that are to be considered for authentication. This can be used on either the client or the server to restrict the SASL mechanisms that may be used to the mechanisms on the list.

pn_sasl_set_allow_insecure_mechs

Boolean to allow use of clear text authentication mechanisms. By default the SASL layer is configured not to allow mechanisms that disclose the clear text of the password over an unencrypted AMQP connection. This specifically will disallow the use of the PLAIN mechanism without using SSL encryption. This default is to avoid disclosing password information accidentally over an insecure network. If you actually wish to use a clear text password unencrypted then you can use this API to set allow_insecure_mechs to true.

pn_sender

Construct a new sender on a session. Each sending link between two AMQP containers must be uniquely named. Note that this uniqueness cannot be enforced at the API level, so some consideration should be taken in choosing link names.

pn_session

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.

pn_session_close

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.

pn_session_free

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.

pn_session_open

Open a session. Once this operation has completed, the PN_LOCAL_ACTIVE state flag will be set.

pn_session_remote_condition

Boolean to allow use of clear text authentication mechanisms. By default the SASL layer is configured not to allow mechanisms that disclose the clear text of the password over an unencrypted AMQP connection. This specifically will disallow the use of the PLAIN mechanism without using SSL encryption. This default is to avoid disclosing password information accidentally over an insecure network. If you actually wish to use a clear text password unencrypted then you can use this API to set allow_insecure_mechs to true.

pn_ssl

Create a new SSL session object associated with a transport. A transport must have an SSL object in order to “speak” SSL over its connection. This method allocates an SSL object associates it with the transport.

pn_ssl_domain

Create an SSL configuration domain. This method allocates an SSL domain object. This object is used to hold the SSL configuration for one or more SSL sessions. The SSL session object (pn_ssl_t) is allocated from this object.

pn_ssl_get_remote_subject

Get the subject from the peers certificate.

pn_ssl_init

Initialize an SSL session. This method configures an SSL object with defaults or the configuration provided by the given domain.

pn_ssl_set_peer_hostname

Set the expected identity of the remote peer. By default, SSL will use the hostname associated with the connection that the transport is bound to (see pn_connection_set_hostname). This method allows the caller to override that default. The hostname is used for two purposes: 1) when set on an SSL client, it is sent to the server during the handshake (if Server Name Indication is supported), and 2) it is used to check against the identifying name provided in the peer’s certificate. If the supplied name does not exactly match a SubjectAltName (type DNS name), or the CommonName entry in the peer’s certificate, the peer is considered unauthenticated (potential imposter), and the SSL connection is aborted.

pn_string_get
pn_terminus_set_address

Set the address of a terminus object.

pn_transport

Factory for creating a transport. A transport is used by a connection to interface with the network. There can only be one connection associated with a transport. Initially a transport is configured to be a client transport. Use pn_transport_set_server() to configure the transport as a server transport. A client transport initiates outgoing connections. A client transport must be configured with the protocol layers to use and cannot configure itself automatically. A server transport accepts incoming connections. It can automatically configure itself to include the various protocol layers depending on the incoming protocol headers.

pn_transport_condition

Get additional information about the condition of the transport. When a PN_TRANSPORT_ERROR event occurs, this operation can be used to access the details of the error condition. The pointer returned by this operation is valid until the transport object is freed.

pn_transport_logger

Get the transport logger. This can be used to control the logging information emitted by the transport The pointer returned by this operation is valid until the transport object is freed.

pn_transport_require_auth

Set whether a non-authenticated transport connection is allowed. There are several ways within the AMQP protocol suite to get unauthenticated connections: Use no SASL layer (with either no TLS or TLS without client certificates) Use a SASL layer but the ANONYMOUS mechanism The default if this option is not set is to allow unauthenticated connections.

pn_transport_require_encryption

Set whether a non encrypted transport connection is allowed. There are several ways within the AMQP protocol suite to get encrypted connections: Use TLS Use a SASL with a mechanism that supports security layers The default if this option is not set is to allow unencrypted connections.