7.2.1 Oggetti Socket

Gli oggetti socket hanno i seguenti metodi. Fatta eccezione per makefile() questi corrispondono alle chiamate di sistema Unix applicabili ai socket.

accept( ): Accetta una connessione. Il socket deve essere legato ad un indirizzo ed in attesa di connessioni. Il valore restituito è una coppia (conn, address) dove conn è un nuovo oggetto socket da usare per inviare e ricevere dati sulla connessione, mentre address è l'indirizzo legato al socket dell'altro capo della connessione.

bind( address): Lega il socket ad address. Il socket non deve essere già legato. (Il formato di address dipende dalla famiglia di indirizzo -- leggere sopra.) Note: Questo metodo storicamente accettava una coppia di parametri per gli indirizzi AF_INET invece di una sola tupla. Ciò non è mai stato intenzionale e non è più disponibile in Python 2.0 e successive versioni dell'interprete.

close( ): Chiude il socket. Tutte le future operazioni sull'oggetto socket falliranno. L'altro capo non riceverà più alcun dato (dopo che la coda dei dati sarà svuotata). I socket sarano automaticamente chiusi quando verranno raccolti dal garbage-collector.

connect( address): Connette con un socket remoto all'indirizzo address. (Il formato di address dipende dalla famiglia di indirizzo -- leggere sopra.) Note: Questo metodo storicamente accettava una coppia di parametri per gli indirizzi AF_INET invece di una sola tupla. Ciò non è mai stato intenzionale e non è più disponibile su Python 2.0 e successive versioni dell'interprete.

connect_ex( address): Come connect(address), ma restituisce un indicatore di errore invece di sollevare un'eccezione, per errori restituiti dalla chiamata connect() a livello C (altri problemi, come ``host not found'', possono ancora sollevare eccezioni). L'indicatore di errore è 0 se l'operazione ha avuto successo, altrimenti viene indicato della variabile errno. Ciò torna utile per supportare, ad esempio, connessioni asincrone. Note: Questo metodo storicamente accettava una coppia di parametri per gli indirizzi AF_INET invece di una sola tupla. Ciò non è mai stato intenzionale e non è più disponibile su Python 2.0 e successivi.

fileno( ): Restituisce il descrittore di file del socket (uno small integer). Utile con la select.select().
Sotto Windows lo small integer ritornato da questo metodo non può essere usato dove si può usare un descrittore di file (come os.fdopen()). Unix non ha questa limitazione.

getpeername( ): Restituisce l'indirizzo remoto al quale il socket è connesso. Torna utile per trovare il numero di porta di un socket remoto IPv4/v6, ad esempio. (Il formato dell'indirizzo restituito dipende dalla famiglia di indirizzo -- leggere sopra.) Su alcuni sistemi questa funzione non è supportata.

getsockname( ): Restituisce l'indirizzo stesso del socket. Torna utile per trovare il numero di porta di un socket IPv4/v6, ad esempio. (Il formato di un indirizzo restituito dipende dalla famiglia di indirizzo -- leggere sopra.)

getsockopt( level, optname[, buflen]): Restituisce il valore dell'opzione socket data (leggere la pagina di manuale Unix getsockopt(2)). Le costanti simboliche di cui ha bisogno (SO_* etc.) sono definite in questo modulo. Se buflen è assente, viene considerata un'opzione intera ed il suo valore intero viene restituito dalla funzione. Se buflen è presente, specifica la lunghezza massima del buffer usata per ricevere l'opzione, e questo buffer è restituito come stringa. È compito del chiamante decodificare il contenuto del buffer (leggere il modulo built-in facoltativo struct per un modo per decodificare le strutture C codificate come stringhe).

listen( backlog): Attende connessioni fatte al socket. L'argomento backlog specifica il numero massimo di connessioni accodabili e dovrebbe essere almeno 1; il valore massimo dipende dal sistema (solitamente 5).

makefile( [mode[, bufsize]]): Restituisce un oggetto file associato al socket. (Gli oggetti file sono descritti nella sezione 2.3.9, ``Oggetti File.'') L'oggetto file si riferisce ad una versione dup()ped del descrittore file del socket, quindi l'oggetto file e l'oggetto socket possono essere chiusi o raccolti dal garbage-collector indipendentemente. Il socket dovrebbe essere in modalità bloccante. Gli argomenti opzionali mode e bufsize sono interpretati nello stesso modo della funzione built-in file(); leggere ``Funzioni built-in'' (sezione 2.1) per ulteriori informazioni.

recv( bufsize[, flags]): Riceve dati dal socket. Il valore restituito è una stringa che rappresenta i dati ricevuti. Il massimo ammontare di dati da ricevere in una volta viene specificato da bufsize. Leggere la pagina di manuale Unix recv(2) per informazioni sul significato dell'argomento facoltativo flags; il valore predefinito è zero.

