Package nss :: Module io :: Class Socket
[hide private]
[frames] | no frames]

Class Socket

object --+
         |
        Socket
Known Subclasses:

Socket(family=PR_AF_INET, type=PR_DESC_SOCKET_TCP)

:Parameters:
    family : integer
        one of:
            - PR_AF_INET
            - PR_AF_INET6
            - PR_AF_LOCAL
    type : integer
        one of:
            - PR_DESC_SOCKET_TCP
            - PR_DESC_SOCKET_UDP

Create a new NSPR socket:

Instance Methods [hide private]
 
__init__(family=PR_AF_INET, type=PR_DESC_SOCKET_TCP)
x.__init__(...) initializes x; see x.__class__.__doc__ for signature
 
__iter__(x)
iter(x)
a new object with type S, a subtype of T

__new__(T, S, ...)
 
__repr__(x)
repr(x)
 
__str__(x)
str(x)
(Socket, NetworkAddress)

accept(timeout=PR_INTERVAL_NO_TIMEOUT)
:Parameters: timeout : integer optional timeout value expressed as a NSPR interval
(Socket, NetworkAddress, buf)

accept_read(amount, timeout=PR_INTERVAL_NO_TIMEOUT)
:Parameters: amount : integer the maximum number of bytes to receive timeout : integer optional timeout value expressed as a NSPR interval
 
bind(addr)
:Parameters: addr : NetworkAddress object address to bind to
 
close()
Close the socket.
 
connect(addr, timeout=PR_INTERVAL_NO_TIMEOUT)
:Parameters: addr : NetworkAddress object address to connect to timeout : integer optional timeout value expressed as a NSPR interval
integer

fileno()
Return the integer file descriptor of the socket.
NetworkAddress

get_peer_name()
Return the network address for the connected peer socket.
NetworkAddress

get_sock_name()
Return the network address for this socket.
 
get_socket_option(option)
The method return values varies depending on the option, see below:
 
listen(backlog=5)
:Parameters: backlog : integer The maximum length of the queue of pending connections.
file object

makefile(mode=..., buffersize=...)
:Parameters: mode : string mode string identical to open(), e.g.
the next value, or raise StopIteration

next(x)
 
read(size=-1)
:Parameters: size : integer If specified and non-negative the maximum number of bytes to receive otherwise read till EOF
buf

readline(size=...)
:Parameters: size : integer optional, read at most size bytes
[buf]

readlines(sizehint=...)
:Parameters: sizehint : integer optional, read approximately sizehint bytes before returning
buf

recv(amount, timeout=PR_INTERVAL_NO_TIMEOUT)
:Parameters: amount : integer the maximum number of bytes to receive timeout : integer optional timeout value expressed as a NSPR interval
buf

recv_from(amount, addr, timeout=PR_INTERVAL_NO_TIMEOUT)
:Parameters: amount : integer the maximum number of bytes to receive addr : NetworkAddress object a NetworkAddress object to receive from timeout : integer optional timeout value expressed as a NSPR interval
amount

send(buf, timeout=PR_INTERVAL_NO_TIMEOUT)
:Parameters: buf : buffer a buffer of data to transmit timeout : integer optional timeout value expressed as a NSPR interval
amount

send_to(buf, addr, timeout=PR_INTERVAL_NO_TIMEOUT)
:Parameters: buf : buffer a buffer of data to transmit addr : NetworkAddress object a NetworkAddress object to send to timeout : integer optional timeout value expressed as a NSPR interval
amount

sendall(buf, timeout=PR_INTERVAL_NO_TIMEOUT)
:Parameters: buf : buffer a buffer of data to transmit timeout : integer optional timeout value expressed as a NSPR interval
 
set_socket_option(option, ...)
The method signature varies depending on the option, see below:
 
shutdown(how=PR_SHUTDOWN_BOTH)
:Parameters: how : integer The kind of disallowed operations on the socket.

Inherited from object: __delattr__, __format__, __getattribute__, __hash__, __reduce__, __reduce_ex__, __setattr__, __sizeof__, __subclasshook__

Static Methods [hide private]
Socket

import_tcp_socket(osfd)
:Parameters: osfd : integer file descriptor of the SOCK_STREAM socket to import
(Socket, Socket)

new_tcp_pair()
Returns a pair of connected TCP sockets: data written to one can be read from the other and vice versa.
(flags, ...)

poll(poll_descs, timeout)
:Parameters: poll_descs : sequence of (Socket, flags) sequences flags is a bitwise OR of PR_POLL_* flags timeout : interval time how long to block
Properties [hide private]
  desc_type
socket description: PR_DESC_FILE, PR_DESC_SOCKET_TCP, PR_DESC_SOCKET_UDP, PR_DESC_LAYERED, PR_DESC_PIPE
  family
