BlueShoes Application Framework - net

Bs_SocketClient

Bs_Object
|
+-- Bs_SocketClient

Generalized SocketClient class.

public class Bs_SocketClient extends Bs_Object

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 codeon a dev machine first.dependencies: Nonebased on pears socket class Stig Bakken <ssb@fast.no> Chuck Hagenbuch <chuck@horde.org>

Authors

Version 4.0.$id$

Copyright blueshoes.org

Methods inherited from Bs_Object

isex, isexception, tostring, tohtml, persist, unpersist, bs_object, bbsetoutput, bbawake, bbisawake, bbxmsg, bbxfunctionstart, bbxfunctionend, bbxecho, bbxvar, bbxvardump, bbforcetrace, bbbufferstart, bbbufferget, bbbufferendflush, bbbufferendclean

Public Method Summary
bool	setBlocking([ string $mode ], string $connection) Sets whether the socket connection should be blocking or
bool	isBlocking() Find out if the socket is in blocking mode.
int	getState() Get the current state of the socket.
void	setState(int $state) Set the current state of the socket.
mixed	connect(string $host, int $port, [ string $persistent, integer $timeOut, string $blocking, string $return ]) Connect to the specified port.
bool	reconnect() Reconnect to the current host with the current settings - if possible.
void	disconnect(string $connection) Disconnects from the peer, closes the socket.
bool	eof(string $connection) if the param $connection is given, this method is used static.
mixed	readLine([ string $removeCrlf ], string $connection) Read from the connection until we got a full line, then return it.
string	readAll(string $connection) Read until the socket closes.
string	gets(int $size, string $connection) Read a specified amount of data, stop when $size is reached, eof or newline.
string	read(int $size, string $connection) Read a specified amount of data, stop when $size is reached or eof. continue on a newline.
bool	writeLine(string $line, [ string $crLf ], string $connection) Write a line to the connection.
bool	write(string $data, string $connection) Write data to the connection.
string	getErrorMessage(long $errCode) Return a textual error message for a bs socket error code
void	Bs_SocketClient() Warning: documentation is missing.

Private Method Summary
void	&_raiseError([ string $code, string $nativeCode, string $msg, string $file, string $line, string $weight ]) This method is called by DB to generate an error.
void	readByte() Warning: documentation is missing.
void	readWord() Warning: documentation is missing.
void	readInt() Warning: documentation is missing.
void	readString() Warning: documentation is missing.
void	readIPAddress() Warning: documentation is missing.

Public Field Summary
string	$host the host we work on.
integer	$port the port we send to.
string	$persistent if the connection should be made persistent or not. default is false.
integer	$timeOut Number of seconds to wait on socket connections before assuming there's no more data.
integer	$lineLength Number of bytes to read at a time in readLine() and readAll().

Private Field Summary
object [unknown]	$_Bs_System Reference to the pseudostatic object.
string	$_blocking Whether the socket is blocking.
string	$_connection the file pointer, our connection.
string	$_state The current state of the connection.

Private Constant Summary
BS_SOCKETCLIENT_VERSION	>>`4.0.$x$`<<	Warning: documentation is missing.
BS_SOCKETCLIENT_DISCONNECTED	>>`0`<<	Warning: documentation is missing.
BS_SOCKETCLIENT_CONNECTED	>>`1`<<	Warning: documentation is missing.
BS_SOCKETCLIENT_SENT	>>`2`<<	Warning: documentation is missing.
BS_SOCKETCLIENT_REQUEST_SENT	>>`3`<<	Warning: documentation is missing.
BS_SOCKETCLIENT_GOT_REPLY	>>`4`<<	Warning: documentation is missing.
BS_SOCKETCLIENT_GOT_REPLY_HEADER	>>`5`<<	Warning: documentation is missing.
BS_SOCKETCLIENT_GOT_REPLY_CONTENT	>>`6`<<	Warning: documentation is missing.
BS_SOCKETCLIENT_ERROR	>>`1`<<	Warning: documentation is missing.
BS_SOCKETCLIENT_ERROR_NEED_MORE_DATA	>>`2`<<	Warning: documentation is missing.
BS_SOCKETCLIENT_ERROR_CONNECT_FAILED	>>`3`<<	Warning: documentation is missing.
BS_SOCKETCLIENT_ERROR_NOT_CONNECTED	>>`4`<<	Warning: documentation is missing.
BS_SOCKETCLIENT_ERROR_WHILE_READ	>>`5`<<	Warning: documentation is missing.
BS_SOCKETCLIENT_ERROR_WHILE_WRITE	>>`6`<<	Warning: documentation is missing.

