local_socket.h 5.37 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25
// Copyright (C) 2013  Internet Systems Consortium, Inc. ("ISC")
//
// Permission to use, copy, modify, and/or distribute this software for any
// purpose with or without fee is hereby granted, provided that the above
// copyright notice and this permission notice appear in all copies.
//
// THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
// REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
// AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
// INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
// LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
// OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
// PERFORMANCE OF THIS SOFTWARE.

#ifndef LOCAL_SOCKET_H
#define LOCAL_SOCKET_H 1

#include <asiolink/io_socket.h>
#include <asiolink/io_service.h>

#include <boost/noncopyable.hpp>

namespace isc {
namespace asiolink {

JINMEI Tatuya's avatar
JINMEI Tatuya committed
26 27 28 29 30 31 32 33
/// \brief A wrapper for ASIO stream socket in the local (AF_UNIX) domain.
///
/// This class provides a simple, limited set of wrapper interfaces to an
/// ASIO stream socket object in the local domain.  Unlike other concrete
/// derived classes of \c IOSocket, this class is intended to be instantiated
/// directly.  Right now it only provides read interface due to the limited
/// expected usage, but it can be extended as we see need for other operations
/// on this socket.
34 35 36 37
///
/// Note that in the initial implementation there's even no stop() or cancel()
/// method; for these cases users are expected to just destroy the socket
/// object (this may be extended in future, too).
38 39
class LocalSocket : boost::noncopyable, public IOSocket {
public:
JINMEI Tatuya's avatar
JINMEI Tatuya committed
40 41
    /// \brief Constructor from a native file descriptor of AF_UNIX stream
    /// socket.
42
    ///
JINMEI Tatuya's avatar
JINMEI Tatuya committed
43 44 45 46 47 48 49 50 51 52 53
    /// Parameter \c fd must be an open stream-type socket of the AF_UNIX
    /// domain.  The constructor tries to detect some invalid cases, but
    /// it may not reject all invalid cases.  It's generally the
    /// responsibility of the caller.
    ///
    /// \throw IOError Failed to create the socket object, most likely because
    /// the given file descriptor is invalid.
    ///
    /// \param io_service The IO service object to handle events on this
    /// socket.
    /// \param fd File descriptor of an AF_UNIX socket.
54 55
    LocalSocket(IOService& io_service, int fd);

JINMEI Tatuya's avatar
JINMEI Tatuya committed
56
    /// \brief Destructor.
JINMEI Tatuya's avatar
JINMEI Tatuya committed
57 58
    ///
    /// \throw None.
59 60
    virtual ~LocalSocket();

JINMEI Tatuya's avatar
JINMEI Tatuya committed
61
    /// \brief Local socket version of getNative().
JINMEI Tatuya's avatar
JINMEI Tatuya committed
62 63
    ///
    /// \throw None.
64 65
    virtual int getNative() const;

JINMEI Tatuya's avatar
JINMEI Tatuya committed
66 67 68
    /// \brief Local socket version of getProtocol().
    ///
    /// It always returns \c AF_UNIX.
JINMEI Tatuya's avatar
JINMEI Tatuya committed
69 70
    ///
    /// \throw None.
71 72
    virtual int getProtocol() const;

JINMEI Tatuya's avatar
JINMEI Tatuya committed
73 74 75 76 77
    /// \brief The callback functor for the \c asyncRead method.
    ///
    /// The callback takes one parameter, \c error.  It will be set to
    /// non empty string if read operation fails and the string explains
    /// the reason for the failure.  On success \c error will be empty.
78
    typedef boost::function<void(const std::string& error)> ReadCallback;
JINMEI Tatuya's avatar
JINMEI Tatuya committed
79 80 81

    /// \brief Start asynchronous read on the socket.
    ///
JINMEI Tatuya's avatar
JINMEI Tatuya committed
82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112
    /// This method registers an interest on a new read event on the local
    /// socket for the specified length of data (\c buflen bytes).  This
    /// method returns immediately.   When the specified amount of data
    /// are available for read from the socket or an error happens, the
    /// specified callback will be called.  In the former case the data are
    /// copied into the given buffer (pointed to by \c buf); in the latter
    /// case, the \c error parameter of the callback will be set to a non
    /// empty string.
    ///
    /// In the case of error, this socket should be considered
    /// unusable anymore, because this class doesn't provide a feasible way
    /// to identify where in the input stream to restart reading.  So,
    /// in practice, the user of this socket should destroy this socket,
    /// and, if necessary to continue, create a new one.
    ///
    /// \c buf must point to a memory region that has at least \c buflen
    /// bytes of valid space.  That region must be kept valid until the
    /// callback is called or the \c IOService passed to the constructor
    /// is stopped.  This method and class do not check these conditions;
    /// it's the caller's responsibility to guarantee them.
    ///
    /// \note If asyncRead() has been called and hasn't been completed (with
    /// the callback being called), it's possible that the callback is called
    /// even after the \c LocalSocket object is destroyed.  So the caller
    /// has to make sure that either \c LocalSocket is valid until the
    /// callback is called or the callback does not depend on \c LocalSocket;
    /// alternatively, the caller can stop the \c IOService.  This will make
    /// sure the callback will not be called regardless of when and how
    /// the \c LocalSocket is destroyed.
    ///
    /// \throw None.
JINMEI Tatuya's avatar
JINMEI Tatuya committed
113
    ///
JINMEI Tatuya's avatar
JINMEI Tatuya committed
114 115 116 117
    /// \brief callback The callback functor to be called on the completion
    /// of read.
    /// \brief buf Buffer to read in data from the socket.
    /// \brief buflen Length of data to read.
118 119 120 121 122 123 124 125 126 127 128 129 130 131 132
    void asyncRead(const ReadCallback& callback, void* buf, size_t buflen);

private:
    class Impl;
    Impl* impl_;
};

} // namespace asiolink
} // namespace isc

#endif // LOCAL_SOCKET_H

// Local Variables:
// mode: c++
// End: