blueshoes php application framework and cms            core_net
[ class tree: core_net ] [ index: core_net ] [ all elements ]

Class: Bs_SocketClient

Source Location: /core/net/Bs_SocketClient.class.php

Class Overview

Bs_Object
   |
   --Bs_SocketClient

Generalized SocketClient class.


Author(s):

Version:

  • 4.3.$Revision: 1.3 $ $Date: 2003/10/29 17:48:41 $

Copyright:

  • blueshoes.org

Variables

Methods


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