Public Method Details

setBlocking

public bool setBlocking( [ string $mode ], string $connection )

Sets whether the socket connection should be blocking or
not. A read call to a non-blocking socket will return immediatelyif there is no data available, whereas it will block until thereis data for blocking sockets.note I: nonblocking mode not supported on win (php404). so until it'savailable, 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 thingsreally cannot be done without.

Parameter

string	$mode	`= >>TRUE,<<`
	true for blocking sockets, false for nonblocking. default is TRUE.

string	$connection
	Warning: documentation is missing.

Returns

bool

true if it was possible to set, false if it failed. (fails to set blocking on win)

isBlocking

public bool isBlocking( )

Find out if the socket is in blocking mode.

Returns

bool

the current blocking mode.

getState

public int getState( )

Get the current state of the socket.
one ofdefine('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=disconnectedit's possible that this is set to connected but the connection expiredor something else happened... it's the "should be" state.

Returns

int

the current state.

setState

public void setState( int $state )

Set the current state of the socket.
one ofdefine('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);

Parameter

int	$state
	please use the constant.

Returns

void

connect

public mixed connect( string $host, int $port, [ string $persistent, integer $timeOut, string $blocking, string $return ] )

Connect to the specified port.
If called when param $return is set to 'bool' and the socket is alreadyconnected, it disconnects and connects again.unless called with param $return='resource', these object vars areoverwritten/updated:$this->host $this->_connection$this->port $this->_state$this->timeOut$this->persistent$this->_blocking

Parameter

string	$host
	like 'your.server.com' or an ip address like '111.111.111.111'.

int	$port
	the tcp port number.

string	$persistent	`= >>FALSE,<<`
	default is FALSE.

integer	$timeOut	`= >>0<<`
	default is 0 (which means don't specify one).

string	$blocking	`= >>TRUE,<<`
	default is TRUE. see $this->setBlocking().

string	$return	`= >>'bool'<<`
	one of 'bool' (default) or 'resource'.

Returns

mixed

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

reconnect

public bool reconnect( )

Reconnect to the current host with the current settings - if possible.

Returns

bool

true on success, false on failure or if not capable.

disconnect

public void disconnect( string $connection )

Disconnects from the peer, closes the socket.
if the param $connection is given, this method is used static.

Parameter

string	$connection
	Warning: documentation is missing.

Returns

void

eof

public bool eof( string $connection )

if the param $connection is given, this method is used static.

Parameter

string	$connection
	Warning: documentation is missing.

Returns

bool

readLine

public mixed readLine( [ string $removeCrlf ], string $connection )

Read from the connection until we got a full line, then return it.
if the param $connection is given, this method is used static.

Parameter

string	$removeCrlf	`= >>TRUE,<<`
	if the carriage return/line feed (or lf, whatever there is) at the end should be removed or not. default is TRUE.

string	$connection
	Warning: documentation is missing.

Returns

mixed

string the line or NULL on eof
@throw NULL on an error. we cannot distinguish between error and eof :((( read comment in the code.

readAll

public string readAll( string $connection )

Read until the socket closes.
CAUTION: this method will not exit if the socket is in blocking modeuntil the socket closes.if the param $connection is given, this method is used static.

Parameter

string	$connection
	Warning: documentation is missing.

Returns

string

all data until the socket closes.

gets

public string gets( int $size, string $connection )

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 gettingeverything in one fread() chunk; if you know the size of the datayou're getting beforehand, this is definitely the way to go.if the param $connection is given, this method is used static.

Parameter

int	$size
	the number of bytes to read from the socket.

string	$connection
	Warning: documentation is missing.

Returns

string $size

bytes of data from the socket

read

public string read( int $size, string $connection )

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 gettingeverything in one fread() chunk; if you know the size of the datayou're getting beforehand, this is definitely the way to go.if the param $connection is given, this method is used static.

Parameter

int	$size
	the number of bytes to read from the socket.

string	$connection
	Warning: documentation is missing.

Returns

string $size

bytes of data from the socket

writeLine

public bool writeLine( string $line, [ string $crLf ], string $connection )

Write a line to the connection.
if the param $connection is given, this method is used static.

Parameter

string	$line

string	$crLf	`= >>"\r\n"<<`
	the carriage return/line feed to add to the line, or any other string. default is "\r\n".

string	$connection
	Warning: documentation is missing.

Returns

bool

true on success, false on failure.

write

public bool write( string $data, string $connection )

Write data to the connection.
if the param $connection is given, this method is used static.

Parameter

string	$data

string	$connection
	Warning: documentation is missing.

Returns

bool

true on success, false on failure.

getErrorMessage

public string getErrorMessage( long $errCode )

Return a textual error message for a bs socket error code

Parameter

long	$errCode
	a bs error code (see constants)

Returns

string

error message, or false if the error code was not recognized

Bs_SocketClient

public void Bs_SocketClient( )

Warning: documentation is missing.

Returns

void

Private Method Details

&_raiseError

private void &_raiseError( [ string $code, string $nativeCode, string $msg, string $file, string $line, string $weight ] )

This method is called by DB to generate an error.

Parameter

string	$code	`= >>BS_SOCKETCLIENT_ERROR,<<`

string	$nativeCode	`= >>NULL,<<`

string	$msg	`= >>''<<`

string	$file	`= >>''<<`
	(use __FILE__)

string	$line	`= >>''<<`
	(use __LINE__)

string	$weight	`= >>''<<`
	('fatal')

Returns

void

readByte

private void readByte( )

Warning: documentation is missing.

Returns

void

readWord

private void readWord( )

Warning: documentation is missing.

Returns

void

readInt

private void readInt( )

Warning: documentation is missing.

Returns

void

readString

private void readString( )

Warning: documentation is missing.

Returns

void

readIPAddress

private void readIPAddress( )

Warning: documentation is missing.

Returns

void

Public Field Details
$host
public string $host >>`NULL`<< the host we work on. eg 'your.server.com'

$port
public integer $port >>`80`<< the port we send to.

$persistent
public string $persistent >>`FALSE`<< 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 commentsand you know exactly what you're doing!

$timeOut
public integer $timeOut >><< 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().

$lineLength
public integer $lineLength >>`2048`<< Number of bytes to read at a time in readLine() and readAll().

Private Field Details
$_Bs_System
private object [unknown] $_Bs_System >><< Reference to the pseudostatic object.

$_blocking
private string $_blocking >>`TRUE`<< Whether the socket is blocking.

$_connection
private string $_connection >>`NULL`<< the file pointer, our connection.

$_state
private string $_state >>`BS_SOCKETCLIENT_DISCONNECTED`<< The current state of the connection. one ofdefine('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);it's possible that this is set to connected but the connection expiredor something else happened... it's the "should be" state.

Private Constant Details
BS_SOCKETCLIENT_VERSION `define( BS_SOCKETCLIENT_VERSION, >>4.0.$x$<< )` Case: default: case sensitive

BS_SOCKETCLIENT_DISCONNECTED `define( BS_SOCKETCLIENT_DISCONNECTED, >>0<< )` Case: default: case sensitive

BS_SOCKETCLIENT_CONNECTED `define( BS_SOCKETCLIENT_CONNECTED, >>1<< )` Case: default: case sensitive

BS_SOCKETCLIENT_SENT `define( BS_SOCKETCLIENT_SENT, >>2<< )` Case: default: case sensitive

BS_SOCKETCLIENT_REQUEST_SENT `define( BS_SOCKETCLIENT_REQUEST_SENT, >>3<< )` Case: default: case sensitive

BS_SOCKETCLIENT_GOT_REPLY `define( BS_SOCKETCLIENT_GOT_REPLY, >>4<< )` Case: default: case sensitive

BS_SOCKETCLIENT_GOT_REPLY_HEADER `define( BS_SOCKETCLIENT_GOT_REPLY_HEADER, >>5<< )` Case: default: case sensitive

BS_SOCKETCLIENT_GOT_REPLY_CONTENT `define( BS_SOCKETCLIENT_GOT_REPLY_CONTENT, >>6<< )` Case: default: case sensitive

BS_SOCKETCLIENT_ERROR `define( BS_SOCKETCLIENT_ERROR, >>1<< )` Case: default: case sensitive

BS_SOCKETCLIENT_ERROR_NEED_MORE_DATA `define( BS_SOCKETCLIENT_ERROR_NEED_MORE_DATA, >>2<< )` Case: default: case sensitive

BS_SOCKETCLIENT_ERROR_CONNECT_FAILED `define( BS_SOCKETCLIENT_ERROR_CONNECT_FAILED, >>3<< )` Case: default: case sensitive

BS_SOCKETCLIENT_ERROR_NOT_CONNECTED `define( BS_SOCKETCLIENT_ERROR_NOT_CONNECTED, >>4<< )` Case: default: case sensitive

BS_SOCKETCLIENT_ERROR_WHILE_READ `define( BS_SOCKETCLIENT_ERROR_WHILE_READ, >>5<< )` Case: default: case sensitive

BS_SOCKETCLIENT_ERROR_WHILE_WRITE `define( BS_SOCKETCLIENT_ERROR_WHILE_WRITE, >>6<< )` Case: default: case sensitive

PHPDoc 1.0beta

BlueShoes Application Framework - net

Bs_SocketClient

public class Bs_SocketClient extends Bs_Object

Methods inherited from Bs_Object

Public Method Summary

setBlocking([ string $mode ], string $connection)

isBlocking()

getState()

setState(int $state)

connect(string $host, int $port, [ string $persistent, integer $timeOut, string $blocking, string $return ])

reconnect()

disconnect(string $connection)

eof(string $connection)

readLine([ string $removeCrlf ], string $connection)

readAll(string $connection)

gets(int $size, string $connection)

read(int $size, string $connection)

writeLine(string $line, [ string $crLf ], string $connection)

write(string $data, string $connection)

getErrorMessage(long $errCode)

Bs_SocketClient()

Private Method Summary

&_raiseError([ string $code, string $nativeCode, string $msg, string $file, string $line, string $weight ])

readByte()

readWord()

readInt()

readString()

readIPAddress()

Public Field Summary

$host

$port

$persistent

$timeOut

$lineLength

Private Field Summary

$_Bs_System

$_blocking

$_connection

$_state

Private Constant Summary

Public Method Details

setBlocking

isBlocking

getState

setState

connect

reconnect

disconnect

eof

readLine

readAll

gets

read

writeLine

write

getErrorMessage

Bs_SocketClient

Private Method Details

&_raiseError

readByte

readWord

readInt

readString

readIPAddress

Public Field Details

$host

$port

$persistent

$timeOut

$lineLength

Private Field Details

$_Bs_System

$_blocking

$_connection

$_state

Private Constant Details

BS_SOCKETCLIENT_VERSION

BS_SOCKETCLIENT_DISCONNECTED

BS_SOCKETCLIENT_CONNECTED

BS_SOCKETCLIENT_SENT