senf::ClientSocketHandle< SPolicy > Class Template Reference
[The Handle Hierarchy]

Generic SocketHandle with client interface. More...

#include <senf/Socket/ClientSocketHandle.hh>

Inheritance diagram for senf::ClientSocketHandle< SPolicy >:
Inheritance graph
[legend]

List of all members.

Detailed Description

template<class SPolicy>
class senf::ClientSocketHandle< SPolicy >

Generic SocketHandle with client interface.

This class provides the client side policy interface of the socket abstraction. ClientSocketHandle defines the complete policy interface. It does not implement any functionality itself however. The following table shows, to which policy members each group of ClientSocketHandle members is forwarded. The last column shows, on which other policies this member-group depends in the default policy classes. If you define your own policy classes, the dependencies are up to you.

ClientSocketHandle member Policy member Other policies
read() ReadPolicy::read (senf::ReadPolicyBase)
readfrom() ReadPolicy::readfrom (senf::ReadPolicyBase) UnconnectedCommunicationPolicy
write() WritePolicy::write (senf::WritePolicyBase) ConnectedCommunicationPolicy
writeto() WritePolicy::writeto (senf::WritePolicyBase) UnconnectedCommunicationPolicy
connect() AddressingPolicy::connect (senf::AddressingPolicyBase)
bind() AddressingPolicy::bind (senf::AddressingPolicyBase)
peer() AddressingPolicy::peer (senf::AddressingPolicyBase)
local() AddressingPolicy::local (senf::AddressingPolicyBase)

It is important to note, that not all members are always accessible. Which are depends on the Policy template argument. If any of the policy axis is left unspecified the corresponding members will not be callable (you will get a compile time error). Even if every policy axis is defined, some members might (and will) not exist if they are meaningless for the protocol of the socket. This depends on the exact policy.

To find out, which members are available, you have to check the documentation of the policy classes. You can also find a summary of all members available in the leaf protocol class documentation.

Todo:
Move all not template-parameter dependent code into a non-template base class
Idea:
Give SocketHandle (and therefore ClientSocketHandle and ServerSocketHandle) a protocol() template member and an additional template arg Policies. This arg should be a typelist of policy classes which can be accessed. You use protocol<ProtocolClass>() to access a protocol class. Policies can of course be underspecified or even empty.
See also:
The Policy Framework
The Protocol Classes

Definition at line 89 of file ClientSocketHandle.hh.


Public Types
typedef
SPolicy::AddressingPolicy::Address 		 Address
  Address type from the addressing policy.
typedef boost::call_traits
< Address >::param_type 		 AddressParam
  'Best' type for passing address as parameter
typedef ServerSocketHandle
< SPolicy > 		 ServerHandle
  Corresponding server socket handle with the same policy.

Public Member Functions
void  state (SocketStateMap &map, unsigned lod=0)
  Inquire state information of socket handle.
std::string  dumpState (unsigned lod=0)
  Format complete state information as string.
unsigned  available ()

Static Public Member Functions
static ClientSocketHandle  cast_static (FileHandle handle)
static ClientSocketHandle  cast_dynamic (FileHandle handle)

Structors and default members
  ClientSocketHandle ()
  ClientSocketHandle (ClientSocketHandle< OtherPolicy > other)
template<class OtherPolicy >
ClientSocketHandle
< OtherPolicy > const & 		 operator= (ClientSocketHandle< OtherPolicy > other)

Reading and Writing
std::string  read (unsigned limit=0)
  Read data from socket.
template<class ForwardWritableRange >
boost::range_iterator
< ForwardWritableRange >::type 		 read (ForwardWritableRange const &range)
  Read data into range.
template<class ForwardWritableRange >
boost::range_iterator
< ForwardWritableRange >::type 		 read (ForwardWritableRange &range)
  Read data into range.
template<class Sequence >
void  read (Sequence &container, unsigned limit)
  Read data into container.
char *  read (char *start, char *end)
  Read data into memory area.
std::pair< std::string, Address >  readfrom (unsigned limit=0)
  Read data from unconnected socket returning address.
template<class ForwardWritableRange >
boost::range_iterator
< ForwardWritableRange const >
::type 		 readfrom (ForwardWritableRange const &range, Address &from)
  Read data into range.
