Raw connection
[IO]

**Unsettled API** - An API allowing raw sockets to be used with proactor More...

Classes

struct  pn_raw_buffer_t
 A descriptor used to represent a single raw buffer in memory. More...

Typedefs

typedef struct pn_raw_connection_t pn_raw_connection_t
 A raw network connection used with the proactor.

Functions

PNP_EXTERN pn_raw_connection_tpn_raw_connection (void)
 Create a new raw connection for use with the Proactor.
PNP_EXTERN struct pn_netaddr_tpn_raw_connection_local_addr (pn_raw_connection_t *connection)
 Get the local address of a raw connection.
PNP_EXTERN struct pn_netaddr_tpn_raw_connection_remote_addr (pn_raw_connection_t *connection)
 Get the local address of a raw connection.
PNP_EXTERN void pn_raw_connection_close (pn_raw_connection_t *connection)
 Close a raw connection.
PNP_EXTERN size_t pn_raw_connection_read_buffers_capacity (pn_raw_connection_t *connection)
 Query the raw connection for how many more read buffers it can be given.
PNP_EXTERN size_t pn_raw_connection_write_buffers_capacity (pn_raw_connection_t *connection)
 Query the raw connection for how many more write buffers it can be given.
PNP_EXTERN size_t pn_raw_connection_give_read_buffers (pn_raw_connection_t *connection, pn_raw_buffer_t const *buffers, size_t num)
 Give the raw connection buffers to use for reading from the underlying socket.
PNP_EXTERN size_t pn_raw_connection_take_read_buffers (pn_raw_connection_t *connection, pn_raw_buffer_t *buffers, size_t num)
 Fetch buffers with bytes read from the raw socket.
PNP_EXTERN size_t pn_raw_connection_write_buffers (pn_raw_connection_t *connection, pn_raw_buffer_t const *buffers, size_t num)
 Give the raw connection buffers to write to the underlying socket.
PNP_EXTERN size_t pn_raw_connection_take_written_buffers (pn_raw_connection_t *connection, pn_raw_buffer_t *buffers, size_t num)
 Return a buffer chain with buffers that have all been written to the raw socket.
PNP_EXTERN bool pn_raw_connection_is_read_closed (pn_raw_connection_t *connection)
 Is connection closed for read?
PNP_EXTERN bool pn_raw_connection_is_write_closed (pn_raw_connection_t *connection)
 Is connection closed for write?
PNP_EXTERN void pn_raw_connection_wake (pn_raw_connection_t *connection)
 Return a PN_RAW_CONNECTION_WAKE event for connection as soon as possible.
PNP_EXTERN pn_condition_tpn_raw_connection_condition (pn_raw_connection_t *connection)
 Get additional information about a raw connection error.
PNP_EXTERN void * pn_raw_connection_get_context (pn_raw_connection_t *connection)
 Get the application context associated with this raw connection.
PNP_EXTERN void pn_raw_connection_set_context (pn_raw_connection_t *connection, void *context)
 Set a new application context for a raw connection.
PNP_EXTERN pn_record_t * pn_raw_connection_attachments (pn_raw_connection_t *connection)
 Get the attachments that are associated with a raw connection.
PNP_EXTERN pn_raw_connection_tpn_event_raw_connection (pn_event_t *event)
 Return the raw connection associated with an event.

Detailed Description

**Unsettled API** - An API allowing raw sockets to be used with proactor


Function Documentation

PNP_EXTERN pn_raw_connection_t* pn_raw_connection ( void   ) 

Create a new raw connection for use with the Proactor.

See pn_proactor_raw_connect and pn_listener_raw_accept.

Returns:
A newly allocated pn_connection_t or NULL if there wasn't sufficient memory.
Note:
This is the only pn_connection_t function that allocates memory. So an application that wants good control of out of memory conditions should check the return value for NULL.
It would be a good practice is to create a raw connection and attach application specific context to it before giving it to the proactor.
There is no way to free a pn_connection_t as once passed to the proactor the proactor owns it and controls its lifecycle.
PNP_EXTERN struct pn_netaddr_t* pn_raw_connection_local_addr ( pn_raw_connection_t connection  )  [read]

Get the local address of a raw connection.

Return `NULL` if not available. Pointer is invalid after the transport closes (PN_RAW_CONNECTION_DISCONNECTED event is handled)

PNP_EXTERN struct pn_netaddr_t* pn_raw_connection_remote_addr ( pn_raw_connection_t connection  )  [read]

Get the local address of a raw connection.

Return `NULL` if not available. Pointer is invalid after the transport closes (PN_RAW_CONNECTION_DISCONNECTED event is handled)

PNP_EXTERN void pn_raw_connection_close ( pn_raw_connection_t connection  ) 

Close a raw connection.

This will close the underlying socket and release all buffers held by the raw connection. It will cause PN_RAW_CONNECTION_READ and PN_RAW_CONNECTION_WRITTEN to be emitted so the application can clean up buffers given to the raw connection. After that a PN_RAW_CONNECTION_DISCONNECTED event will be emitted to allow the application to clean up any other state held by the raw connection.

PNP_EXTERN size_t pn_raw_connection_give_read_buffers ( pn_raw_connection_t connection,
pn_raw_buffer_t const *  buffers,
size_t  num 
)

Give the raw connection buffers to use for reading from the underlying socket.

If the raw socket has no read buffers then the application will never receive a PN_RAW_CONNECTION_READ event.

