Prev

ftss protocol

This document describes the ftss protocol implemented by ftss and libftss.

NOTE: All types are assumed to be in network byte order. uint32 refers to a 32 bit unsigned integer. uint16 refers to a 16 bit unsigned integer.

Requests

Communication between the server and clients is initiated by clients through requests. Each request begins with a uint16 opcode indicating the request type. Following that is a uint32 message length and then the opcode specific message. The message length is the length of the opcode specific data in bytes. 


|------------ 32 bits ------------|
 ---------------------------------
|     opcode     |   message...   |
 ---------------------------------
|...length(bytes)|   opcode ...   |
 ---------------------------------
|                                 |
|      ... specific message       |
|                                 |
|                                 |
 ---------------------------------
 fig. 1 - Request structure

Responses

Every request made by clients has a corresponding response. Each response begins with a uint16 indicating the opcode it is responding to. Then follows a uint32 result code. Following the result code is a uint32 message length and then the reponse specific message. The message length is the length of the response specific message. 

|------------ 32 bits ------------|
 ---------------------------------
|  opcode reply  |   result...    |
 ---------------------------------
|   ...code      |  message ...   |
 ---------------------------------
|...length(bytes)| response ...   |
 ---------------------------------
|                                 |
|    ...specific message          |
|                                 |
|                                 |
 ---------------------------------
 fig. 2 - Response structure

Requests and Responses

This section describes each request/response supported by the server. Unless otherwise noted, all versions in this document should be 1.

Get Server Info

Get the version of the protocol implemented by the server.

Request
Opcode: FTOP_SERVERINFO (1)
Message: None.

Response
Result Codes: FTRESULT_OK
Message: A uint16 version number of the protocol implemented by the server.

Search

Issue a search request.

Request
Opcode: FTOP_SEARCH (2)
Message: The query to execute. Click here to learn about query syntax.

Response
Result Codes: FTRESULT_OK, FTRESULT_SYNTAX_ERROR, FTRESULT_TOO_MANY_OPENED_SEARCHES
Message: A uint32 handle used to identify this search. 0 is an invalid handle.

Get Hits

Get the hits returned from a search.

Request
Opcode: FTOP_GETHITS (3)
Message: The handle from the search followed by the maximum number of hits to return, given as a uint32.

Response
Result Codes: FTRESULT_OK, FTRESULT_INVALID_HANDLE, FTRESULT_NOMORE
Message: A uint32 giving the number of hits returned followed by that many hits. Each hit is:

  1. a uint16 address length
  2. a variable length, null terminated address of that length.

Close Search

Close a search.

Request
Opcode: FTOP_CLOSESEARCH (4)
Message: The handle of the search you want to close.

Response
Result Codes: FTRESULT_OK, FTRESULT_INVALID_HANDLE
Message: None.

Add Document Begin

Request
Opcode: FTOP_ADDDOCUMENTBEGIN (5)
Message:

  1. A uint16 length of the address that follows
  2. An ASCII address

Response
Result Codes: FTRESULT_OK, FTRESULT_ADD_ERROR
Message: A uint32 handle to the document. Use this in the add document data and add document finished requests.

Add Document Data

Request
Opcode: FTOP_ADDDOCUMENTDATA (6)
Message:

  1. A uint32 handle returned from add document begin.
  2. A uint32 length of the data that follow
  3. ASCII data to index

Response
Result Codes: FTRESULT_OK, FTRESULT_ADD_ERROR, FTRESULT_INVALID_HANDLE
Message: None.

Add Document End

Request
Opcode: FTOP_ADDDOCUMENTEND (7)
Message: A uint32 document handle returned from add document begin. This handle becomes invalid after this request.

Response
Result Codes: FTRESULT_OK, FTRESULT_ADD_ERROR, FTRESULT_INVALID_HANDLE
Message: None.

Disconnect

Disconnect from the server.

Request
Opcode: FTOP_DISCONNECT (8)
Message: None

Response
Result Codes: FTRESULT_OK
Message: None