template<class ForwardWritableRange >
boost::range_iterator
< ForwardWritableRange >::type 		 readfrom (ForwardWritableRange &range, Address &from)
  Read data into range.
template<class Sequence >
void  readfrom (Sequence &container, Address &from, unsigned limit)
  Read data into container.
char *  readfrom (char *start, char *end, Address &from)
  Read data into memory buffer.
template<class ForwardReadableRange >
boost::range_const_iterator
< ForwardReadableRange const >
::type 		 write (ForwardReadableRange const &range)
  Write data to socket.
char const *  write (char const *start, char const *end)
  Write data to socket from memory buffer.
template<class ForwardReadableRange >
boost::range_const_iterator
< ForwardReadableRange const >
::type 		 writeto (AddressParam addr, ForwardReadableRange const &range)
  Write data to unconnected socket.
char const *  writeto (AddressParam addr, char const *start, char const *end)
  Write data from memory buffer to unconnected socket.

Addressing
void  connect (AddressParam addr) const
  Connect to remote peer.
void  bind (AddressParam addr) const
  Set local address.
Address  peer () const
  Query remote address.
void  peer (Address &addr) const
  Query remote address.
Address  local () const
  Query local address.
void  local (Address &addr) const
  Query local address.

Protected Member Functions
  ClientSocketHandle (FileHandle other, bool isChecked)
  ClientSocketHandle (std::auto_ptr< SocketBody > body)

Member Typedef Documentation

template<class SPolicy>
typedef SPolicy::AddressingPolicy::Address senf::ClientSocketHandle< SPolicy >::
Address

Address type from the addressing policy.

Definition at line 97 of file ClientSocketHandle.hh.

template<class SPolicy>
typedef boost::call_traits<Address>::param_type senf::ClientSocketHandle< SPolicy >::
AddressParam

'Best' type for passing address as parameter

Depending on the type of Address, this will be either Address or Address const &. See call_traits documentation in the Boost.Utility library.

Definition at line 104 of file ClientSocketHandle.hh.

template<class SPolicy>
typedef ServerSocketHandle<SPolicy> senf::ClientSocketHandle< SPolicy >::
ServerHandle

Corresponding server socket handle with the same policy.

This class will probably only be usable, if the CommunicationPolicy is ConnectedCommunicationPolicy and the AddressingPolicy is not NoAddressingPolicy.

Definition at line 109 of file ClientSocketHandle.hh.

Constructor & Destructor Documentation

template<class SPolicy >
senf::ClientSocketHandle< SPolicy >::
ClientSocketHandle ()

Definition at line 101 of file ClientSocketHandle.cti.

template<class SPolicy>
senf::ClientSocketHandle< SPolicy >::
ClientSocketHandle ( ClientSocketHandle< OtherPolicy >  other )

Definition at line 116 of file ClientSocketHandle.cti.

template<class SPolicy >
senf::ClientSocketHandle< SPolicy >::
ClientSocketHandle ( FileHandle  other,
bool  isChecked )

Definition at line 121 of file ClientSocketHandle.cti.

template<class SPolicy >
senf::ClientSocketHandle< SPolicy >::
ClientSocketHandle ( std::auto_ptr< SocketBody >  body )

Definition at line 127 of file ClientSocketHandle.cti.

Member Function Documentation

template<class SPolicy >
unsigned senf::ClientSocketHandle< SPolicy >::
available ()

Definition at line 146 of file ClientSocketHandle.ct.

template<class SPolicy >
void senf::ClientSocketHandle< SPolicy >::
bind ( AddressParam  addr )

Set local address.

For addressable protocols (AddressingPolicy is not NoAddressingPolicy), bind() will set the local address of the socket.

Parameters:
[in]  addr  Local socket address to assign
Exceptions:
senf::SystemException 

Definition at line 347 of file ClientSocketHandle.cti.

template<class SPolicy >
senf::ClientSocketHandle< SPolicy > senf::ClientSocketHandle< SPolicy >::
cast_dynamic ( FileHandle  handle )

For internal use only.

Reimplemented from senf::SocketHandle< SPolicy >.

Reimplemented in senf::ProtocolClientSocketHandle< SocketProtocol >, and senf::ProtocolClientSocketHandle< DVBFrontendSocketProtocol >.

