XSServer · Xunsearch 中文文档

[Xunsearch PHP-SDK](http://www.xunsearch.com) v1.4.8 API 参考文档 # XSServer [All Packages](#)| [属性](#)| [方法(函数)](#) | 包 | [XS](#) | |-----|-----| | 继承关系 | class XSServer »[XSComponent](#) | | 子类 | [XSIndex](#), [XSSearch](#) | | 版本 | 1.0.0 | | 源代码 | [sdk/php/lib/XSServer.class.php](https://github.com/hightman/xunsearch/blob/master/sdk/php/lib/XSServer.class.php) | XSServer 服务器操作对象同时兼容于 indexd, searchd, 所有交互均采用 [XSCommand](#) 对象 ### Public 属性 [隐去继承来的属性](#) | 名称 | 类型 | 描述 | 定义于 | |-----|-----|-----|-----| | [connString](#) | string | 连接字符串 | XSServer | | [project](#) | string | 获取当前项目名称 | XSServer | | [respond](#) | [XSCommand](#) | 从服务器读取响应指令 | XSServer | | [socket](#) | mixed | 获取连接资源描述符 | XSServer | | [xs](#) | [XS](#) | 服务端关联的 XS 对象 | XSServer | ### Protected 属性 [隐去继承来的属性](#) | 名称 | 类型 | 描述 | 定义于 | |-----|-----|-----|-----| | [_conn](#) | | | XSServer | | [_flag](#) | | | XSServer | | [_project](#) | | | XSServer | | [_sendBuffer](#) | | | XSServer | | [_sock](#) | | | XSServer | ### Public 方法 [隐去继承来的方法](#) | 名称 | 描述 | 定义于 | |-----|-----|-----| | [__construct()](#) | 构造函数, 打开连接 | XSServer | | [__destruct()](#) | 析构函数, 关闭连接 | XSServer | | [__get()](#) | 魔术方法 __get | [XSComponent](#) | | [__isset()](#) | 魔术方法 __isset | [XSComponent](#) | | [__set()](#) | 魔术方法 __set | [XSComponent](#) | | [__unset()](#) | 魔术方法 __unset | [XSComponent](#) | | [close()](#) | 关闭连接 | XSServer | | [execCommand()](#) | 执行服务端指令并获取返回值 | XSServer | | [getConnString()](#) | Returns 连接字符串 | XSServer | | [getProject()](#) | 获取当前项目名称 | XSServer | | [getRespond()](#) | 从服务器读取响应指令 | XSServer | | [getSocket()](#) | 获取连接资源描述符 | XSServer | | [hasRespond()](#) | 判断服务端是否有可读数据 | XSServer | | [open()](#) | 打开服务端连接 | XSServer | | [reopen()](#) | 重新打开连接 | XSServer | | [sendCommand()](#) | 往服务器直接发送指令 (无缓存) | XSServer | | [setProject()](#) | 设置当前项目 | XSServer | | [setTimeout()](#) | 设置服务端超时秒数 | XSServer | ### Protected 方法 [隐去继承来的方法](#) | 名称 | 描述 | 定义于 | |-----|-----|-----| | [check()](#) | 检测服务端的连接情况 | XSServer | | [connect()](#) | 连接服务端 | XSServer | | [read()](#) | 读取数据 | XSServer | | [write()](#) | 写入数据 | XSServer | ### 属性明细 _conn属性 protected **$_conn**; _flag属性 protected **$_flag**; _project属性 protected **$_project**; _sendBuffer属性 protected **$_sendBuffer**; _sock属性 protected **$_sock**; connString属性 *只读* public string [**getConnString**](#)() 连接字符串 project属性 public string [**getProject**](#)() public void [**setProject**](#)(string $name, string $home='') 获取当前项目名称 respond属性 *只读* public [XSCommand](#)[**getRespond**](#)() 从服务器读取响应指令 socket属性 *只读* public mixed [**getSocket**](#)() 获取连接资源描述符 xs属性 public [XS](#)**$xs**; 服务端关联的 XS 对象 ### 方法明细 __construct()方法 <table class="summaryTable"><tr><td colspan="3"><div class="signature2">public void <b>__construct</b>(string $conn=NULL, <a href="XS.html">XS</a> $xs=NULL)</div></td></tr><tr><td class="paramNameCol">$conn</td> <td class="paramTypeCol">string</td> <td class="paramDescCol">服务端连接参数</td></tr><tr><td class="paramNameCol">$xs</td> <td class="paramTypeCol"><a href="XS.html">XS</a></td> <td class="paramDescCol">需要捆绑的 xs 对象</td></tr></table> **源码:**[sdk/php/lib/XSServer.class.php#L143](https://github.com/hightman/xunsearch/blob/master/sdk/php/lib/XSServer.class.php#L143) (**[显示](#)**) `public function __construct($conn = null, $xs = null) { $this->xs = $xs; if ($conn !== null) { $this->open($conn); } }` 构造函数, 打开连接 __destruct()方法 <table class="summaryTable"><tr><td colspan="3"><div class="signature2">public void <b>__destruct</b>()</div></td></tr></table> **源码:**[sdk/php/lib/XSServer.class.php#L154](https://github.com/hightman/xunsearch/blob/master/sdk/php/lib/XSServer.class.php#L154) (**[显示](#)**) `public function __destruct() { $this->xs = null; $this->close(); }` 析构函数, 关闭连接 check()方法 <table class="summaryTable"><tr><td colspan="3"><div class="signature2">protected void <b>check</b>()</div></td></tr></table> **源码:**[sdk/php/lib/XSServer.class.php#L438](https://github.com/hightman/xunsearch/blob/master/sdk/php/lib/XSServer.class.php#L438) (**[显示](#)**) `protected function check() { if ($this->_sock === null) { throw new XSException('No server connection'); } if ($this->_flag & self::BROKEN) { throw new XSException('Broken server connection'); } }` 检测服务端的连接情况 close()方法 <table class="summaryTable"><tr><td colspan="3"><div class="signature2">public void <b>close</b>(bool $ioerr=false)</div></td></tr><tr><td class="paramNameCol">$ioerr</td> <td class="paramTypeCol">bool</td> <td class="paramDescCol">关闭调用是否由于 IO 错误引起的, 以免发送 quit 指令</td></tr></table> **源码:**[sdk/php/lib/XSServer.class.php#L198](https://github.com/hightman/xunsearch/blob/master/sdk/php/lib/XSServer.class.php#L198) (**[显示](#)**) `public function close($ioerr = false) { if ($this->_sock && !($this->_flag & self::BROKEN)) { if (!$ioerr && $this->_sendBuffer !== '') { $this->write($this->_sendBuffer); $this->_sendBuffer = ''; } if (!$ioerr && !($this->_flag & self::FILE)) { $cmd = new XSCommand(CMD_QUIT); fwrite($this->_sock, $cmd); } fclose($this->_sock); $this->_flag |= self::BROKEN; } }` 关闭连接附带发送发送 quit 命令 connect()方法 <table class="summaryTable"><tr><td colspan="3"><div class="signature2">protected void <b>connect</b>()</div></td></tr></table> **源码:**[sdk/php/lib/XSServer.class.php#L452](https://github.com/hightman/xunsearch/blob/master/sdk/php/lib/XSServer.class.php#L452) (**[显示](#)**) `protected function connect() { // connect to server $conn = $this->_conn; if (is_int($conn) || is_numeric($conn)) { $host = 'localhost'; $port = intval($conn); } elseif (!strncmp($conn, 'file://', 7)) { // write-only for saving index exchangable data to file // NOTE: this will cause file content be turncated $conn = substr($conn, 7); if (($sock = @fopen($conn, 'wb')) === false) { throw new XSException('Failed to open local file for writing: `' . $conn . '\''); } $this->_flag |= self::FILE; $this->_sock = $sock; return; } elseif (($pos = strpos($conn, ':')) !== false) { $host = substr($conn, 0, $pos); $port = intval(substr($conn, $pos + 1)); } else { $host = 'unix://' . $conn; $port = -1; } if (($sock = @fsockopen($host, $port, $errno, $error, 5)) === false) { throw new XSException($error . '(C#' . $errno . ', ' . $host . ':' . $port . ')'); } // set socket options $timeout = ini_get('max_execution_time'); $timeout = $timeout > 0 ? ($timeout - 1) : 30; stream_set_blocking($sock, true); stream_set_timeout($sock, $timeout); $this->_sock = $sock; }` 连接服务端 execCommand()方法 <table class="summaryTable"><tr><td colspan="3"><div class="signature2">public mixed <b>execCommand</b>(mixed $cmd, int $res_arg=0, int $res_cmd=128)</div></td></tr><tr><td class="paramNameCol">$cmd</td> <td class="paramTypeCol">mixed</td> <td class="paramDescCol">要提交的指令, 若不是 XSCommand 实例则作为构造函数的第一参数创建对象</td></tr><tr><td class="paramNameCol">$res_arg</td> <td class="paramTypeCol">int</td> <td class="paramDescCol">要求的响应参数, 默认为 CMD_NONE 即不检测, 若检测结果不符则认为命令调用失败, 会返回 false 并设置相应的出错信息</td></tr><tr><td class="paramNameCol">$res_cmd</td> <td class="paramTypeCol">int</td> <td class="paramDescCol">要求的响应指令, 默认为 CMD_OK 即要求结果必须正确.</td></tr><tr><td class="paramNameCol">{return}</td> <td class="paramTypeCol">mixed</td> <td class="paramDescCol">若无需要检测结果则返回 true, 其它返回响应的 XSCommand 对象</td></tr></table> **源码:**[sdk/php/lib/XSServer.class.php#L279](https://github.com/hightman/xunsearch/blob/master/sdk/php/lib/XSServer.class.php#L279) (**[显示](#)**) `public function execCommand($cmd, $res_arg = CMD_NONE, $res_cmd = CMD_OK) { // create command object if (!$cmd instanceof XSCommand) { $cmd = new XSCommand($cmd); } // just cache the cmd for those need not answer if ($cmd->cmd & 0x80) { $this->_sendBuffer .= $cmd; return true; } // send cmd to server $buf = $this->_sendBuffer . $cmd; $this->_sendBuffer = ''; $this->write($buf); // return true directly for local file if ($this->_flag & self::FILE) { return true; } // got the respond $res = $this->getRespond(); // check respond if ($res->cmd === CMD_ERR && $res_cmd != CMD_ERR) { throw new XSException($res->buf, $res->arg); } // got unexpected respond command if ($res->cmd != $res_cmd || ($res_arg != CMD_NONE && $res->arg != $res_arg)) { throw new XSException('Unexpected respond {CMD:' . $res->cmd . ', ARG:' . $res->arg . '}'); } return $res; }` 执行服务端指令并获取返回值 getConnString()方法 <table class="summaryTable"><tr><td colspan="3"><div class="signature2">public string <b>getConnString</b>()</div></td></tr><tr><td class="paramNameCol">{return}</td> <td class="paramTypeCol">string</td> <td class="paramDescCol">连接字符串</td></tr></table> **源码:**[sdk/php/lib/XSServer.class.php#L217](https://github.com/hightman/xunsearch/blob/master/sdk/php/lib/XSServer.class.php#L217) (**[显示](#)**) `public function getConnString() { $str = $this->_conn; if (is_int($str) || is_numeric($str)) { $str = 'localhost:' . $str; } elseif (strpos($str, ':') === false) { $str = 'unix://' . $str; } return $str; }` getProject()方法 <table class="summaryTable"><tr><td colspan="3"><div class="signature2">public string <b>getProject</b>()</div></td></tr><tr><td class="paramNameCol">{return}</td> <td class="paramTypeCol">string</td> <td class="paramDescCol">项目名称</td></tr></table> **源码:**[sdk/php/lib/XSServer.class.php#L241](https://github.com/hightman/xunsearch/blob/master/sdk/php/lib/XSServer.class.php#L241) (**[显示](#)**) `public function getProject() { return $this->_project; }` 获取当前项目名称 getRespond()方法 <table class="summaryTable"><tr><td colspan="3"><div class="signature2">public <a href="XSCommand.html">XSCommand</a> <b>getRespond</b>()</div></td></tr><tr><td class="paramNameCol">{return}</td> <td class="paramTypeCol"><a href="XSCommand.html">XSCommand</a></td> <td class="paramDescCol">成功返回响应指令</td></tr></table> **源码:**[sdk/php/lib/XSServer.class.php#L334](https://github.com/hightman/xunsearch/blob/master/sdk/php/lib/XSServer.class.php#L334) (**[显示](#)**) `public function getRespond() { // read data from server $buf = $this->read(8); $hdr = unpack('Ccmd/Carg1/Carg2/Cblen1/Iblen', $buf); $res = new XSCommand($hdr); $res->buf = $this->read($hdr['blen']); $res->buf1 = $this->read($hdr['blen1']); return $res; }` 从服务器读取响应指令 getSocket()方法 <table class="summaryTable"><tr><td colspan="3"><div class="signature2">public mixed <b>getSocket</b>()</div></td></tr><tr><td class="paramNameCol">{return}</td> <td class="paramTypeCol">mixed</td> <td class="paramDescCol">连接标识, 仅用于内部测试等目的</td></tr></table> **源码:**[sdk/php/lib/XSServer.class.php#L232](https://github.com/hightman/xunsearch/blob/master/sdk/php/lib/XSServer.class.php#L232) (**[显示](#)**) `public function getSocket() { return $this->_sock; }` 获取连接资源描述符 hasRespond()方法 <table class="summaryTable"><tr><td colspan="3"><div class="signature2">public bool <b>hasRespond</b>()</div></td></tr><tr><td class="paramNameCol">{return}</td> <td class="paramTypeCol">bool</td> <td class="paramDescCol">如果有返回 true, 否则返回 false</td></tr></table> **源码:**[sdk/php/lib/XSServer.class.php#L350](https://github.com/hightman/xunsearch/blob/master/sdk/php/lib/XSServer.class.php#L350) (**[显示](#)**) `public function hasRespond() { // check socket if ($this->_sock === null || $this->_flag & (self::BROKEN | self::FILE)) { return false; } $wfds = $xfds = array(); $rfds = array($this->_sock); $res = stream_select($rfds, $wfds, $xfds, 0, 0); return $res > 0; }` 判断服务端是否有可读数据用于某些特别情况在 [getRespond](#) 前先调用和判断, 以免阻塞 open()方法 <table class="summaryTable"><tr><td colspan="3"><div class="signature2">public void <b>open</b>(mixed $conn)</div></td></tr><tr><td class="paramNameCol">$conn</td> <td class="paramTypeCol">mixed</td> <td class="paramDescCol">服务端连接参数, 支持: <端口号|host:port|本地套接字路径></td></tr></table> **源码:**[sdk/php/lib/XSServer.class.php#L165](https://github.com/hightman/xunsearch/blob/master/sdk/php/lib/XSServer.class.php#L165) (**[显示](#)**) `public function open($conn) { $this->close(); $this->_conn = $conn; $this->_flag = self::BROKEN; $this->_sendBuffer = ''; $this->_project = null; $this->connect(); $this->_flag ^= self::BROKEN; if ($this->xs instanceof XS) { $this->setProject($this->xs->getName()); } }` 打开服务端连接如果已关联 XS 对象, 则会同时切换至相应的项目名称 read()方法 <table class="summaryTable"><tr><td colspan="3"><div class="signature2">protected string <b>read</b>(int $len)</div></td></tr><tr><td class="paramNameCol">$len</td> <td class="paramTypeCol">int</td> <td class="paramDescCol">要读入的长度</td></tr><tr><td class="paramNameCol">{return}</td> <td class="paramTypeCol">string</td> <td class="paramDescCol">成功时返回读到的字符串</td></tr></table> **源码:**[sdk/php/lib/XSServer.class.php#L404](https://github.com/hightman/xunsearch/blob/master/sdk/php/lib/XSServer.class.php#L404) (**[显示](#)**) `protected function read($len) { // quick return for zero size if ($len == 0) { return ''; } // loop to send data $this->check(); for ($buf = '', $size = $len;;) { $bytes = fread($this->_sock, $len); if ($bytes === false || strlen($bytes) == 0) { break; } $len -= strlen($bytes); $buf .= $bytes; if ($len === 0) { return $buf; } } // error occured $meta = stream_get_meta_data($this->_sock); $this->close(true); $reason = $meta['timed_out'] ? 'timeout' : ($meta['eof'] ? 'closed' : 'unknown'); $msg = 'Failed to recv the data from server completely '; $msg .= '(SIZE:' . ($size - $len) . '/' . $size . ', REASON:' . $reason . ')'; throw new XSException($msg); }` 读取数据 reopen()方法 <table class="summaryTable"><tr><td colspan="3"><div class="signature2">public XSServer <b>reopen</b>(bool $force=false)</div></td></tr><tr><td class="paramNameCol">$force</td> <td class="paramTypeCol">bool</td> <td class="paramDescCol">是否强制重新连接, 默认为否</td></tr><tr><td class="paramNameCol">{return}</td> <td class="paramTypeCol">XSServer</td> <td class="paramDescCol">返回自己, 以便串接操作</td></tr></table> **源码:**[sdk/php/lib/XSServer.class.php#L185](https://github.com/hightman/xunsearch/blob/master/sdk/php/lib/XSServer.class.php#L185) (**[显示](#)**) `public function reopen($force = false) { if ($this->_flag & self::BROKEN || $force === true) { $this->open($this->_conn); } return $this; }` 重新打开连接仅应用于曾经成功打开的连并且异常关闭了 sendCommand()方法 <table class="summaryTable"><tr><td colspan="3"><div class="signature2">public void <b>sendCommand</b>(mixed $cmd)</div></td></tr><tr><td class="paramNameCol">$cmd</td> <td class="paramTypeCol">mixed</td> <td class="paramDescCol">要提交的指令, 支持 XSCommand 实例或 cmd 构造函数的第一参数</td></tr></table> **源码:**[sdk/php/lib/XSServer.class.php#L321](https://github.com/hightman/xunsearch/blob/master/sdk/php/lib/XSServer.class.php#L321) (**[显示](#)**) `public function sendCommand($cmd) { if (!$cmd instanceof XSCommand) { $cmd = new XSCommand($cmd); } $this->write(strval($cmd)); }` 往服务器直接发送指令 (无缓存) setProject()方法 <table class="summaryTable"><tr><td colspan="3"><div class="signature2">public void <b>setProject</b>(string $name, string $home='')</div></td></tr><tr><td class="paramNameCol">$name</td> <td class="paramTypeCol">string</td> <td class="paramDescCol">项目名称</td></tr><tr><td class="paramNameCol">$home</td> <td class="paramTypeCol">string</td> <td class="paramDescCol">项目在服务器上的目录路径, 可选参数(不得超过255字节).</td></tr></table> **源码:**[sdk/php/lib/XSServer.class.php#L251](https://github.com/hightman/xunsearch/blob/master/sdk/php/lib/XSServer.class.php#L251) (**[显示](#)**) `public function setProject($name, $home = '') { if ($name !== $this->_project) { $cmd = array('cmd' => CMD_USE, 'buf' => $name, 'buf1' => $home); $this->execCommand($cmd, CMD_OK_PROJECT); $this->_project = $name; } }` 设置当前项目 setTimeout()方法 <table class="summaryTable"><tr><td colspan="3"><div class="signature2">public void <b>setTimeout</b>(int $sec)</div></td></tr><tr><td class="paramNameCol">$sec</td> <td class="paramTypeCol">int</td> <td class="paramDescCol">秒数, 设为 0则永不超时直到客户端主动关闭</td></tr></table> **源码:**[sdk/php/lib/XSServer.class.php#L264](https://github.com/hightman/xunsearch/blob/master/sdk/php/lib/XSServer.class.php#L264) (**[显示](#)**) `public function setTimeout($sec) { $cmd = array('cmd' => CMD_TIMEOUT, 'arg' => $sec); $this->execCommand($cmd, CMD_OK_TIMEOUT_SET); }` 设置服务端超时秒数 write()方法 <table class="summaryTable"><tr><td colspan="3"><div class="signature2">protected void <b>write</b>(string $buf, string $len=0)</div></td></tr><tr><td class="paramNameCol">$buf</td> <td class="paramTypeCol">string</td> <td class="paramDescCol">要写入的字符串</td></tr><tr><td class="paramNameCol">$len</td> <td class="paramTypeCol">string</td> <td class="paramDescCol">要写入的长度, 默认为字符串长度</td></tr></table> **源码:**[sdk/php/lib/XSServer.class.php#L368](https://github.com/hightman/xunsearch/blob/master/sdk/php/lib/XSServer.class.php#L368) (**[显示](#)**) `protected function write($buf, $len = 0) { // quick return for empty buf $buf = strval($buf); if ($len == 0 && ($len = $size = strlen($buf)) == 0) { return true; } // loop to send data $this->check(); while (true) { $bytes = fwrite($this->_sock, $buf, $len); if ($bytes === false || $bytes === 0 || $bytes === $len) { break; } $len -= $bytes; $buf = substr($buf, $bytes); } // error occured if ($bytes === false || $bytes === 0) { $meta = stream_get_meta_data($this->_sock); $this->close(true); $reason = $meta['timed_out'] ? 'timeout' : ($meta['eof'] ? 'closed' : 'unknown'); $msg = 'Failed to send the data to server completely '; $msg .= '(SIZE:' . ($size - $len) . '/' . $size . ', REASON:' . $reason . ')'; throw new XSException($msg); } }` 写入数据 Copyright © 2008-2011 by [杭州云圣网络科技有限公司](http://www.xunsearch.com) All Rights Reserved.