socket family: PR_AF_INET, PR_AF_INET6, PR_AF_LOCAL, PR_AF_UNSPEC
  netaddr
NetworkAddress object bound to this socket

Inherited from object: __class__

Method Details [hide private]

__init__(family=PR_AF_INET, type=PR_DESC_SOCKET_TCP)
(Constructor)

 
x.__init__(...) initializes x; see x.__class__.__doc__ for signature

Overrides: object.__init__

__new__(T, S, ...)

 


Returns:
a new object with type S, a subtype of T

Overrides: object.__new__

__repr__(x)
(Representation operator)

 
repr(x)

Overrides: object.__repr__

__str__(x)
(Informal representation operator)

 
str(x)

Overrides: object.__str__

accept(timeout=PR_INTERVAL_NO_TIMEOUT)

 
:Parameters:
    timeout : integer
        optional timeout value expressed as a NSPR interval

The socket is a rendezvous socket that has been bound to an address
with Socket.bind() and is listening for connections after a call to
Socket.listen(). Socket.accept() accepts the first connection from the
queue of pending connections and creates a new socket for the newly
accepted connection. The rendezvous socket can still be used to accept
more connections.

Socket.accept() blocks the calling thread until either a new
connection is successfully accepted or an error occurs. If the timeout
parameter is not PR_INTERVAL_NO_TIMEOUT and no pending connection can
be accepted before the time limit, Socket.accept() raises a
nss.error.NSPRError exception with the error code PR_IO_TIMEOUT_ERROR.

Socket.accept() returns a tuple containing a new Socket object and
Networkaddress object for the peer.

Returns:
(Socket, NetworkAddress)

accept_read(amount, timeout=PR_INTERVAL_NO_TIMEOUT)

 
:Parameters:
    amount : integer
        the maximum number of bytes to receive
    timeout : integer
        optional timeout value expressed as a NSPR interval

Socket.accept_read() combines the behavior of Socket.accept() and
Socket.recv(). It accepts a new connection and after it performs an
initial read on the new socket as Socket.recv() would it returns the
newly created Socket and NetworkAddress objects for the peer as well
as a buffer of data.

Socket.accept_read() returns a tuple containing a new Socket object, a
new Networkaddress object for the peer, and a bufer containing data
from the first read on the Socket object.

Returns:
(Socket, NetworkAddress, buf)

bind(addr)

 
:Parameters:
    addr : NetworkAddress object
        address to bind to

When a new socket is created, it has no address bound to
it. Socket.bind() assigns the specified network address to the
socket. If you do not care about the exact IP address assigned to the
socket, create a NetworkAddress object using PR_INADDR_ANY. If you do
not care about the TCP/UDP port assigned to the socket, set the port
value of the NetworkAddress object to 0.

Note that if Socket.connect() is invoked on a socket that is not
bound, it implicitly binds an arbitrary address to the socket.

Call Socket.get_sock_name to obtain the address (name) bound to a
socket.

connect(addr, timeout=PR_INTERVAL_NO_TIMEOUT)

 
:Parameters:
    addr : NetworkAddress object
        address to connect to
    timeout : integer
        optional timeout value expressed as a NSPR interval

Socket.connect() is usually invoked on a TCP socket, but it may also
be invoked on a UDP socket. Both cases are discussed here.

If the socket is a TCP socket, Socket.connect() establishes a TCP
connection to the peer. If the socket is not bound, it will be bound
to an arbitrary local address.

Socket.connect() blocks until either the connection is successfully
established or an error occurs. If the timeout parameter is not
PR_INTERVAL_NO_TIMEOUT and the connection setup cannot complete before
the time limit, Socket.connect() fails with the error code
PR_IO_TIMEOUT_ERROR.

If the socket is a UDP socket, there is no connection setup to speak
of, since UDP is connectionless. If Socket.connect() is invoked on a
UDP socket, it has an overloaded meaning: Socket.connect() merely
saves the specified address as the default peer address for the
socket, so that subsequently one can send and receive datagrams from
the socket using Socket.send() and Socket.recv() instead of the usual
Socket.send_to() and Socket.recv_from().

get_socket_option(option)

 
The method return values varies depending on the option, see below:

Set socket to non-blocking IO
    ::
        
        get_socket_option(PR_SockOpt_Nonblocking) -> bool

Time to linger on close if data is present in socket send buffer. 
    ::
        
        get_socket_option(PR_SockOpt_Linger) -> (polarity, interval)

Allow local address reuse
    ::
        
        get_socket_option(PR_SockOpt_Reuseaddr) -> bool