Definition at line 365 of file ClientSocketHandle.cti.

template<class SPolicy >
senf::ClientSocketHandle< SPolicy > senf::ClientSocketHandle< SPolicy >::
cast_static ( FileHandle  handle )

For internal use only.

Reimplemented from senf::SocketHandle< SPolicy >.

Reimplemented in senf::ProtocolClientSocketHandle< SocketProtocol >, and senf::ProtocolClientSocketHandle< DVBFrontendSocketProtocol >.

Definition at line 358 of file ClientSocketHandle.cti.

template<class SPolicy >
void senf::ClientSocketHandle< SPolicy >::
connect ( AddressParam  addr )

Connect to remote peer.

This member will establish a connection for addressable connection-oriented protocols (that is, the CommunicationPolicy is ConnectedCommunicationPolicy and the AddressingPolicy is not NoAddressingPolicy).

Parameters:
[in]  addr  Address to connect to
Exceptions:
senf::SystemException 

Definition at line 338 of file ClientSocketHandle.cti.

template<class SPolicy >
std::string senf::ClientSocketHandle< SPolicy >::
dumpState ( unsigned  lod = 0 )

Format complete state information as string.

Formats the complete state map value and returns it as a single multi-line string.

Parameters:
lod  level of detail requested. The interpretation of this value is protocol specific
Implementation note:
This member will be re-implemented in every derived class. See the state() documentation.

Reimplemented from senf::SocketHandle< SPolicy >.

Reimplemented in senf::ProtocolClientSocketHandle< SocketProtocol >, and senf::ProtocolClientSocketHandle< DVBFrontendSocketProtocol >.

Definition at line 388 of file ClientSocketHandle.cti.

template<class SPolicy >
void senf::ClientSocketHandle< SPolicy >::
local ( Address &  addr )

Query local address.

See also:
local()

Definition at line 329 of file ClientSocketHandle.cti.

template<class SPolicy >
SPolicy::AddressingPolicy::Address senf::ClientSocketHandle< SPolicy >::
local ()

Query local address.

This member will return the address of the local socket in addressable protocols (AddressingPolicy is not NoAddressingPolicy).

There are two Variants of this member, one will return the address by value, the other takes a reference argument to elide the copy operation.

Exceptions:
senf::SystemException 

Definition at line 319 of file ClientSocketHandle.cti.

template<class SPolicy >
template<class OtherPolicy >
OtherPolicy const & senf::ClientSocketHandle< SPolicy >::
operator= ( ClientSocketHandle< OtherPolicy >  other )

Definition at line 144 of file ClientSocketHandle.cti.

template<class SPolicy >
void senf::ClientSocketHandle< SPolicy >::
peer ( Address &  addr )

Query remote address.

See also:
peer()

Definition at line 309 of file ClientSocketHandle.cti.

template<class SPolicy >
SPolicy::AddressingPolicy::Address senf::ClientSocketHandle< SPolicy >::
peer ()

Query remote address.

This member will return the address of the communication partner in addressable connection-oriented protocols (that is, the CommunicationPolicy is ConnectedCommunicationPolicy and the AddressingPolicy is not NoAddressingPolicy).

There are two Variants of this member, one will return the address by value, the other takes a reference argument to elide the copy operation.

Exceptions:
senf::SystemException 

Definition at line 299 of file ClientSocketHandle.cti.

template<class SPolicy >
char * senf::ClientSocketHandle< SPolicy >::
read ( char *  start,
char *  end )

Read data into memory area.

This variant will read data into the memory area from start to before end. This is guaranteed to be the most efficient version of read().

Parameters:
[in]  start  address of buffer to store data at
[in]  end  address one past the end of the buffer
Returns:
pointer past the end of the data read
See also:
read()

Definition at line 204 of file ClientSocketHandle.cti.

template<class SPolicy >
template<class Sequence >
void senf::ClientSocketHandle< SPolicy >::
read ( Sequence &  container,
unsigned  limit )

Read data into container.

The data read is written into the given container. Old data in the container will be removed. For this to work, the container must be a model of 'Sequence' as defined in the STL documentation

Parameters:
[out]  container  Container to write data to
[in]  limit  Maximum number of characters to read
See also:
read()

Definition at line 107 of file ClientSocketHandle.ct.

