Qpid Proton C++ API  0.17.0
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Pages
container Class Reference

A top-level container of connections, sessions, senders, and receivers. More...

#include <container.hpp>

Public Member Functions

 container (messaging_handler &h, const std::string &id="")
 Create a container.
 
 container (const std::string &id="")
 Create a container.
 
returned< connectionconnect (const std::string &url, const connection_options &)
 Connect to url and send an open request to the remote peer. More...
 
returned< connectionconnect (const std::string &url)
 Connect to url and send an open request to the remote peer.
 
listener listen (const std::string &url, listen_handler &lh)
 Start listening on url. More...
 
listener listen (const std::string &url, const connection_options &)
 Listen with a fixed set of options for all accepted connections. More...
 
listener listen (const std::string &url)
 Start listening on URL. More...
 
void run ()
 Run the container in this thread. More...
 
void auto_stop (bool)
 If true, stop the container when all active connections and listeners are closed. More...
 
void stop (const error_condition &err)
 Experimental - Stop the container with an error_condition err. More...
 
void stop ()
 Experimental - Stop the container with an empty error condition. More...
 
returned< senderopen_sender (const std::string &url)
 Open a connection and sender for url.
 
returned< senderopen_sender (const std::string &url, const proton::sender_options &o)
 Open a connection and sender for url. More...
 
returned< senderopen_sender (const std::string &url, const connection_options &c)
 Open a connection and sender for url. More...
 
returned< senderopen_sender (const std::string &url, const proton::sender_options &o, const connection_options &c)
 Open a connection and sender for url. More...
 
returned< receiveropen_receiver (const std::string &url)
 Open a connection and receiver for url.
 
returned< receiveropen_receiver (const std::string &url, const proton::receiver_options &o)
 Open a connection and receiver for url. More...
 
returned< receiveropen_receiver (const std::string &url, const connection_options &c)
 Open a connection and receiver for url. More...
 
returned< receiveropen_receiver (const std::string &url, const proton::receiver_options &o, const connection_options &c)
 Open a connection and receiver for url. More...
 
std::string id () const
 A unique identifier for the container.
 
void client_connection_options (const connection_options &)
 Connection options that will be to outgoing connections. More...
 
connection_options client_connection_options () const
 Connection options that will be to outgoing connections. More...
 
void server_connection_options (const connection_options &)
 Connection options that will be applied to incoming connections. More...
 
connection_options server_connection_options () const
 Connection options that will be applied to incoming connections. More...
 
void sender_options (const class sender_options &)
 Sender options applied to senders created by this container. More...
 
class sender_options sender_options () const
 Options for creating a sender. More...
 
void receiver_options (const class receiver_options &)
 Receiver options applied to receivers created by this container. More...
 
class receiver_options receiver_options () const
 Options for creating a receiver. More...
 
void schedule (duration, void_function0 &)
 Schedule a function to be called after the duration. More...
 
void schedule (duration, std::function< void()>)
 Schedule a function to be called after the duration.
 

Friends

class connection_options
 
class session_options
 
class receiver_options
 
class sender_options
 

Detailed Description

A top-level container of connections, sessions, senders, and receivers.

A container gives a unique identity to each communicating peer. It is often a process-level object.

It serves as an entry point to the API, allowing connections, senders, and receivers to be established. It can be supplied with an event handler in order to intercept important messaging events, such as newly received messages or newly issued credit for sending messages.

Examples:
broker.cpp, client.cpp, direct_recv.cpp, direct_send.cpp, helloworld.cpp, helloworld_direct.cpp, scheduled_send.cpp, scheduled_send_03.cpp, server.cpp, server_direct.cpp, service_bus.cpp, simple_recv.cpp, and simple_send.cpp.

Member Function Documentation

void auto_stop ( bool  )

If true, stop the container when all active connections and listeners are closed.

If false the container will keep running till stop() is called.

auto_stop is set by default when a new container is created.

void client_connection_options ( const connection_options )

Connection options that will be to outgoing connections.

These are applied first and overriden by options provided in connect() and messaging_handler::on_connection_open().

connection_options client_connection_options ( ) const

Connection options that will be to outgoing connections.

These are applied first and overriden by options provided in connect() and messaging_handler::on_connection_open().

returned<connection> connect ( const std::string &  url,
const connection_options  
)

Connect to url and send an open request to the remote peer.