Keep connections alive
    ::
        
        get_socket_option(PR_SockOpt_Keepalive) -> bool

Allow IP multicast loopback
    ::
        
        get_socket_option(PR_SockOpt_McastLoopback) -> bool

Disable Nagle algorithm. Don't delay send to coalesce packets. 
    ::
        
        get_socket_option(PR_SockOpt_NoDelay) -> bool

Enable broadcast
    ::
        
        get_socket_option(PR_SockOpt_Broadcast) -> bool

Receive buffer size. 
    ::
        
        get_socket_option(PR_SockOpt_RecvBufferSize) -> size

Send buffer size. 
    ::
        
        get_socket_option(PR_SockOpt_SendBufferSize) -> size

Maximum segment size
    ::
        
        get_socket_option(PR_SockOpt_MaxSegment) -> size

IP Time to Live
    ::
        
        get_socket_option(PR_SockOpt_IpTimeToLive) -> interval

IP type of service and precedence
    ::
        
        get_socket_option(PR_SockOpt_IpTypeOfService) -> tos

Add an IP group membership
    ::
        
        get_socket_option(PR_SockOpt_AddMember) -> (mcaddr, ifaddr)

- mcaddr is a NetworkAddress object representing the IP multicast address of group
- ifaddr is a NetworkAddress object representing the local IP address of the interface

Drop an IP group membership
    ::
        
        get_socket_option(PR_SockOpt_DropMember) -> (mcaddr, ifaddr)

- mcaddr is a NetworkAddress object representing the IP multicast address of group
- ifaddr is a NetworkAddress object representing the local IP address of the interface

Multicast Time to Live
    ::
        
        get_socket_option(PR_SockOpt_McastTimeToLive) -> interval

Multicast interface address
    ::
        
        get_socket_option(PR_SockOpt_McastInterface) -> ifaddr

- ifaddr is a NetworkAddress object representing the multicast interface address

import_tcp_socket(osfd)
Static Method

 
:Parameters:
    osfd : integer
        file descriptor of the SOCK_STREAM socket to import

Returns a Socket object that uses the specified socket file descriptor for
communication.

Returns:
Socket

listen(backlog=5)

 
:Parameters:
    backlog : integer
        The maximum length of the queue of pending connections.

Socket.listen() turns the specified socket into a rendezvous
socket. It creates a queue for pending connections and starts to
listen for connection requests on the socket. The maximum size of the
queue for pending connections is specified by the backlog
parameter. Pending connections may be accepted by calling
Socket.accept().

makefile(mode=..., buffersize=...)

 
:Parameters:
    mode : string
        mode string identical to open(), e.g. 'r','w','rb', etc.
    buffersize : integer
        file buffer size

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

Returns:
file object

poll(poll_descs, timeout)
Static Method

 
:Parameters:
    poll_descs : sequence of (Socket, flags) sequences
        flags is a bitwise OR of PR_POLL_* flags
    timeout : interval time
        how long to block

Wait until at least one of the Socket objects is ready for the action in
flags.  Return a sequence of flags values, each representing the state of
the corresponding Socket in poll_descs.

Returns:
(flags, ...)

read(size=-1)

 
:Parameters:
    size : integer
        If specified and non-negative the maximum number of bytes to receive
        otherwise read till EOF

If the length of the returned buffer is 0 this indicates the network
connection is closed.

readline(size=...)

 
:Parameters:
    size : integer
        optional, read at most size bytes