template<class SPolicy >
template<class ForwardWritableRange >
boost::range_iterator< ForwardWritableRange >::type senf::ClientSocketHandle< SPolicy >::
read ( ForwardWritableRange &  range )

Read data into range.

See also:
read(ForwardWritableRange const &)
read()
Boost.Range

Definition at line 199 of file ClientSocketHandle.cti.

template<class SPolicy >
template<class ForwardWritableRange >
boost::range_iterator< ForwardWritableRange >::type senf::ClientSocketHandle< SPolicy >::
read ( ForwardWritableRange const &  range )

Read data into range.

Read data into the given range. At most boost::size(range) characters are read. The data read will start at the beginning of the range. read returns a past-the-end iterator after the last character read. This iterator will point to somewhere within the input range.

Parameters:
[in,out]  range  Range to store data in
Returns:
past-the-end iterator pointer to after the last read character
See also:
read()
Boost.Range

Definition at line 174 of file ClientSocketHandle.cti.

template<class SPolicy >
std::string senf::ClientSocketHandle< SPolicy >::
read ( unsigned  limit = 0 )

Read data from socket.

If the sockets FramingPolicy is DatagramFramingPolicy, every read() command will return a single datagram. If the sockets FramingPolicy is StreamFraming, the operation will return as much data as possible from the socket buffer. However it cannot be guaranteed, that the socket buffer will be empty after read() returns.

Attention:
If the space available for the data read is limited, the read will return no more than that amount of data. For a datagram socket, a full datagram is still dequeued from the socket buffer, the remainder of the datagram will be lost.
There are several variants of read which differ in how they return the read string.

If the further document doesn't tell something differently, on a blocking socket the members will always return some data (as long as the socket has not been closed at the other end) and will block, if no data is available now. If you do not want to block, you must make the socket non-blocking (using FileHandle::blocking()).

Exceptions:
senf::SystemException  This variant will read up to limit bytes from the socket and return them as a std::string object.
Parameters:
[in]  limit  Maximum number of bytes to read or 0 if unlimited.
Returns:
data read
Implementation note:
The read() family of members will use standard POSIX read calls, not recv.

Definition at line 98 of file ClientSocketHandle.ct.

template<class SPolicy >
char * senf::ClientSocketHandle< SPolicy >::
readfrom ( char *  start,
char *  end,
Address &  from )

Read data into memory buffer.

This variant will read data into the memory area from start to before end. This is guaranteed to be the most efficient version of readfrom().

Parameters:
[in]  start  address of buffer to store data at
[in]  end  address one past the end of the buffer
[out]  from  peers address from which the data was received
Returns:
pointer past the end of the data read
See also:
read()

Definition at line 240 of file ClientSocketHandle.cti.

template<class SPolicy >
template<class Sequence >
void senf::ClientSocketHandle< SPolicy >::
readfrom ( Sequence &  container,
Address &  from,
unsigned  limit )

Read data into container.

The data read is written into the given container. Old data in the container will be removed. For this to work, the container must be a model of 'Sequence' as defined in the STL documentation

Parameters:
[out]  container  Container to write data to
[in]  limit  Maximum number of characters to read
[out]  from  peers address from which the data was received
See also:
readfrom()

Definition at line 130 of file ClientSocketHandle.ct.

template<class SPolicy >
template<class ForwardWritableRange >
boost::range_iterator< ForwardWritableRange >::type senf::ClientSocketHandle< SPolicy >::
readfrom ( ForwardWritableRange &  range,
Address &  from )

Read data into range.

See also:
readfrom(ForwardWritableRange const&,Address&)
readfrom()
Boost.Range

Definition at line 228 of file ClientSocketHandle.cti.

template<class SPolicy >
template<class ForwardWritableRange >
boost::range_iterator< ForwardWritableRange const >::type senf::ClientSocketHandle< SPolicy >::
readfrom ( ForwardWritableRange const &  range,
Address &  from )

Read data into range.

Read data into the given range. At most boost::size(range) characters are read. The data read will start at the beginning of the range. read returns a past-the-end iterator after the last character read. This iterator will point to somewhere within the input range.

Parameters:
[in,out]  range  Range to store data in
[out]  from  peers address from which the data was received
Returns:
past-the-end iterator pointer to after the last read character
See also:
readfrom()
Boost.Range

Definition at line 214 of file ClientSocketHandle.cti.

template<class SPolicy >
std::pair< std::string, typename SPolicy::AddressingPolicy::Address > senf::ClientSocketHandle< SPolicy >::
readfrom ( unsigned  limit = 0 )

Read data from unconnected socket returning address.

The readfrom() group of member behaves like read() but should only be available, if the sockets CommunicationPolicy is UnconnectedCommunicationPolicy and the AddressingPolicy is not NoAddressingPolicy. readfrom() will in addition to the data return the address of the sender.

Exceptions:
senf::SystemException  This variant will return the data read and the address as a std::pair.
Returns:
std::pair of data read (a string) and the peers address
Implementation note:
The readfrom() family of members will use recvfrom from the BSD socket API.

Definition at line 120 of file ClientSocketHandle.ct.

template<class SPolicy >
void senf::ClientSocketHandle< SPolicy >::
state ( SocketStateMap &  map,
unsigned  lod = 0 )

Inquire state information of socket handle.

The map argument (a string to string mapping) will be filled with information covering the current state of the socket. The information provided depends on the socket protocol. The amount of information returned can be controlled using the lod value.

See senf::SocketProtocol::state() for more information, how the Information is generated.

Parameters:
map  string to string mapping to be filled with state information
lod  level of detail requested. The interpretation of this value is protocol specific
Implementation note:
This member will be re-implemented in every derived class. This is very important since state() is not a virtual function (which we don't want since we don't want to add a vtable pointer to every handle instance).

Reimplemented from senf::SocketHandle< SPolicy >.

Reimplemented in senf::ProtocolClientSocketHandle< SocketProtocol >, and senf::ProtocolClientSocketHandle< DVBFrontendSocketProtocol >.

Definition at line 377 of file ClientSocketHandle.cti.

template<class SPolicy >
char const * senf::ClientSocketHandle< SPolicy >::
write ( char const *  start,
char const *  end )

Write data to socket from memory buffer.

Parameters:
[in]  start  beginning of area to write
[in]  end  past-the-end pointer to area to write
Returns:
past-the-end pointer after last byte written
See also:
write()
Boost.Range

Definition at line 263 of file ClientSocketHandle.cti.

template<class SPolicy >
template<class ForwardReadableRange >
boost::range_const_iterator< ForwardReadableRange const >::type senf::ClientSocketHandle< SPolicy >::
write ( ForwardReadableRange const &  range )

Write data to socket.

The write() family of members will write out the data to the socket. If the sockets FramingPolicy is DatagramFramingPolicy, every write() call will result in one datagram.

A single write call might depending on the circumstances write only part of the data.

There are two variants of this member

Exceptions:
senf::SystemException  This variant will write out the range data.
Parameters:
[in]  range  Data to write
Returns:
past-the-end iterator after last element written
Implementation note:
The write() family of members will use POSIX write calls, not send.

Definition at line 251 of file ClientSocketHandle.cti.

template<class SPolicy >
char const * senf::ClientSocketHandle< SPolicy >::
writeto ( AddressParam  addr,
char const *  start,
char const *  end )

Write data from memory buffer to unconnected socket.

Parameters:
[in]  addr  Address of peer to send data to
[in]  start  address of buffer to write
[in]  end  past-the-end pointer after data to write
Returns:
past-the-end iterator after last byte written
See also:
writeto()
Boost.Range

Definition at line 285 of file ClientSocketHandle.cti.

template<class SPolicy >
template<class ForwardReadableRange >
boost::range_const_iterator< ForwardReadableRange const >::type senf::ClientSocketHandle< SPolicy >::
writeto ( AddressParam  addr,
ForwardReadableRange const &  range )

Write data to unconnected socket.

This member behaves like write() but should only be available, if the sockets CommunicationPolicy is UnconnectedCommunicationPolicy and the AddressingPolicy is not NoAddressingPolicy. The writeto() family of members takes the target address as an additional argument.

There are two variants of this member.

Exceptions:
senf::SystemException  This variant will send the range range to peer addr.
Parameters:
[in]  addr  Address of peer to send data to
[in]  range  data to send
Returns:
Number of bytes written

Definition at line 273 of file ClientSocketHandle.cti.

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