/** * @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 "apr_pools.h" #include "apr_network_io.h" #include "llchainio.h" 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 boost::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 * @return A valid socket shared pointer if the call worked. */ static ptr_t create( apr_pool_t* pool, EType type, U16 port = PORT_EPHEMERAL); /** * @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 boost::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