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

type Socket

object --+
         |
        Socket
Known Subclasses:

Socket(family=PR_AF_INET, type=PR_DESC_SOCKET_TCP)

Create a new NSPR socket:

Instance Methods [hide private]
 
__init__(family=PR_AF_INET, type=PR_DESC_SOCKET_TCP)
x.__init__(...) initializes x; see help(type(x)) for signature
 
__iter__(x)
iter(x)
a new object with type S, a subtype of T
__new__(T, S, ...)
 
__str__(x)
str(x)
(Socket, NetworkAddress)
accept(timeout=PR_INTERVAL_NO_TIMEOUT)
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, NetworkAddress, buf)
accept_read(amount, timeout=PR_INTERVAL_NO_TIMEOUT)
Socket.accept_read() combines the behavior of Socket.accept() and Socket.recv().
 
bind(addr)
When a new socket is created, it has no address bound to it.
 
close()
Close the socket.
 
connect(addr, timeout=PR_INTERVAL_NO_TIMEOUT)
Socket.connect() is usually invoked on a TCP socket, but it may also be invoked on a UDP socket.
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)
Socket.listen() turns the specified socket into a rendezvous socket.
file object
makefile(mode=..., buffersize=...)
Return a regular file object corresponding to the socket.
the next value, or raise StopIteration
next(x)
 
read(size=-1)
If the length of the returned buffer is 0 this indicates the network connection is closed.
buf
readline(size=...)
Read one entire line from the socket.
[buf]
readlines(sizehint=...)
Read until EOF using Socket.readline() and return a list containing the lines thus read.
buf
recv(amount, timeout=PR_INTERVAL_NO_TIMEOUT)
Socket.recv() blocks until some positive number of bytes are transferred, a timeout occurs, or an error occurs.
buf
recv_from(amount, addr, timeout=PR_INTERVAL_NO_TIMEOUT)
Socket.recv_from() blocks until some positive number of bytes are transferred, a timeout occurs, or an error occurs.
amount
send(buf, timeout=PR_INTERVAL_NO_TIMEOUT)
Socket.send() blocks until all bytes are sent (unless the socket is in non-blocking mode), a timeout occurs, or an error occurs.
amount
send_to(buf, addr, timeout=PR_INTERVAL_NO_TIMEOUT)
Socket.send_to() blocks until all bytes are sent (unless the socket is in non-blocking mode), a timeout occurs, or an error occurs.
amount
sendall(buf, timeout=PR_INTERVAL_NO_TIMEOUT)
Socket.sendall() blocks until all bytes are sent (unless the socket is in non-blocking mode), a timeout occurs, or an error occurs.
 
set_socket_option(option, ...)
The method signature varies depending on the option, see below:
 
shutdown(how=PR_SHUTDOWN_BOTH)
Static Methods [hide private]
Socket
import_tcp_socket(osfd)
Returns a Socket object that uses the specified socket file descriptor for communication.
(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)
Wait until at least one of the Socket objects is ready for the action in flags.
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
Method Details [hide private]

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

 
x.__init__(...) initializes x; see help(type(x)) for signature
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
Overrides: object.__init__

__new__(T, S, ...)

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

__str__(x)
(Informal representation operator)

 
str(x)
Overrides: object.__str__

accept(timeout=PR_INTERVAL_NO_TIMEOUT)

 

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.

Parameters:
  • timeout (integer) - optional timeout value expressed as a NSPR interval
Returns: (Socket, NetworkAddress)

accept_read(amount, timeout=PR_INTERVAL_NO_TIMEOUT)

 

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.

Parameters:
  • amount (integer) - the maximum number of bytes to receive
  • timeout (integer) - optional timeout value expressed as a NSPR interval
Returns: (Socket, NetworkAddress, buf)

bind(addr)

 

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.

Parameters:
  • addr (NetworkAddress object) - address to bind to

connect(addr, timeout=PR_INTERVAL_NO_TIMEOUT)

 

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().

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

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

 
Returns a Socket object that uses the specified socket file descriptor for communication.
Parameters:
  • osfd (integer) - file descriptor of the SOCK_STREAM socket to import
Returns: Socket

listen(backlog=5)

 
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().
Parameters:
  • backlog (integer) - The maximum length of the queue of pending connections.

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

 
Return a regular file object corresponding to the socket. The mode and buffersize arguments are as for the built-in open() function.
Parameters:
  • mode (string) - mode string identical to open(), e.g. 'r','w','rb', etc.
  • buffersize (integer) - file buffer size
Returns: file object

poll(poll_descs, timeout)
Static Method

 
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.
Parameters:
  • poll_descs (sequence of (Socket, flags) sequences) - flags is a bitwise OR of PR_POLL_* flags
  • timeout (interval time) - how long to block
Returns: (flags, ...)

read(size=-1)

 
If the length of the returned buffer is 0 this indicates the network connection is closed.
Parameters:
  • size (integer) - If specified and non-negative the maximum number of bytes to receive otherwise read till EOF

readline(size=...)

 
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 ('
Parameters:
  • size (integer) - optional, read at most size bytes
Returns: buf

readlines(sizehint=...)

 
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.
Parameters:
  • sizehint (integer) - optional, read approximately sizehint bytes before returning
Returns: [buf]

recv(amount, timeout=PR_INTERVAL_NO_TIMEOUT)

 

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.

Parameters:
  • amount (integer) - the maximum number of bytes to receive
  • timeout (integer) - optional timeout value expressed as a NSPR interval
Returns: buf

recv_from(amount, addr, timeout=PR_INTERVAL_NO_TIMEOUT)

 

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.

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
Returns: buf

send(buf, timeout=PR_INTERVAL_NO_TIMEOUT)

 

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.

Parameters:
  • buf (buffer) - a buffer of data to transmit
  • timeout (integer) - optional timeout value expressed as a NSPR interval
Returns: amount

send_to(buf, addr, timeout=PR_INTERVAL_NO_TIMEOUT)

 

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.

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
Returns: amount

sendall(buf, timeout=PR_INTERVAL_NO_TIMEOUT)

 

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.

Parameters:
  • buf (buffer) - a buffer of data to transmit
  • timeout (integer) - optional timeout value expressed as a NSPR interval
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.