A PN_RAW_CONNECTION_NEED_READ_BUFFERS event will be generated immediately after the PN_RAW_CONNECTION_CONNECTED event if there are no read buffers. It will also be generated whenever the raw connection runs out of read buffers. In both these cases the event will not be generated again until pn_raw_connection_give_read_buffers is called.

Returns:
the number of buffers actually given to the raw connection. This will only be different from the number supplied if the connection has no more space to record more buffers. In this case the buffers taken will be the earlier buffers in the array supplied, the elements 0 to the returned value-1.
Note:
The buffers given to the raw connection are owned by it until the application receives a PN_RAW_CONNECTION_READ event giving them back to the application. They must not be accessed at all (written or even read) from calling pn_raw_connection_give_read_buffers until receiving this event.
The application should not assume that the PN_RAW_CONNECTION_NEED_READ_BUFFERS event signifies that the connection is readable.
PNP_EXTERN size_t pn_raw_connection_take_read_buffers ( pn_raw_connection_t connection,
pn_raw_buffer_t buffers,
size_t  num 
)

Fetch buffers with bytes read from the raw socket.

Parameters:
[out] buffers pointer to an array of pn_raw_buffer_t structures which will be filled in with the read buffer information
[in] num the number of buffers allocated in the passed in array of buffers
Returns:
the number of buffers being returned, if there is are no read bytes then this will be 0. As many buffers will be returned as can be given the number that are passed in. So if the number returned is less than the number passed in there are no more buffers read. But if the number is the same there may be more read buffers to take.
Note:
After the application receives PN_RAW_CONNECTION_READ there should be bytes read from the socket and hence this call should return buffers. It is safe to carry on calling pn_raw_connection_take_read_buffers until it returns 0.
PNP_EXTERN size_t pn_raw_connection_write_buffers ( pn_raw_connection_t connection,
pn_raw_buffer_t const *  buffers,
size_t  num 
)

Give the raw connection buffers to write to the underlying socket.

A PN_RAW_CONNECTION_WRITTEN event will be generated once the buffers have been written to the socket until this point the buffers must not be accessed at all (written or even read).

A PN_RAW_CONNECTION_NEED_WRITE_BUFFERS event will be generated immediately after the PN_RAW_CONNECTION_CONNECTED event if there are no write buffers. It will also be generated whenever the raw connection finishes writing all the write buffers. In both these cases the event will not be generated again until pn_raw_connection_write_buffers is called.

Returns:
the number of buffers actually recorded by the raw connection to write. This will only be different from the number supplied if the connection has no more space to record more buffers. In this case the buffers recorded will be the earlier buffers in the array supplied, the elements 0 to the returned value-1.
PNP_EXTERN size_t pn_raw_connection_take_written_buffers ( pn_raw_connection_t connection,
pn_raw_buffer_t buffers,
size_t  num 
)

Return a buffer chain with buffers that have all been written to the raw socket.

Parameters:
[out] buffers pointer to an array of pn_raw_buffer_t structures which will be filled in with the written buffer information
[in] num the number of buffers allocated in the passed in array of buffers
Returns:
the number of buffers being returned, if there is are no written buffers to return then this will be 0. As many buffers will be returned as can be given the number that are passed in. So if the number returned is less than the number passed in there are no more buffers written. But if the number is the same there may be more written buffers to take.
Note:
After the application receives PN_RAW_CONNECTION_WRITTEN there should be bytes written to the socket and hence this call should return buffers. It is safe to carry on calling pn_raw_connection_take_written_buffers until it returns 0.
PNP_EXTERN bool pn_raw_connection_is_read_closed ( pn_raw_connection_t connection  ) 

Is connection closed for read?

Returns:
true if the raw connection is closed for read.
PNP_EXTERN bool pn_raw_connection_is_write_closed ( pn_raw_connection_t connection  ) 

Is connection closed for write?

Returns:
true if the raw connection is closed for write.
PNP_EXTERN void pn_raw_connection_wake ( pn_raw_connection_t connection  ) 

Return a PN_RAW_CONNECTION_WAKE event for connection as soon as possible.

At least one wake event will be returned, serialized with other Proactor events for the same raw connection. Wakes can be "coalesced" - if several pn_raw_connection_wake() calls happen close together, there may be only one PN_RAW_CONNECTION_WAKE event that occurs after all of them.

Note:
Thread-safe
PNP_EXTERN pn_condition_t* pn_raw_connection_condition ( pn_raw_connection_t connection  ) 

Get additional information about a raw connection error.

There is a raw connection error if the PN_RAW_CONNECTION_DISCONNECTED event is received and the pn_condition_t associated is non null (

See also:
pn_condition_is_set).

The value returned is only valid until the end of handler for the PN_RAW_CONNECTION_DISCONNECTED event.

PNP_EXTERN void* pn_raw_connection_get_context ( pn_raw_connection_t connection  ) 

Get the application context associated with this raw connection.

The application context for a raw connection may be set using pn_raw_connection_set_context.

Parameters:
[in] connection the raw connection whose context is to be returned.
Returns:
the application context for the raw connection
PNP_EXTERN void pn_raw_connection_set_context ( pn_raw_connection_t connection,
void *  context 
)

Set a new application context for a raw connection.

The application context for a raw connection may be retrieved using pn_raw_connection_get_context.

Parameters:
[in] connection the raw connection object
[in] context the application context
PNP_EXTERN pn_raw_connection_t* pn_event_raw_connection ( pn_event_t event  ) 

Return the raw connection associated with an event.

Returns:
NULL if the event is not associated with a raw connection.

Generated on 2 Oct 2020 for Qpid Proton C by  doxygen 1.6.1