Socket objects

## package lightblue:

### Socket objects

        A Bluetooth socket object has the same interface as a socket object from
        the Python standard library <socket> module. It also uses the same
        exceptions, raising socket.error for general errors and socket.timeout for
        timeout errors.

        Note that L2CAP sockets are not available on Python For Series 60, and
        only L2CAP client sockets are supported on Mac OS X and Linux.

        A simple client socket example:
            >>> from lightblue import *
            >>> s = socket()        # or socket(L2CAP) to create an L2CAP socket
            >>> s.connect(("00:12:2c:45:8a:7b", 5))
            >>> s.send("hello")
            5
            >>> s.close()
        A simple server socket example:
            >>> from lightblue import *
            >>> s = socket()
            >>> s.bind(("", 0))
            >>> s.listen(1)
            >>> advertise("My RFCOMM Service", s, RFCOMM)
            >>> conn, addr = s.accept()
            >>> print "Connected by", addr
            Connected by ('00:0D:93:19:C8:68', 5)
            >>> conn.recv(1024)
            "hello"
            >>> conn.close()
            >>> s.close()

## Methods

- accept()
- bind(address)
- close()
- connect(address)
- connect_ex(address)
- dup()
- fileno()
- getpeername()
- getsockname()
- getsockopt(level, option[, bufsize])
- gettimeout()
- listen(backlog)
- makefile([mode[, bufsize]])
- recv(bufsize[, flags])
- recvfrom(bufsize[, flags])
- send(data[, flags])
- sendall(data[, flags])
- sendto(data[, flags], address)
- setblocking(flag)
- setsockopt(level, option, value)
- settimeout(timeout)
- shutdown(how)

#### accept()

        accept() -> (socket object, address info)

        Wait for an incoming connection. Return a new socket representing the
        connection, and the address of the client. For RFCOMM sockets, the address
        info is a pair (hostaddr, channel).

        The socket must be bound and listening before calling this method.

#### bind(address)

        bind(address)

        Bind the socket to a local address. For RFCOMM sockets, the address is a
        pair (host, channel); the host must refer to the local host.

        A port value of 0 binds the socket to a dynamically assigned port.
        (Note that on Mac OS X, the port value must always be 0.)

        The socket must not already be bound.

#### close()

        close()

        Close the socket.  It cannot be used after this call.

#### connect(address)

        connect(address)

        Connect the socket to a remote address. The address should be a
        (host, channel) pair for RFCOMM sockets, and a (host, PSM) pair for L2CAP
        sockets.

        The socket must not be already connected.

#### connect_ex(address)

        connect_ex(address) -> errno

        This is like connect(address), but returns an error code instead of raising
        an exception when an error occurs.

#### dup()

        dup() -> socket object

        Returns a new socket object connected to the same system resource.

#### fileno()

        fileno() -> integer

        Return the integer file descriptor of the socket.

        Raises NotImplementedError on Mac OS X and Python For Series 60.

#### getpeername()

        getpeername() -> address info

        Return the address of the remote endpoint. The address info is a
        (host, channel) pair for RFCOMM sockets, and a (host, PSM) pair for L2CAP
        sockets.

        If the socket has not been connected, socket.error will be raised.

#### getsockname()

        getsockname() -> address info

        Return the address of the local endpoint. The address info is a
        (host, channel) pair for RFCOMM sockets, and a (host, PSM) pair for L2CAP
        sockets.

        If the socket has not been connected nor bound, this returns the tuple
        ("00:00:00:00:00:00", 0).

#### getsockopt(level, option[, bufsize])

        getsockopt(level, option[, bufsize]) -> value

        Get a socket option.  See the Unix manual for level and option.
        If a nonzero buffersize argument is given, the return value is a
        string of that length; otherwise it is an integer.

        Currently support for socket options are platform independent -- i.e.
        depends on the underlying Series 60 or BlueZ socket options support.
        The Mac OS X implementation currently does not support any options at
        all and automatically raises socket.error.

#### gettimeout()

        gettimeout() -> timeout

        Returns the timeout in floating seconds associated with socket
        operations. A timeout of None indicates that timeouts on socket
        operations are disabled.

        Currently not supported on Python For Series 60 implementation, which
        will always return None.

#### listen(backlog)

        listen(backlog)

        Enable a server to accept connections. The backlog argument must be at
        least 1; it specifies the number of unaccepted connection that the system
        will allow before refusing new connections.

        The socket must not be already listening.

        Currently not implemented on Mac OS X.

#### makefile([mode[, bufsize]])

        makefile([mode[, bufsize]]) -> file object

        Returns a regular file object corresponding to the socket.  The mode
        and bufsize arguments are as for the built-in open() function.

#### recv(bufsize[, flags])

        recv(bufsize[, flags]) -> data

        Receive up to bufsize bytes from the socket.  For the optional flags
        argument, see the Unix manual.  When no data is available, block until
        at least one byte is available or until the remote end is closed.  When
        the remote end is closed and all data is read, return the empty string.

        Currently the flags argument has no effect on Mac OS X.

#### recvfrom(bufsize[, flags])

        recvfrom(bufsize[, flags]) -> (data, address info)

        Like recv(buffersize, flags) but also return the sender's address info.

#### send(data[, flags])

        send(data[, flags]) -> count

        Send a data string to the socket.  For the optional flags
        argument, see the Unix manual.  Return the number of bytes
        sent.

        The socket must be connected to a remote socket.

        Currently the flags argument has no effect on Mac OS X.

#### sendall(data[, flags])

        sendall(data[, flags])

        Send a data string to the socket.  For the optional flags
        argument, see the Unix manual.  This calls send() repeatedly
        until all data is sent.  If an error occurs, it's impossible
        to tell how much data has been sent.

#### sendto(data[, flags], address)

        sendto(data[, flags], address) -> count

        Like send(data, flags) but allows specifying the destination address.
        For RFCOMM sockets, the address is a pair (hostaddr, channel).

#### setblocking(flag)

        setblocking(flag)

        Set the socket to blocking (flag is true) or non-blocking (false).
        setblocking(True) is equivalent to settimeout(None);
        setblocking(False) is equivalent to settimeout(0.0).

        Initially a socket is in blocking mode. In non-blocking mode, if a
        socket operation cannot be performed immediately, socket.error is raised.

#### setsockopt(level, option, value)

        setsockopt(level, option, value)

        Set a socket option.  See the Unix manual for level and option.
        The value argument can either be an integer or a string.

        Currently support for socket options are platform independent -- i.e.
        depends on the underlying Series 60 or BlueZ socket options support.
        The Mac OS X implementation currently does not support any options at
        all and automatically raise socket.error.

#### settimeout(timeout)

        settimeout(timeout)

        Set a timeout on socket operations.  'timeout' can be a float,
        giving in seconds, or None.  Setting a timeout of None disables
        the timeout feature and is equivalent to setblocking(1).
        Setting a timeout of zero is the same as setblocking(0).

        If a timeout is set, the connect, accept, send and receive operations will
        raise socket.timeout if a timeout occurs.

        Raises NotImplementedError on Python For Series 60.

#### shutdown(how)

        shutdown(how)

        Shut down the reading side of the socket (flag == socket.SHUT_RD), the
        writing side of the socket (flag == socket.SHUT_WR), or both ends
        (flag == socket.SHUT_RDWR).