File: cIMSPStream.php

<?php
 /******************************************************************************************************
 * Project: PHP IMSP CLIENT LIBRARY  
 * FILE: 		cIMSPStream.PHP
 * PROVIDES: 	Basic IMSP connectivity and defines the CIMSPStream object.
 *
 * Copyright 2002 Michael Rubinsky <mike@theupstairsroom.com>
 *
 *  This program is free software; you can redistribute it and/or modify
 *  it under the terms of the GNU General Public License as published by
 *  the Free Software Foundation; either version 2 of the License, or
 *  (at your option) any later version.
 *
 *  This program is distributed in the hope that it will be useful,
 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 *  GNU General Public License for more details.
 *
 *  You should have received a copy of the GNU General Public License
 *  along with this program; if not, write to the Free Software
 *  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 *
 ********************************************************************************************************

 * Change Log:
 *
 *  4/16/02: mjr Version 1.1
 * 		
 *		-Improved the imspError() routine for more informative error messages.
 *		-Added a showImspErrors property to allow turning on and off the display of the IMSP specific errors.
 *		 (This does not affect the behaviour of PHP errors).
 *		-Released project under the GNU GPL
 *	
 *	3/19/02: mjr
 *		
 *		-Changed the imspRecieve() function making it responsible for determining if the server returns
 *		 a "OK", "BAD" or "NO" response.  It returns the words "OK", "BAD", or "NO" if that is the case.
 *		 All other server responses are passed back as-is to the caller.  Any failures are still reported
 *		 as a returned FALSE.
 *	
 * 3/31/02: mjr
 *		 
 *		-Updated the constructor function and the logout() function to use the new imspSend() and 
 *		 imspRecieve() routines.
 *
 *		-Seperated out the authentication code into a seperate function to allow for easier future
 *       support of other Authentication mechs.
 *		
 *		-Added beginnings of an error handling scheme.
 ********************************************************************************************************/
//Constant Definitions
define("IMSP_CRLF","\r\n");
define("IMSP_RESPONSE_TAG_LENGTH",5);
define("IMSP_DEFAULT_RESPONSE_LENGTH",512);

//These define regExp that should match the respective server response strings
define ("IMSP_CONNECTION_OK","^\* OK");
define ("IMSP_LOGIN_OK","OK User");
define ("IMSP_COMMAND_CONTINUATION_RESPONSE","^\+");

//Exit code values
define ("IMSP_EXIT_LOGIN_FAILED","Login to host failed");
define ("IMSP_EXIT_CONNECTION_FAILED","Connection failure");
define ("IMSP_NOT_EXPECTED_RESPONSE", "Did not recieve the expected response from the server.");
define ("IMSP_EXIT_UNEXPECTED_RESPONSE", "Did not recieve the expected response from the server.");		//For compatability
define ("IMSP_SYNTAX_ERROR","The server did not understand your request.");
define ("IMSP_BAD_SYNTAX","The server did not understand your request.");								//For backwards compatability.
define ("IMSP_NO","Server returned a NO response");		
define ("IMSP_EXIT_BAD_ARGUMENT","The wrong type of arguement was passed to this function");		
define ("IMSP_ENTRY_LOCKED","That addressbook entry is locked or cannot be unlocked.");
						
class IMSPStream {
	/****************************************************************************************
 	* Public Property Declarations
 	****************************************************************************************/
 	var $imsp_server = "localhost";									//Defaults to "localhost" for the IMSP server host 	
	var $imsp_port = "406"; 										//...on the default port
 	var $user;														//Property for the username
 	var $pass;														//Holds the user's password
 	var $auth_method = "PLAIN";										//Set this to the type of Authentication Method to be used. (ONLY PLAIN SUPPORTED AT THIS TIME)	
 	var $exitCode;													//Routines may place exit codes into this property for checking by the client application
 	var $log_name = "imspstream.log";								//The name of the log to write to if logging enabled.
 	var $logging = true;											//Set this to "TRUE" to enable logging.
	var $log_level = 2;												// 1 = Normal user level logging 																
																	// 2 = Include client debugging info (response strings etc..)
	
	var $seperator = ".";											//Heirarchy seperator (not used in the class...here as a convienience to the client)
	var $showImspErrors = TRUE;										//Determines if IMSP errors are passed thru to the client.
	
	/****************************************************************************************
 	* "Private" or "Friend" Declarations
 	****************************************************************************************/
 	var $commandPrefix = "A";										//Holds the current alphabetic portion of command tag	
 	var $commandCount = 1;											//Holds the current numeric portion of the command tag
 	var $tag = "";													//Holds the most current command tag
 	var $stream;													//reference to the file pointer for the IMSP stream
 	var $log_stream;												//file stream to log file;
	var $connectionID; 												//Holds uniques identifier for this connection (used only for logging purposes as of this version)


function IMSPStream($local_imsp_server="", $local_port="") {
 	
	// Check for passed in values for server and port number
 	if ($local_imsp_server) {
 		$this->imsp_server = $local_imsp_server;
 	}
 	
 	if($local_port) {
 		$this->imsp_port = $local_port;
 	}
 	
 	$this->connectionID = time();								//get a somewhat unique identifier...good enough for logging purposes.
 	
 	 		 	
 }

function login($username,$pass) {
	
	
	$this->user = $username;
	$this->pass = $pass;
	
	
	if ($this->logging) {
 		$this->open_log($this->log_name);							//open log
 		$this->write_to_log("Starting IMSP Session");
 	}
 	
  	
 	// Now try to open the IMSP connection
	if (!$this->imspOpen()) {
		$this->imspError();
		return FALSE;
	}
	 
	 if ($this->log_stream) {
 	  	$this->write_to_log("Connection OK");
 	 }

 
 	/*Everything is ok...so try to login to the server
 	 *For now, we do things simply, using LOGIN command
 	 *
 	 *in release version, we will want to support SASL logins
 	 */
 	 Switch ($this->auth_method) {
 	 	case "PLAIN":
 	 		if (!$this->imspPlainTextLogin()) {
 	 			//Login failed
 	
 	 			if($this->exitCode = "") {
	 	 			$this->exit_code = IMSP_EXIT_LOGIN_FAILED;
 				}
 				
 				
 	 			//$this->imspError();
 	 			return FALSE;
 	 		}
 	 		
 	 		break;
 	 		
 	 	default:
 	 		//must specify an auth method 
 	 		$this->exit_code = IMSP_EXIT_LOGIN_FAILED;
 	 		$this->imspError("Must specify an authentication method in the auth_method property.");
 	 		return FALSE;
 	 }
 	 
 	//OK. We are logged in to the server
 	
 	if ($this->log_stream) {
 		$this->write_to_log("LOGIN for user $this->user successful.");
 	 }
 	return TRUE;

}
/****************************************************************************************
 *logout() - logs out of the server and closes the IMSP stream
 ****************************************************************************************/
function logout() {
	//Disconnect from the server
	
	if($this->log_stream){
		$this->write_to_log("Closing Connection.");
	}
	
	
		$command_string = "LOGOUT";				//Build the command to send to the server
	
		if (!$this->imspSend($command_string)) {
			$this->imspError();
			return FALSE;
		} else {
			//Should we test here for the BYE response? Is there a need for this?
			
			fclose($this->stream);
			
			if ($this->log_stream) {
				$this->close_log();
			}
			
			return TRUE;
		}
		
	
}




/**************************************************************************************
 * IMSP connectivity functions
 *************************************************************************************/

function imspOpen() {
	// Now try to open the IMSP connection
 	$fp = fsockopen($this->imsp_server,$this->imsp_port);
 	
 	
 	// Check for failure
 	if(!$fp) {
 		$this->exit_code = IMSP_CONNECTION_FAILED;
 		$this->imspError();
 		return FALSE;	
 	}
 	
 	//save the file pointer
 	$this->stream = $fp;

 	//Get The Server Response
 	$server_response = $this->imspRecieve();
 		
 		 	
 	//Check that it is what was expected
 	if(!ereg(IMSP_CONNECTION_OK,$server_response)) {
 		$this->exit_code = IMSP_NOT_EXPECTED_RESONSE;
 		$this->imspError();
 		fclose($fp);
 		return FALSE; 
 		
 	}

	return TRUE;
	
}


function imspSend($commandText, $includeTag = TRUE, $sendCRLF=TRUE){
	
	if(!$this->stream){
		//no connection!!
		$this->exit_code = IMSP_EXIT_CONNECTION_FAILED;
		return FALSE;
	}
	
	if ($includeTag) {
		$this->tag = $this->getNextCommandTag();
		$command_text = "$this->tag ";
	}
	
	$command_text .= $commandText;
	
	
	if ($sendCRLF) {	
		$command_text .= IMSP_CRLF;
	}
	
	
	if ($this->log_stream && $this->log_level > 1) {
		$this->write_to_log("[CLIENT COMMAND] $command_text");
	}
	
	if (!fputs($this->stream,$command_text)) {
		//something wrong with connection?
		$this->exit_code = IMSP_EXIT_CONNECTION_FAILED;
		return FALSE;
		
	} else {
	
		return TRUE;
																	//don't forget to report success!	
	}
	
}

function imspRecieve() {
	//Recieves a single CRLF terminated server status response from the server.
	
	if (!$this->stream){
		//no connection!!
		$this->exit_code = IMSP_EXIT_CONNECTION_FAILED;
		return FALSE;
	}
	
	$server_response = trim(fgets($this->stream,IMSP_DEFAULT_RESPONSE_LENGTH));
	
	if ($this->log_stream && $this->log_level > 1) {
		$this->write_to_log("[SERVER RESPONSE] $server_response");
	}
	
	//should we see if the response is simply an OK, BAD or NO in response to an tagged command?
	
	//Parse out the response
	$currentTag = $this->tag;
	if (ereg("^" . $currentTag . " NO", $server_response)) {
		//Could not perform action.
		$this->exitCode = IMSP_NO;
		return "NO";

	}
	
	if (ereg("^" . $currentTag . " BAD",$server_response)) {
		//Bad syntax or entry names
		$this->exitCode = IMSP_SYNTAX_ERROR;
		return "BAD";
	}
	
	if (ereg("^" . $currentTag . " OK",$server_response)) {
		return "OK";
	}

	//If it was not a "NO", "BAD" or "OK" response, then it is up to the 
	//calling function to decide what to do with it 
	return $server_response;
}

function getServerResponseChunks(){
	//Retrieves a CRLF terminated response from the server and splits it into an array delimeted by a <space> and returns array
	$server_response = trim(fgets($this->stream,IMSP_DEFAULT_RESPONSE_LENGTH));
	$chunks = split(" ",$server_response);
	return $chunks;
}



function recieveStringLiteral($length){

	return	trim(fread($this->stream,$length));

}

/**************************************************************************************
 *Authentication Routines
 *************************************************************************************/
 function imspPlainTextLogin() {
 
 	/*Everything is ok...so try to login to the server
 	 *For now, we do things simply, using LOGIN command
 	 *
 	 *in release version, we will want to support SASL logins
 	 */
 	 
 	//Now build the command string
 	$command_string = "LOGIN $this->user $this->pass";
 	
 	//make sure any logging is at level 1 only to ensure no password information
 	//will be sent to the log during the imspSend() call.
 	$logLevel = $this->log_level;
 	$this->log_level = 1;
 	
 	
 	if (!$this->imspSend($command_string)) {
 		$this->exitCode = IMSP_CONNECTION_FAILURE;
 		return FALSE;
 	}
 	
 	//restore original logging level
 	$this->log_level = $logLevel;
 	
 	//Get the response
 	$server_response = $this->imspRecieve();
 	
 	if ($server_response!="OK") {
 		//login failed
 		$this->exitCode = IMSP_LOGIN_FAILED;
 		return FALSE;
 	}
 	
 		return TRUE;
 }
 
 
 
/**************************************************************************************
 * Utility Functions
 *************************************************************************************/
function getNextCommandTag() {
		
		$newtag = $this->commandPrefix;
		
	 	if ($this->commandCount < 10) {
			$newtag .= "000" . (string) $this->commandCount;
		} elseif ($this->commandCount < 100){
			$newtag .= "00" . (string) $this->commandCount;
		} elseif ($this->commandCount < 999) {
			$newtag .= "0" . (string) $this->commandCount;
		}
		
		//increment it for the next command
		$this->commandCount++;
		
		return $newtag;
}

function quoteSpacedString($string) {
	
	if (ereg(" ",$string)) {
		return "\"" . $string . "\"";
	} else {
		return $string;
	}
}

function imspError($server_text = "") {

	if ($this->log_stream) {
		$this->write_to_log("[ERROR]$this->exit_code");
	}
	
	if ($this->showImspErrors) {
		echo("There was an error with the IMSP service.\n");
		echo("\tThe error code is: $this->exitCode\n");
		
		if($server_text != "") {
			echo("\tThe following information is also available: $server_text\n");
		}
	}
	
	//reset the exitCode
	$this->exitCode = "";
	
}





/******************************************************************************************
 *Logging functions
 *****************************************************************************************/
 
function open_log($logfile){
	
	$fp = @fopen("log/" . $logfile,"a");
	
	if (!$fp) {
		return FALSE;
	} else {
		$this->log_stream = $fp;
		return TRUE;
	 }
}
	
function write_to_log($message) {
	@fputs($this->log_stream,date("r") . ":[$this->connectionID][$this->user] $message\n");
}

function close_log(){
	@fclose($this->log_stream);
}


}//End of Class Definition

?>