Read one entire line from the socket. If the size argument is present
and non-negative, it is a maximum byte count (including the trailing
newline) and an incomplete line may be returned. An empty string is
returned on EOF (connection close). Note: Unlike stdio's fgets(), the
returned string may contain null characters ('

Returns:
buf

readlines(sizehint=...)

 
:Parameters:
    sizehint : integer
        optional, read approximately sizehint bytes before returning

Read until EOF using Socket.readline() and return a list containing
the lines thus read. If the optional sizehint argument is present and
non-negative, instead of reading up to EOF, whole lines totalling
approximately sizehint bytes are read.

Returns:
[buf]

recv(amount, timeout=PR_INTERVAL_NO_TIMEOUT)

 
:Parameters:
    amount : integer
        the maximum number of bytes to receive
    timeout : integer
        optional timeout value expressed as a NSPR interval

Socket.recv() blocks until some positive number of bytes are
transferred, a timeout occurs, or an error occurs. No more than amount
bytes will be transferred.

If the length of the returned buffer is 0 this indicates the network
connection is closed.

Returns:
buf

recv_from(amount, addr, timeout=PR_INTERVAL_NO_TIMEOUT)

 
:Parameters:
    amount : integer
        the maximum number of bytes to receive
    addr : NetworkAddress object
        a NetworkAddress object to receive from
    timeout : integer
        optional timeout value expressed as a NSPR interval

Socket.recv_from() blocks until some positive number of bytes are
transferred, a timeout occurs, or an error occurs. No more than amount
bytes will be transferred.

If the length of the returned buffer is 0 this indicates the network
connection is closed.

Note: Socket.recv_from() is usually used with a UDP socket.

Returns:
buf

send(buf, timeout=PR_INTERVAL_NO_TIMEOUT)

 
:Parameters:
    buf : buffer
        a buffer of data to transmit
    timeout : integer
        optional timeout value expressed as a NSPR interval

Socket.send() blocks until all bytes are sent (unless the socket is in
non-blocking mode), a timeout occurs, or an error occurs. In the case
of a timeout or an error then a nss.error.NSPRError will be raised.

The function returns the number of bytes actually transmitted.

Returns:
amount

send_to(buf, addr, timeout=PR_INTERVAL_NO_TIMEOUT)

 
:Parameters:
    buf : buffer
        a buffer of data to transmit
    addr : NetworkAddress object
        a NetworkAddress object to send to
    timeout : integer
        optional timeout value expressed as a NSPR interval

Socket.send_to() blocks until all bytes are sent (unless the socket is in
non-blocking mode), a timeout occurs, or an error occurs. In the case
of a timeout or an error then a nss.error.NSPRError will be raised.

The function returns the number of bytes actually transmitted.

Note: Socket.send_to() is usually used with a UDP socket.

Returns:
amount

sendall(buf, timeout=PR_INTERVAL_NO_TIMEOUT)

 
:Parameters:
    buf : buffer
        a buffer of data to transmit
    timeout : integer
        optional timeout value expressed as a NSPR interval

Socket.sendall() blocks until all bytes are sent (unless the socket is in
non-blocking mode), a timeout occurs, or an error occurs. In the case
of a timeout or an error then a nss.error.NSPRError will be raised.

The function returns the number of bytes actually transmitted.

Returns:
amount

set_socket_option(option, ...)

 
The method signature varies depending on the option, see below:

Set socket to non-blocking IO
    ::
        
        set_socket_option(PR_SockOpt_Nonblocking, bool)

Time to linger on close if data is present in socket send buffer. 
    ::
        
        set_socket_option(PR_SockOpt_Linger, polarity, interval)

Allow local address reuse
    ::
        
        set_socket_option(PR_SockOpt_Reuseaddr, bool)

Keep connections alive
    ::
        
        set_socket_option(PR_SockOpt_Keepalive, bool)

Allow IP multicast loopback
    ::
        
        set_socket_option(PR_SockOpt_McastLoopback, bool)

Disable Nagle algorithm. Don't delay send to coalesce packets. 
    ::
        
        set_socket_option(PR_SockOpt_NoDelay, bool)

Enable broadcast
    ::
        
        set_socket_option(PR_SockOpt_Broadcast, bool)

Receive buffer size. 
    ::
        
        set_socket_option(PR_SockOpt_RecvBufferSize, size)

Send buffer size. 
    ::
        
        set_socket_option(PR_SockOpt_SendBufferSize, size)

Maximum segment size
    ::
        
        set_socket_option(PR_SockOpt_MaxSegment, size)

IP Time to Live
    ::
        
        set_socket_option(PR_SockOpt_IpTimeToLive, interval)

IP type of service and precedence
    ::
        
        set_socket_option(PR_SockOpt_IpTypeOfService, tos)

Add an IP group membership
    ::
        
        set_socket_option(PR_SockOpt_AddMember, mcaddr, ifaddr)

- mcaddr is a NetworkAddress object representing the IP multicast address of group
- ifaddr is a NetworkAddress object representing the local IP address of the interface

Drop an IP group membership
    ::
        
        set_socket_option(PR_SockOpt_DropMember, mcaddr, ifaddr)

- mcaddr is a NetworkAddress object representing the IP multicast address of group
- ifaddr is a NetworkAddress object representing the local IP address of the interface

Multicast Time to Live
    ::
        
        set_socket_option(PR_SockOpt_McastTimeToLive, interval)

Multicast interface address
    ::
        
        set_socket_option(PR_SockOpt_McastInterface, ifaddr)

- ifaddr is a NetworkAddress object representing the multicast interface address

shutdown(how=PR_SHUTDOWN_BOTH)

 
:Parameters:
    how : integer
        The kind of disallowed operations on the socket.

        May be one of the following the following:
        
        PR_SHUTDOWN_RCV
            Further receives will be disallowed.
        PR_SHUTDOWN_SEND
            Further sends will be disallowed.
        PR_SHUTDOWN_BOTH
            Further sends and receives will be disallowed.