Options are applied to the connection as follows, values in later options override earlier ones:

  1. client_connection_options()
  2. options passed to connect()

The handler in the composed options is used to call proton::messaging_handler::on_connection_open() when the remote peer's open response is received.

Examples:
helloworld.cpp, server.cpp, and service_bus.cpp.
listener listen ( const std::string &  url,
listen_handler lh 
)

Start listening on url.

Calls to the listen_handler are serialized for this listener, but handlers attached to separate listeners may be called concurrently.

Parameters
urlidentifies a listening url.
lhhandles listening events
Returns
listener lets you stop listening
Examples:
direct_recv.cpp, direct_send.cpp, helloworld_direct.cpp, and server_direct.cpp.
listener listen ( const std::string &  url,
const connection_options  
)

Listen with a fixed set of options for all accepted connections.

See listen(const std::string&, listen_handler&)

listener listen ( const std::string &  url)

Start listening on URL.

New connections will use the handler from server_connection_options()

returned<receiver> open_receiver ( const std::string &  url,
const proton::receiver_options o 
)

Open a connection and receiver for url.

Supplied receiver options will override the container's template options.

returned<receiver> open_receiver ( const std::string &  url,
const connection_options c 
)

Open a connection and receiver for url.

Supplied receiver or connection options will override the container's template options.

returned<receiver> open_receiver ( const std::string &  url,
const proton::receiver_options o,
const connection_options c 
)

Open a connection and receiver for url.

Supplied receiver or connection options will override the container's template options.

returned<sender> open_sender ( const std::string &  url,
const proton::sender_options o 
)

Open a connection and sender for url.

Supplied sender options will override the container's template options.

returned<sender> open_sender ( const std::string &  url,
const connection_options c 
)

Open a connection and sender for url.

Supplied connection options will override the container's template options.

returned<sender> open_sender ( const std::string &  url,
const proton::sender_options o,
const connection_options c 
)

Open a connection and sender for url.

Supplied sender or connection options will override the container's template options.

void receiver_options ( const class receiver_options )

Receiver options applied to receivers created by this container.

They are applied before messaging_handler::on_receiver_open() and can be overridden.

Options for creating a receiver.

Options can be "chained" like this:

l = container.create_receiver(url, receiver_options().handler(h).auto_settle(true));

You can also create an options object with common settings and use it as a base for different connections that have mostly the same settings:

opts.auto_settle(true);
c2 = container.open_receiver(url2, opts.handler(h2));

Normal value semantics: copy or assign creates a separate copy of the options.

void run ( )

Run the container in this thread.

Returns when the container stops.

See Also
auto_stop() and stop().

With a multithreaded container, call run() in multiple threads to create a thread pool.

Examples:
mt/broker.cpp.
void schedule ( duration  ,
void_function0  
)

Schedule a function to be called after the duration.

C++03 compatible, for C++11 use schedule(duration, std::function<void()>)

Examples:
scheduled_send.cpp, and scheduled_send_03.cpp.
void sender_options ( const class sender_options )

Sender options applied to senders created by this container.

They are applied before messaging_handler::on_sender_open() and can be overridden.

class sender_options sender_options ( ) const

Options for creating a sender.

Options can be "chained" like this:

l = container.create_sender(url, sender_options().handler(h).auto_settle(false));

You can also create an options object with common settings and use it as a base for different connections that have mostly the same settings:

opts.browsing(true);
l1 = container.open_sender(url1, opts.handler(h1));
c2 = container.open_receiver(url2, opts.handler(h2));

Normal value semantics: copy or assign creates a separate copy of the options.

void server_connection_options ( const connection_options )

Connection options that will be applied to incoming connections.

These are applied first and overridden by options provided in listen(), listen_handler::on_accept() and messaging_handler::on_connection_open().

connection_options server_connection_options ( ) const

Connection options that will be applied to incoming connections.

These are applied first and overridden by options provided in listen(), listen_handler::on_accept() and messaging_handler::on_connection_open().

void stop ( const error_condition err)

Experimental - Stop the container with an error_condition err.

  • Abort all open connections and listeners.
  • Process final handler events and injected functions
  • If !err.empty(), handlers will receive on_transport_error
  • run() will return in all threads.
void stop ( )

Experimental - Stop the container with an empty error condition.

See Also
stop(const error_condition&)

The documentation for this class was generated from the following file: