/**
* @file lliosocket.h
* @author Phoenix
* @date 2005-07-31
* @brief Declaration of files used for handling sockets and associated pipes
*
* $LicenseInfo:firstyear=2005&license=viewerlgpl$
* Second Life Viewer Source Code
* Copyright (C) 2010, Linden Research, Inc.
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation;
* version 2.1 of the License only.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
* License along with this library; if not, write to the Free Software
* Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
*
* Linden Research, Inc., 945 Battery Street, San Francisco, CA 94111 USA
* $/LicenseInfo$
*/
#ifndef LL_LLIOSOCKET_H
#define LL_LLIOSOCKET_H
/**
* The socket interface provided here is a simple wraper around apr
* sockets, with a pipe source and sink to read and write off of the
* socket. Every socket only performs non-blocking operations except
* the server socket which only performs blocking operations when an
* OS poll indicates it will not block.
*/
#include "lliopipe.h"
#include "llwin32headerslean.h"
#include "apr_pools.h"
#include "apr_network_io.h"
#include "llchainio.h"
extern const std::string CONTEXT_REMOTE_HOST;
extern const std::string CONTEXT_REMOTE_PORT;
class LLHost;
/**
* @class LLSocket
* @brief Implementation of a wrapper around a socket.
*
* An instance of this class represents a single socket over it's
* entire life - from uninitialized, to connected, to a listening
* socket depending on it's purpose. This class simplifies our access
* into the socket interface by only providing stream/tcp and
* datagram/udp sockets - the only types we are interested in, since
* those are the only properly supported by all of our platforms.
*/
class LLSocket
{
public:
/**
* @brief Reference counted shared pointers to sockets.
*/
typedef std::shared_ptr<LLSocket> ptr_t;
/**
* @brief Type of socket to create.
*/
enum EType
{
STREAM_TCP,
DATAGRAM_UDP,
};
/**
* @brief Anonymous enumeration to help identify ports
*/
enum
{
PORT_INVALID = (U16)-1,
PORT_EPHEMERAL = 0,
};
/**
* @brief Create a socket.
*
* This is the call you would use if you intend to create a listen
* socket. If you intend the socket to be known to external
* clients without prior port notification, do not use
* PORT_EPHEMERAL.
* @param pool The apr pool to use. A child pool will be created
* and associated with the socket.
* @param type The type of socket to create
* @param port The port for the socket
* @param hostname e.g. APR_ANYADDR to listen openly, or "127.0.0.1"
* @return A valid socket shared pointer if the call worked.
*/
static ptr_t create(
apr_pool_t* pool,
EType type,
U16 port = PORT_EPHEMERAL,
const char *hostname = APR_ANYADDR);
/**
* @brief Create a LLSocket when you already have an apr socket.
*
* This method assumes an ephemeral port. This is typically used
* by calls which spawn a socket such as a call to
* <code>accept()</code> as in the server socket. This call should
* not fail if you have a valid apr socket.
* Because of the nature of how accept() works, you are expected
* to create a new pool for the socket, use that pool for the
* accept, and pass it in here where it will be bound with the
* socket and destroyed at the same time.
* @param socket The apr socket to use
* @param pool The pool used to create the socket. *NOTE: The pool
* passed in will be DESTROYED.
* @return A valid socket shared pointer if the call worked.
*/
static ptr_t create(apr_socket_t* socket, apr_pool_t* pool);
/**
* @brief Perform a blocking connect to a host. Do not use in production.
*
* @param host The host to connect this socket to.
* @return Returns true if the connect was successful.
*/
bool blockingConnect(const LLHost& host);
/**
* @brief Get the type of socket
*/
//EType getType() const { return mType; }
/**
* @brief Get the port.
*
* This will return PORT_EPHEMERAL if bind was never called.
* @return Returns the port associated with this socket.
*/
U16 getPort() const { return mPort; }
/**
* @brief Get the apr socket implementation.
*
* @return Returns the raw apr socket.
*/
apr_socket_t* getSocket() const { return mSocket; }
/**
* @brief Set default socket options, with SO_NONBLOCK = 0 and a timeout in us.
* @param timeout Number of microseconds to wait on this socket. Any
* negative number means block-forever. TIMEOUT OF 0 IS NON-PORTABLE.
*/
void setBlocking(S32 timeout);
/**
* @brief Set default socket options, with SO_NONBLOCK = 1 and timeout = 0.
*/
void setNonBlocking();
protected:
/**
* @brief Protected constructor since should only make sockets
* with one of the two <code>create()</code> calls.
*/
LLSocket(apr_socket_t* socket, apr_pool_t* pool);
public:
/**
* @brief Do not call this directly.
*/
~LLSocket();
protected:
// The apr socket.
apr_socket_t* mSocket;
// our memory pool
apr_pool_t* mPool;
// The port if we know it.
U16 mPort;
//EType mType;
};
/**
* @class LLIOSocketReader
* @brief An LLIOPipe implementation which reads from a socket.
* @see LLIOPipe
*
* An instance of a socket reader wraps around an LLSocket and
* performs non-blocking reads and passes it to the next pipe in the
* chain.
*/
class LLIOSocketReader : public LLIOPipe
{
public:
LLIOSocketReader(LLSocket::ptr_t socket);
~LLIOSocketReader();
protected:
/* @name LLIOPipe virtual implementations
*/
//@{
/**
* @brief Process the data coming in the socket.
*
* Since the socket and next pipe must exist for process to make
* any sense, this method will return STATUS_PRECONDITION_NOT_MET
* unless if they are not known.
* If a STATUS_STOP returned by the next link in the chain, this
* reader will turn of the socket polling.
* @param buffer Pointer to a buffer which needs processing. Probably NULL.
* @param bytes Number of bytes to in buffer to process. Probably 0.
* @param eos True if this function is the last. Almost always false.
* @param read Number of bytes actually processed.
* @param pump The pump which is calling process. May be NULL.
* @param context A data structure to pass structured data
* @return STATUS_OK unless the preconditions are not met.
*/
virtual EStatus process_impl(
const LLChannelDescriptors& channels,
buffer_ptr_t& buffer,
bool& eos,
LLSD& context,
LLPumpIO* pump);
//@}
protected:
LLSocket::ptr_t mSource;
std::vector<U8> mBuffer;
bool mInitialized;
};
/**
* @class LLIOSocketWriter
* @brief An LLIOPipe implementation which writes to a socket
* @see LLIOPipe
*
* An instance of a socket writer wraps around an LLSocket and
* performs non-blocking writes of the data passed in.
*/
class LLIOSocketWriter : public LLIOPipe
{
public:
LLIOSocketWriter(LLSocket::ptr_t socket);
~LLIOSocketWriter();
protected:
/* @name LLIOPipe virtual implementations
*/
//@{
/**
* @brief Write the data in buffer to the socket.
*
* Since the socket pipe must exist for process to make any sense,
* this method will return STATUS_PRECONDITION_NOT_MET if it is
* not known.
* @param buffer Pointer to a buffer which needs processing.
* @param bytes Number of bytes to in buffer to process.
* @param eos True if this function is the last.
* @param read Number of bytes actually processed.
* @param pump The pump which is calling process. May be NULL.
* @param context A data structure to pass structured data
* @return A return code for the write.
*/
virtual EStatus process_impl(
const LLChannelDescriptors& channels,
buffer_ptr_t& buffer,
bool& eos,
LLSD& context,
LLPumpIO* pump);
//@}
protected:
LLSocket::ptr_t mDestination;
U8* mLastWritten;
bool mInitialized;
};
/**
* @class LLIOServerSocket
* @brief An IOPipe implementation which listens and spawns connected
* sockets.
* @see LLIOPipe, LLChainIOFactory
*
* Each server socket instance coordinates with a pump to ensure it
* only processes waiting connections. It uses the provided socket,
* and assumes it is correctly initialized. When the connection is
* established, the server will call the chain factory to build a
* chain, and attach a socket reader and the front and a socket writer
* at the end. It is up to the chain factory to create something which
* correctly handles the established connection using the reader as a
* source, and the writer as the final sink.
* The newly added chain timeout is in DEFAULT_CHAIN_EXPIRY_SECS unless
* adjusted with a call to setResponseTimeout().
*/
class LLIOServerSocket : public LLIOPipe
{
public:
typedef LLSocket::ptr_t socket_t;
typedef std::shared_ptr<LLChainIOFactory> factory_t;
LLIOServerSocket(apr_pool_t* pool, socket_t listener, factory_t reactor);
virtual ~LLIOServerSocket();
/**
* @brief Set the timeout for the generated chains.
*
* This value is passed directly to the LLPumpIO::addChain()
* method. The default on construction is set to
* DEFAULT_CHAIN_EXPIRY_SECS which is a reasonable value for most
* applications based on this library. Avoid passing in
* NEVER_CHAIN_EXPIRY_SECS unless you have another method of
* harvesting chains.
* @param timeout_secs The seconds before timeout for the response chain.
*/
void setResponseTimeout(F32 timeout_secs);
/* @name LLIOPipe virtual implementations
*/
//@{
protected:
/**
* @brief Process the data in buffer
*/
virtual EStatus process_impl(
const LLChannelDescriptors& channels,
buffer_ptr_t& buffer,
bool& eos,
LLSD& context,
LLPumpIO* pump);
//@}
protected:
apr_pool_t* mPool;
socket_t mListenSocket;
factory_t mReactor;
bool mInitialized;
F32 mResponseTimeout;
};
#if 0
/**
* @class LLIODataSocket
* @brief BRIEF_DESC
*
* THOROUGH_DESCRIPTION
*/
class LLIODataSocket : public LLIOSocket
{
public:
/**
* @brief Construct a datagram socket.
*
* If you pass in LLIOSocket::PORT_EPHEMERAL as the suggested
* port, The socket will not be in a 'listen' mode, but can still
* read data sent back to it's port. When suggested_port is not
* ephemeral or invalid and bind fails, the port discovery
* algorithm will search through a limited set of ports to
* try to find an open port. If that process fails, getPort() will
* return LLIOSocket::PORT_INVALID
* @param suggested_port The port you would like to bind. Use
* LLIOSocket::PORT_EPHEMERAL for an unspecified port.
* @param start_discovery_port The start range for
* @param pool The pool to use for allocation.
*/
LLIODataSocket(
U16 suggested_port,
U16 start_discovery_port,
apr_pool_t* pool);
virtual ~LLIODataSocket();
protected:
private:
apr_socket_t* mSocket;
};
#endif
#endif // LL_LLIOSOCKET_H