| core_net

# Class: Bs_SocketClient Source Location: /core/net/Bs_SocketClient.class.php
### Class Overview
    Bs_Object
       |
       --Bs_SocketClient
Generalized SocketClient class. #### Author(s): Andrej Arn <at blueshoes dot org> #### Version: 4.3.$Revision: 1.3 $ $Date: 2003/10/29 17:48:41 $ #### Copyright: blueshoes.org | ### Variables $host $lineLength $persistent $port $timeOut | ### Methods Bs_SocketClient connect disconnect eof getErrorMessage gets getState isBlocking read readAll readLine reconnect setBlocking setState write writeLine
### Inherited Variables | ### Inherited Methods #### Class: Bs_Object Bs_Object::Bs_Object() Bs_Object::getErrors() Basic error handling: Get *all* errors as string array from the global Bs_Error-error stack. Bs_Object::getLastError() Basic error handling: Get last error string from the global Bs_Error-error stack. Bs_Object::getLastErrors() Basic error handling: Get last errors string array from the global Bs_Error-error stack sinc last call of getLastErrors(). Bs_Object::persist() Persists this object by serializing it and saving it to a file with unique name. Bs_Object::setError() Basic error handling: Push an error string on the global Bs_Error-error stack. Bs_Object::toHtml() Dumps the content of this object to a string using PHP's var_dump(). Bs_Object::toString() Dumps the content of this object to a string using PHP's var_dump(). Bs_Object::unpersist() Fetches an object that was persisted with persist()
### Class Details [line 45] Generalized SocketClient class. use this in your classes that need a socket connection, please. examples: http clients, ftp clients, various email clients. Caution: it's possible to crash apache with sockets. test your code on a dev machine first. dependencies: None based on pears socket class Stig Bakken <ssb@fast.no> Chuck Hagenbuch <chuck@horde.org> #### Tags:
pattern: | singleton: (pseudostatic)
todo: | check from time to time setBlocking() (if nonblocking is possible on win now)
access: | public
version: | 4.3.$Revision: 1.3 $ $Date: 2003/10/29 17:48:41 $
copyright: | blueshoes.org
author: | Andrej Arn <at blueshoes dot org>
[ Top ] ### Class Variables #### $host = NULL [line 62] the host we work on. eg 'your.server.com' #### Tags:
access: | public
Type: | string
[ Top ] #### $lineLength = 2048 [line 138] Number of bytes to read at a time in readLine() and readAll(). #### Tags:
access: | public
Type: | int
[ Top ] #### $persistent = FALSE [line 90] if the connection should be made persistent or not. default is false. the connection is not closed after the script finishes if p is set. don't use this unless you have read the online manual with all comments and you know exactly what you're doing! #### Tags:
access: | public
Type: | bool
[ Top ] #### $port = 80 [line 70] the port we send to. #### Tags:
access: | public
Type: | int
[ Top ] #### $timeOut = 0 [line 99] Number of seconds to wait on socket connections before assuming there's no more data. make sure the script doesn't terminate before, see php's set_time_limit(). #### Tags:
access: | public
Type: | double
[ Top ] ### Class Methods ### constructor Bs_SocketClient [line 144]
`Bs_SocketClient Bs_SocketClient( )`
constructor. [ Top ] ### method connect [line 285]
`mixed connect( string $host, int $port, [bool $persistent = FALSE], [int $timeOut = 0], [bool $blocking = TRUE], [string $return = 'bool'])`
Connect to the specified port. If called when param $return is set to 'bool' and the socket is already connected, it disconnects and connects again. unless called with param $return='resource', these object vars are overwritten/updated: $this->host $this->_connection $this->port $this->_state $this->timeOut $this->persistent $this->_blocking #### Tags:
return: | depends on param $return. if set to 'bool' -> bool true on success, if set to 'resource' -> the resouce. on failure see throw.
throws: | bs_exception
access: | public
#### Parameters:
string | $host | like 'your.server.com' or an ip address like '111.111.111.111'.
int | $port | the tcp port number.
bool | $persistent | default is FALSE.
int | $timeOut | default is 0 (which means don't specify one).
bool | $blocking | default is TRUE. see $this->setBlocking().
string | $return | one of 'bool' (default) or 'resource'.
[ Top ] ### method disconnect [line 372]
`void disconnect( [resouce $connection = NULL])`
Disconnects from the peer, closes the socket. if the param $connection is given, this method is used static. #### Parameters:
resouce | $connection |
[ Top ] ### method eof [line 389]
`bool eof( [resouce $connection = NULL])`
if the param $connection is given, this method is used static. #### Parameters:
resouce | $connection |
[ Top ] ### method getErrorMessage [line 550]
`string getErrorMessage( long $errCode)`
Return a textual error message for a bs socket error code #### Tags:
return: | error message, or false if the error code was not recognized
#### Parameters:
long | $errCode | a bs error code (see constants)
[ Top ] ### method gets [line 471]
`string gets( int $size, [mixed $connection = NULL])`
Read a specified amount of data, stop when $size is reached, eof or newline. This is guaranteed to return, and has the added benefit of getting everything in one fread() chunk; if you know the size of the data you're getting beforehand, this is definitely the way to go. if the param $connection is given, this method is used static. #### Tags:
return: | bytes of data from the socket
see: | Bs_SocketClient::read(), Bs_SocketClient::readLine(), Bs_SocketClient::readAll()
#### Parameters:
int | $size | the number of bytes to read from the socket.
[ Top ] ### method getState [line 235]
`int getState( )`
Get the current state of the socket. one of define('BS_SOCKETCLIENT_DISCONNECTED', 0); define('BS_SOCKETCLIENT_CONNECTED', 1); define('BS_SOCKETCLIENT_SENT', 2); define('BS_SOCKETCLIENT_REQUEST_SENT', 3); define('BS_SOCKETCLIENT_GOT_REPLY', 4); define('BS_SOCKETCLIENT_GOT_REPLY_HEADER', 5); define('BS_SOCKETCLIENT_GOT_REPLY_CONTENT', 6); hint. (bool)TRUE=connected, FALSE=disconnected it's possible that this is set to connected but the connection expired or something else happened... it's the "should be" state. #### Tags:
return: | the current state.
see: | $this->setState, $this->_state
access: | public
[ Top ] ### method isBlocking [line 210]
`bool isBlocking( )`
Find out if the socket is in blocking mode. #### Tags:
return: | the current blocking mode.
see: | $this->setBlocking()
access: | public
[ Top ] ### method read [line 489]
`string read( int $size, [mixed $connection = NULL])`
Read a specified amount of data, stop when $size is reached or eof. continue on a newline. This is guaranteed to return, and has the added benefit of getting everything in one fread() chunk; if you know the size of the data you're getting beforehand, this is definitely the way to go. if the param $connection is given, this method is used static. #### Tags:
return: | bytes of data from the socket
see: | Bs_SocketClient::gets(), Bs_SocketClient::readLine(), Bs_SocketClient::readAll()
#### Parameters:
int | $size | the number of bytes to read from the socket.
[ Top ] ### method readAll [line 449]
`string readAll( [resouce $connection = NULL])`
Read until the socket closes. CAUTION: this method will not exit if the socket is in blocking mode until the socket closes. if the param $connection is given, this method is used static. #### Tags:
return: | all data until the socket closes.
see: | Bs_SocketClient::gets(), Bs_SocketClient::read(), Bs_SocketClient::readLine()
#### Parameters:
resouce | $connection |
[ Top ] ### method readLine [line 408]
`mixed readLine( [bool $removeCrlf = TRUE], [resouce $connection = NULL])`
Read from the connection until we got a full line, then return it. if the param $connection is given, this method is used static. #### Tags:
return: | string the line or NULL on eof
see: | Bs_SocketClient::gets(), Bs_SocketClient::read(), Bs_SocketClient::readAll()
throws: | NULL on an error. we cannot distinguish between error and eof :((( read comment in the code.
#### Parameters:
bool | $removeCrlf | if the carriage return/line feed (or lf, whatever there is) at the end should be removed or not. default is TRUE.
resouce | $connection |
[ Top ] ### method reconnect [line 355]
`bool reconnect( )`
Reconnect to the current host with the current settings - if possible. #### Tags:
return: | true on success, false on failure or if not capable.
access: | public
[ Top ] ### method setBlocking [line 171]
`bool setBlocking( [bool $mode = TRUE], [resouce $connection = NULL])`
Sets whether the socket connection should be blocking or not. A read call to a non-blocking socket will return immediately if there is no data available, whereas it will block until there is data for blocking sockets. note I: nonblocking mode not supported on win (php404). so until it's available, you cannot set this to blocking on win. note II: if the 2nd param $connection is given, this method is used static. the return value stays the same, no need to pass $connection by reference. note III: non-blocking sockets waste alot of cpu. take care. but some things really cannot be done without. #### Tags:
return: | true if it was possible to set, false if it failed. (fails to set blocking on win)
see: | $this->isBlocking()
#### Parameters:
bool | $mode | true for blocking sockets, false for nonblocking. default is TRUE.
resouce | $connection |
[ Top ] ### method setState [line 257]
`void setState( int $state)`
Set the current state of the socket. one of define('BS_SOCKETCLIENT_DISCONNECTED', 0); define('BS_SOCKETCLIENT_CONNECTED', 1); define('BS_SOCKETCLIENT_SENT', 2); define('BS_SOCKETCLIENT_REQUEST_SENT', 3); define('BS_SOCKETCLIENT_GOT_REPLY', 4); define('BS_SOCKETCLIENT_GOT_REPLY_HEADER', 5); define('BS_SOCKETCLIENT_GOT_REPLY_CONTENT', 6); #### Tags:
see: | $this->getState, $this->_state
access: | public
#### Parameters:
int | $state | please use the constant.
[ Top ] ### method write [line 521]
`bool write( string $data, [resouce $connection = NULL])`
Write data to the connection. if the param $connection is given, this method is used static. #### Tags:
return: | true on success, false on failure.
see: | Bs_SocketClient::writeLine()
#### Parameters:
string | $data |
resouce | $connection |
[ Top ] ### method writeLine [line 506]
`bool writeLine( string $line, [string $crLf = "\r\n"], [resouce $connection = NULL])`
Write a line to the connection. if the param $connection is given, this method is used static. #### Tags:
return: | true on success, false on failure.
see: | Bs_SocketClient::write()
#### Parameters:
string | $line |
string | $crLf | the carriage return/line feed to add to the line, or any other string. default is "\r\n".
resouce | $connection |
[ Top ] Documentation generated on Mon, 29 Dec 2003 21:12:46 +0100 by phpDocumentor 1.2.3