recvfrom( bufsize[, flags]): Riceve dati dal socket. Il valore restituito è una coppia (string, address) dove string è una stringa che rappresenta i dati ricevuti e address è l'indirizzo del socket che ha inviato i dati. L'argomento opzionale flags ha lo stesso significato della recv() sopra. (Il formato di address dipende dalla famiglia di indirizzo -- leggere sopra.)

send( string[, flags]): Invia dati al socket. Il socket deve essere connesso ad un socket remoto. L'argomento facoltativo flags ha lo stesso significato della recv() precedente. Restituisce il numero di byte inviati. Gli applicativi sono responsabili del controllo di tutti i dati che vengono trasmessi; se solo una parte dei dati viene inviata, l'applicativo deve tentare la consegna dei dati rimanenti.

sendall( string[, flags]): Invia dati al socket. Il socket deve essere connesso ad un socket remoto. L'argomento facoltativo flags ha lo stesso significato della recv() precedente. Diversamente da send(), questo metodo continua ad inviare dati da string fino a che tutti i dati vengano inviati o accada un errore. Viene restituito None in caso di successo. In caso di errore, viene sollevata un'eccezione, e non c'è modo di determinare quanti dati siano stati effettivamente inviati.

sendto( string[, flags], address): Invia dati al socket. Il socket non dovrebbe essere connesso ad un socket remoto, visto che il socket di destinazione è specificato da address. L'argomento facoltativo flags ha lo stesso significato della recv() precedente. Restituisce il numero di byte inviati. (Il formato di address dipende dalla famiglia di indirizzo -- leggere sopra.)

setblocking( flag): Imposta la modalità bloccante o non-bloccante sul socket: se flag è 0, il socket è impostato come non-bloccante, altrimenti è in modalità bloccante. Inizialmente tutti i socket sono in modalità bloccante. In modalità non-bloccante, se una chiamata recv() non trova alcun dato, o se una chiamata send() non può avere subito a disposizione i dati, viene sollevata un'eccezione error; in modalità bloccante, la chiamata si ferma fino a che non è possibile procedere. s.setblocking(0) equivale a s.settimeout(0); s.setblocking(1) equivale a s.settimeout(None).

settimeout( value): Imposta un timeout sulle operazioni di bloccaggio del socket. L'argomento value può essere un numero in virgola mobile non negativo espresso in secondi, o None. Se viene passato un numero in virgola mobile, le operazioni socket seguenti solleveranno un'eccezione timeout se scade il periodo di timeout prima che l'operazione venga completata. Impostando un timeout a None vengono disabilitati i timeout su ogni operazione. s.settimeout(0.0) equivale a s.setblocking(0); s.settimeout(None) equivale a s.setblocking(1). Nuovo nella versione 2.3.

gettimeout( ): Restituisce il timeout in secondi in virgola mobile associato alle operazioni socket o None se non è impostato alcun timeout. Ciò riflette l'ultima chiamata a setblocking() o settimeout(). Nuovo nella versione 2.3.

Alcune note sui timeout ed il bloccaggio dei socket: un oggetto socket può essere in una di queste tre modalità: bloccante, non-bloccante, o timeout. I socket vengono sempre creati in modalità bloccante. In modalità bloccante, le operazioni sono bloccate fino al loro completamento. In modalità non-bloccante, le operazioni falliscono (con un errore che è sfortunatamente dipendente dal sistema) se non possono essere completati immediatamente. In modalità timeout le operazioni falliscono se non possono essere completate durante il timeout specificato per il socket. Il metodo setblocking() è semplicemente una scorciatoia per alcune chiamate a settimeout().

La modalità timeout imposta internamente il socket in modalità non-bloccante. Le modalità bloccante e timeout sono condivise fra descrittori di file e oggetti socket che si riferiscono alla stessa estremità della rete. Una conseguenza di questo è che gli oggetti file ritornati dal metodo makefile() dovrebbero essere usati solo per socket in modalià bloccante; nelle modalità timeout e non bloccanti le operazioni sui file che non possono essere completate immediatamente falliranno.

Notare che l'operazione connect() è soggetta alle impostazioni di timeout, ed in generale viene raccomandato di chiamare la settimeout() prima di chiamare la connect().

setsockopt( level, optname, value): Imposta il valore per la data opzione socket (leggere la pagina di manuale Unix setsockopt(2)). Le costanti simboliche richieste sono definite nel modulo socket (SO_* ecc.). value può essere un intero o una stringa rappresentante un buffer. Nell'ultimo caso è compito del chiamante assicurarsi che la stringa contenga i bit adatti (leggere il modulo facoltativo built-in struct per un modo per codificare strutture C come stringhe).

shutdown( how): Chiude una o entrambe le metà della connessione. Se how è SHUT_RD, saranno disabilitate ulteriori ricezioni. Se how è SHUT_WR, saranno disabilitati ulteriori invii. Se how è SHUT_RDWR, verranno disabilitati entrambi.

Notare che non esiste alcuna read() o write(); usare recv() e send() senza argomenti flags al loro posto.

Vedete Circa questo documento... per informazioni su modifiche e suggerimenti.