From 80fd4c332c06b788fc2672e78718ded83b6b57f5 Mon Sep 17 00:00:00 2001 From: Constantin Kaplinsky Date: Thu, 29 Mar 2007 11:31:21 +0000 Subject: [PATCH] Added incomplete documentation on RFB protocol extensions (version as of 2006/08/07). git-svn-id: svn://svn.code.sf.net/p/tigervnc/code/trunk@2247 3789f03b-4d11-0410-bbf8-ca57d06f2519 --- doc/rfbtight.tex | 972 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 972 insertions(+) create mode 100644 doc/rfbtight.tex diff --git a/doc/rfbtight.tex b/doc/rfbtight.tex new file mode 100644 index 00000000..e7ad3870 --- /dev/null +++ b/doc/rfbtight.tex @@ -0,0 +1,972 @@ +\documentclass[a4paper]{article} +\usepackage{geometry} +\geometry{verbose,a4paper,tmargin=20mm,bmargin=20mm,lmargin=30mm,rmargin=30mm} +\setlength{\parindent}{0pt} +\setlength{\parskip}{1ex plus 0.5ex minus 0.2ex} + +\newcommand{\typestr}[1]{\textit{#1}} +\newcommand{\literal}[1]{\textit{\textbf{#1}}} + +\begin{document} + +\title{TightVNC Extensions to the RFB~Protocol + \thanks{This document refers to RFB protocol versions 3.3, 3.7}} +\author{Constantin Kaplinsky\\ + TightVNC Group} +\date{Revision 1 --- July, 2006} +\maketitle + +\tableofcontents + +\newpage +\section{Overview} +This document describes various extensions to the RFB protocol used in +the TightVNC distribution and in other software compatible with +TightVNC. Only differences from the stardard RFB protocol are +discussed. The original RFB protocol specification (protocol versions +3.3, 3.7, 3.8) can be obtained here: +\begin{center} +\texttt{http://www.realvnc.com/docs/rfbproto.pdf} +\end{center} + +At the moment of writing this document, TightVNC supports RFB protocol +version 3.3 (all TightVNC versions) and 3.7 (TightVNC 1.3.x). It does +not use the version 3.8 of the protocol, and it's not safe to assume +that the TightVNC-specific changes to the protocol 3.7 initialization +procedure can be used with the protocol 3.8. However, all encodings, +pseudo-encodings and protocol messages described in this document can +be safely used with the protocol 3.8. +% (pseudo-)encodings: 3.3+, messages: 3.7+ with sec-type == Tight + +TightVNC introduces the following protocol changes: +\begin{itemize} +\item extended protocol initialization procedure, +\item new encodings, +\item new pseudo-encodings, +\item new protocol messages. +\end{itemize} + +\newpage +\section{Protocol initialization} + +\subsection{Protocol version 3.3} +\subsection{Protocol version 3.7} + +\newpage +\section{Encodings} +\subsection{Tight} +\begin{verbatim} +Encoding type: 7 +Name signature: "TIGHT___" +Vendor signature: "TGHT" +\end{verbatim} +Tight encoding provides efficient compression for pixel data. + +The first byte of each Tight-encoded rectangle is a +\typestr{compression-control} byte: + +\begin{tabular}{l|lc|l} \hline +No.\ of bytes & Type & [Value] & Description \\ \hline +1 & U8 & & \typestr{compression-control} \\ \hline +\end{tabular} + +\begin{quote} +The least significant four bits of \typestr{compression-control} byte +inform the client which zlib compression streams should be reset +before decoding the rectangle. Each bit is independent and corresponds +to a separate zlib stream that should be reset: + +\begin{tabular}{l|l} +\hline +Bit & Description \\ +\hline +0 & if 1: reset stream 0 \\ +1 & if 1: reset stream 1 \\ +2 & if 1: reset stream 2 \\ +3 & if 1: reset stream 4 \\ +\hline +\end{tabular} + +One of three possible compression methods are supported in Tight +encoding. These are \literal{BasicCompression}, +\literal{FillCompression} and \literal{JpegCompression}. If the bit 7 (the +most significant bit) of \typestr{compression-control} byte is 0, then +the compression type is \literal{BasicCompression}. In that case, bits +7-4 (the most significant four bits) of \typestr{compression-control} +should be interpreted as follows: + +\begin{tabular}{l|c|l} +\hline +Bits & Binary value & Description \\ +\hline +5-4 & 00 & \literal{UseStream0} \\ + & 01 & \literal{UseStream1} \\ + & 10 & \literal{UseStream2} \\ + & 11 & \literal{UseStream3} \\ +\hline +6 & 0 & --- \\ + & 1 & \literal{ReadFilterId} \\ +\hline +7 & 0 & \literal{BasicCompression} \\ +\hline +\end{tabular} + +Otherwise, if the bit 7 of \typestr{compression-control} is set to 1, +then the compression method is either \literal{FillCompression} or +\literal{JpegCompression}, depending on other bits of the same byte: + +\begin{tabular}{l|c|l} +\hline +Bits & Binary value & Description \\ +\hline +7-4 & 1000 & \literal{FillCompression} \\ + & 1001 & \literal{JpegCompression} \\ + & any other & invalid \\ +\hline +\end{tabular} + +Note: \literal{JpegCompression} may only be used when +\typestr{bits-per-pixel} is either 16 or 32. + +\end{quote} + +The data following the \typestr{compression-control} byte depends on +the compression method. + +\subsubsection*{\literal{FillCompression}} + +-- If the compression type is "fill", then the only pixel value follows, in + client pixel format (see NOTE 1). This value applies to all pixels of the + rectangle. + +\subsubsection*{\literal{JpegCompression}} + +-- If the compression type is "jpeg", the following data stream looks like + this: + + 1..3 bytes: data size (N) in compact representation; + N bytes: JPEG image. + + Data size is compactly represented in one, two or three bytes, according + to the following scheme: + + 0xxxxxxx (for values 0..127) + 1xxxxxxx 0yyyyyyy (for values 128..16383) + 1xxxxxxx 1yyyyyyy zzzzzzzz (for values 16384..4194303) + + Here each character denotes one bit, xxxxxxx are the least significant 7 + bits of the value (bits 0-6), yyyyyyy are bits 7-13, and zzzzzzzz are the + most significant 8 bits (bits 14-21). For example, decimal value 10000 + should be represented as two bytes: binary 10010000 01001110, or + hexadecimal 90 4E. + +\subsubsection*{\literal{BasicCompression}} + +-- If the compression type is "basic" and bit 6 of the compression control + byte was set to 1, then the next (second) byte specifies "filter id" which + tells the decoder what filter type was used by the encoder to pre-process + pixel data before the compression. The "filter id" byte can be one of the + following: + + 0: no filter ("copy" filter); + 1: "palette" filter; + 2: "gradient" filter. + +-- If bit 6 of the compression control byte is set to 0 (no "filter id" + byte), or if the filter id is 0, then raw pixel values in the client + format (see NOTE 1) will be compressed. See below details on the + compression. + +-- The "gradient" filter pre-processes pixel data with a simple algorithm + which converts each color component to a difference between a "predicted" + intensity and the actual intensity. Such a technique does not affect + uncompressed data size, but helps to compress photo-like images better. + Pseudo-code for converting intensities to differences is the following: + + P[i,j] := V[i-1,j] + V[i,j-1] - V[i-1,j-1]; + if (P[i,j] < 0) then P[i,j] := 0; + if (P[i,j] > MAX) then P[i,j] := MAX; + D[i,j] := V[i,j] - P[i,j]; + + Here V[i,j] is the intensity of a color component for a pixel at + coordinates (i,j). MAX is the maximum value of intensity for a color + component. + +-- The "palette" filter converts true-color pixel data to indexed colors + and a palette which can consist of 2..256 colors. If the number of colors + is 2, then each pixel is encoded in 1 bit, otherwise 8 bits is used to + encode one pixel. 1-bit encoding is performed such way that the most + significant bits correspond to the leftmost pixels, and each raw of pixels + is aligned to the byte boundary. When "palette" filter is used, the + palette is sent before the pixel data. The palette begins with an unsigned + byte which value is the number of colors in the palette minus 1 (i.e. 1 + means 2 colors, 255 means 256 colors in the palette). Then follows the + palette itself which consist of pixel values in client pixel format (see + NOTE 1). + +-- The pixel data is compressed using the zlib library. But if the data + size after applying the filter but before the compression is less then 12, + then the data is sent as is, uncompressed. Four separate zlib streams + (0..3) can be used and the decoder should read the actual stream id from + the compression control byte (see NOTE 2). + + If the compression is not used, then the pixel data is sent as is, + otherwise the data stream looks like this: + + 1..3 bytes: data size (N) in compact representation; + N bytes: zlib-compressed data. + + Data size is compactly represented in one, two or three bytes, just like + in the "jpeg" compression method (see above). + +-- NOTE 1. If the color depth is 24, and all three color components are + 8-bit wide, then one pixel in Tight encoding is always represented by + three bytes, where the first byte is red component, the second byte is + green component, and the third byte is blue component of the pixel color + value. This applies to colors in palettes as well. + +-- NOTE 2. The decoder must reset compression streams' states before + decoding the rectangle, if some of bits 0,1,2,3 in the compression control + byte are set to 1. Note that the decoder must reset zlib streams even if + the compression type is "fill" or "jpeg". + +-- NOTE 3. The "gradient" filter and "jpeg" compression may be used only + when bits-per-pixel value is either 16 or 32, not 8. + +-- NOTE 4. The width of any Tight-encoded rectangle cannot exceed 2048 + pixels. If a rectangle is wider, it must be split into several rectangles + and each one should be encoded separately. + +\newpage +\section{Pseudo-encodings} +\subsection{NewFBSize} +\begin{verbatim} +Encoding type: 0xFFFFFF21 +Name signature: "NEWFBSIZ" +Vendor signature: "TGHT" +\end{verbatim} + +The NewFBSize pseudo-encoding is used to transmit information about +framebuffer size changes from server to client. + +This pseudo-encoding was introduced in TightVNC, and was adopted for +use in RealVNC 4 (see the DesktopSize pseudo-encoding in the RFB 3.7+ +specification). However, there is known incompatibility between +TightVNC and RealVNC in the way the server sends information about new +framebuffer size. TightVNC implementation requires that a NewFBSize +``rectangle'' must be the last one in a framebuffer update, while +RealVNC does not make such a requirement. As a result, TightVNC +viewers may incorrectly interpret the data stream received from +RealVNC 4 servers. + +Hopefully, this incompatibility will be fixed in future versions of +TightVNC. Ideally, the server should send NewFBSize ``rectangles'' +according to the TightVNC rules (with valid rectangle counter in the +FramebufferUpdate header), while the client should interpet it in +accordance to the DesktopSize pseudo-encoding description from +RealVNC's official RFB specification. + +Below is the complete specification of the NewFBSize pseudo-encoding, +as it was introduced in TightVNC: + +\subsubsection*{ +\begin{center} + Handling framebuffer size changes in the RFB protocol v.3\\ + Technical Specification, revision 3 +\end{center} +} + +\begin{quote} +The following pseudo-encoding is used to transmit information about +framebuffer size changes from server to client: + +\begin{center} +\texttt{\#define rfbEncodingNewFBSize 0xFFFFFF21} +\end{center} + +A client supporting variable framebuffer size should send this +pseudo-encoding number in the encodings list within the SetEncodings +RFB message. + +After a client informed the server about this capability, the server +may send a special rectangle within the FramebufferUpdate RFB message, +where the header contains encoding-type field set to the +rfbEncodingNewFBSize value. Fields width and height in this rectangle +header should be interpreted as new framebuffer size, fields +x-position and y-position are currently not used and should be set to +zero values by the server. Unlike true rectangle in framebuffer +updates, this one should not include any pixel data. This rectangle +must always be the last one in a FramebufferUpdate message, and a +client should treat it similarly to the LastRect marker, that is, it +should not expect more rectangles in this update, even if the +number-of-rectangles field in the FramebufferUpdate message header +exceeds current number of rectangles. + +Immediately after receiving such a special rectangle, a client should +change its framebuffer size accordingly, and should interpret all +following framebuffer updates in context of the new framebuffer size. + +Changing framebuffer size invalidates framebuffer contents, so the +server should mark all the framebuffer contents as changed. + +FIXME: Allow zero-size framebuffer? +\end{quote} + +\subsection{RichCursor} +\subsection{XCursor} +\subsection{PointerPos} +\subsection{CompressLevel} +\subsection{QualityLevel} +\subsection{LastRect} + +% For each message, describe its place in the message sequence. + +\newpage +\section{Protocol messages (client to server)} + +\subsection{FileListRequest} +\begin{verbatim} +Message type: 130 +Name signature: "FTC_LSRQ" +Vendor signature: "TGHT" +\end{verbatim} + +The client sends \typestr{FileListRequest} message to obtain the list +of files in a particular directory. The server is expected to respond +with exactly one \typestr{FileListData} message. + +\begin{tabular}{l|lc|l} \hline +No.\ of bytes & Type & [Value] & Description \\ \hline +1 & U8 & 130 & \typestr{message-type} \\ +1 & U8 & & \typestr{flags} \\ +2 & U16 & & \typestr{dirname-length} \\ +\typestr{dirname-length} & U8 array & & \typestr{dirname-string} \\ +\hline\end{tabular} + +The \typestr{flags} byte has the following format: + +\begin{tabular}{l|l|l} +\hline +Bits & Binary value & Description \\ \hline +3-0 & 0000 & do not compress file list data \\ + & 0001..1001 & use compression level 1..9 \\ + & 1010 or greater & invalid \\ +\hline +4 & 0 & list of files and directories requested \\ + & 1 & list of directories only requested \\ +\hline +\end{tabular} + +The client can request compression only if enabled via the server's +\typestr{FileEnableCompression} message. Otherwise, bits 3-0 of +\typestr{flags} must be all zeroes (for no compression). See more +details in the specification for the \typestr{FileEnableCompression} +message. + +% Add a note that specifying compression levels is not fatal here. + +The \typestr{dirname-string} should be an absolute path represented in +Unix-style format: it should start with a forward slash +(``\verb|/|''), path components should be separated also with forward +slashes. There should be no trailing slash at the end of the path, +except for the root (highest level) directory which is denoted with a +single slash. Note that Windows-style path like +``\verb|c:\Program Files\TightVNC|'' should be sent as +``\verb|/c:/Program Files/TightVNC|''. + +\newpage +\subsection{FileDownloadRequest} +\begin{verbatim} +Message type: 131 +Name signature: "FTC_DNRQ" +Vendor signature: "TGHT" +\end{verbatim} + +The client sends \typestr{FileDownloadRequest} message to start +downloading (receiving) a particular file from the server. + +\begin{tabular}{l|lc|l} \hline +No.\ of bytes & Type & [Value] & Description \\ \hline +1 & U8 & 131 & \typestr{message-type} \\ +1 & U8 & & \typestr{flags} \\ +2 & U16 & & \typestr{filename-length} \\ +4 & U32 & & \typestr{initial-offset} \\ +\typestr{filename-length} & U8 array & & \typestr{filename-string} \\ +\hline\end{tabular} + +The \typestr{flags} byte has the following format: + +\begin{tabular}{l|l|l} +\hline +Bits & Binary value & Description \\ \hline +3-0 & 0000 & do not compress file data \\ + & 0001..1001 & use compression level 1..9 \\ + & 1010 or greater & invalid \\ +\hline +\end{tabular} + +% \typestr{initial-offset} +% do not use compression when not enabled by the server + +After the client sends \typestr{FileDownloadRequest}, the server is +expected to respond with one of the following: + +\begin{itemize} + +\item \typestr{FileLastRequestFailed} message, if there was an error +opening file on the server side. + +\item Arbitrary number (including zero) of \typestr{FileDownloadData} +messages with file data, and then one more \typestr{FileDownloadData} +message with \typestr{raw-length} and \typestr{compressed-length} +fields set to zero. This is the normal scenario when there was no +error and download was not interrupted. + +\item Arbitrary number (including zero) of \typestr{FileDownloadData} +messages with file data, and then one \typestr{FileDownloadFailed} +message. This happens when the server cannot complete file download +for some reason. + +\item \dots + +\end{itemize} + +% Can FileDownloadFailed go first? -- probably yes. +% How zero-size files are transmitted? +% How to detect the beginning of the next file, when previous +% download was cancelled with FileDownloadCancel? + +The \typestr{filename-string} should be a file name with complete +absolute path represented in Unix-style format: it should start with a +forward slash (``\verb|/|''), path components should be separated also +with forward slashes. For example, Windows-style file name +``\verb|c:\Temp\Report.doc|'' should be sent as +``\verb|/c:/Temp/Report.doc|''. + +\newpage +\subsection{FileUploadRequest} +\begin{verbatim} +Message type: 132 +Name signature: "FTC_UPRQ" +Vendor signature: "TGHT" +\end{verbatim} + +The client sends \typestr{FileUploadRequest} message to start +uploading (sending) a particular file to the server. + +\begin{tabular}{l|lc|l} \hline +No.\ of bytes & Type & [Value] & Description \\ \hline +1 & U8 & 132 & \typestr{message-type} \\ +1 & U8 & & \typestr{flags} \\ +2 & U16 & & \typestr{filename-length} \\ +4 & U32 & & \typestr{initial-offset} \\ +\typestr{filename-length} & U8 array & & \typestr{filename-string} \\ +\hline\end{tabular} + +The \typestr{flags} byte has the following format: + +\begin{tabular}{l|l|l} +\hline +Bits & Binary value & Description \\ \hline +3-0 & 0000 & file data is expected to be uncompressed \\ + & 0001..1001 & expected compression level (1..9) \\ + & 1010 or greater & invalid \\ +\hline +\end{tabular} + +% \typestr{initial-offset} +% do not use compression when not enabled by the server + +Normally, the server does not respond to this message, so the client +can start sending \typestr{FileUploadData} messages immediately. +However, the server may send \typestr{FileUploadCancel} to make the +client cancel current upload. The client can cancel current upload by +sending \typestr{FileUploadFailed} message. + +The \typestr{filename-string} should be a file name with complete +absolute path represented in Unix-style format: it should start with a +forward slash (``\verb|/|''), path components should be separated also +with forward slashes. For example, Windows-style file name +``\verb|c:\Temp\Report.doc|'' should be sent as +``\verb|/c:/Temp/Report.doc|''. + +\newpage +\subsection{FileUploadData} +\begin{verbatim} +Message type: 133 +Name signature: "FTC_UPDT" +Vendor signature: "TGHT" +\end{verbatim} + +The client uses \typestr{FileUploadData} message to send each +successive portion of file data, as a part of file upload procedure. + +\begin{tabular}{l|lc|l} \hline +No.\ of bytes & Type & [Value] & Description \\ \hline +1 & U8 & 133 & \typestr{message-type} \\ +1 & U8 & & \typestr{flags} \\ +2 & U16 & & \typestr{raw-length} \\ +2 & U16 & & \typestr{compressed-length} \\ +\typestr{compressed-length} & U8 array & & \typestr{file-data} \\ +\hline\end{tabular} + +The \typestr{flags} byte has the following format: + +\begin{tabular}{l|l|l} +\hline +Bits & Binary value & Description \\ \hline +3-0 & 0000 & file data is not compressed \\ + & 0001..1001 & compression level used (1..9) \\ + & 1010 or greater & invalid \\ +\hline +\end{tabular} + +Last message per file (both \typestr{raw-length} and +\typestr{compressed-length} are set to zeroes): + +\begin{tabular}{l|lc|l} \hline +No.\ of bytes & Type & [Value] & Description \\ \hline +1 & U8 & 133 & \typestr{message-type} \\ +1 & & & \typestr{padding} \\ +2 & U16 & 0 & \typestr{raw-length} \\ +2 & U16 & 0 & \typestr{compressed-length} \\ +4 & U32 & & \typestr{modification-time} \\ +\hline\end{tabular} + +% do not use compression when not enabled by the server +% data is compressed with zlib +% format of the modification-time + +\newpage +\subsection{FileDownloadCancel} +\begin{verbatim} +Message type: 134 +Name signature: "FTC_DNCN" +Vendor signature: "TGHT" +\end{verbatim} + +The client sends \typestr{FileDownloadCancel} message to make the +server break current download operation. + +\begin{tabular}{l|lc|l} \hline +No.\ of bytes & Type & [Value] & Description \\ \hline +1 & U8 & 134 & \typestr{message-type} \\ +1 & & & \typestr{padding} \\ +2 & U16 & & \typestr{reason-length} \\ +\typestr{reason-length} & U8 array & & \typestr{reason-string} \\ +\hline\end{tabular} + +% reason-string may be empty + +\newpage +\subsection{FileUploadFailed} +\begin{verbatim} +Message type: 135 +Name signature: "FTC_UPFL" +Vendor signature: "TGHT" +\end{verbatim} + +The client sends \typestr{FileUploadFailed} message to notify the +server that current upload operation will not be completed. + +\begin{tabular}{l|lc|l} \hline +No.\ of bytes & Type & [Value] & Description \\ \hline +1 & U8 & 135 & \typestr{message-type} \\ +1 & & & \typestr{padding} \\ +2 & U16 & & \typestr{reason-length} \\ +\typestr{reason-length} & U8 array & & \typestr{reason-string} \\ +\hline\end{tabular} + +% reason-string may be empty + +\newpage +\subsection{FileCreateDirRequest} +\begin{verbatim} +Message type: 136 +Name signature: "FTC_FCDR" +Vendor signature: "TGHT" +\end{verbatim} + +\typestr{FileCreateDirRequest} message requests the server to create a +new directory. + +\begin{tabular}{l|lc|l} \hline +No.\ of bytes & Type & [Value] & Description \\ \hline +1 & U8 & 136 & \typestr{message-type} \\ +1 & & & \typestr{padding} \\ +2 & U16 & & \typestr{dirname-length} \\ +\typestr{dirname-length} & U8 array & & \typestr{dirname-string} \\ +\hline\end{tabular} + +The \typestr{dirname-string} should be an absolute path represented in +Unix-style format: it should start with a forward slash +(``\verb|/|''), path components should be separated also with forward +slashes. There should be no trailing slash at the end of the path. +Note that Windows-style path like +``\verb|c:\Temp\MyNewDir|'' should be sent as +``\verb|/c:/Temp/MyNewDir|''. + +% All components of the path except the last one should exist in the +% server's file system? + +\newpage +\subsection{FileDirSizeRequest} +\begin{verbatim} +Message type: 137 +Name signature: "FTC_DSRQ" +Vendor signature: "TGHT" +\end{verbatim} + +The client can send \typestr{FileDirSizeRequest} message to inquire +about the total size of all files within a particular directory on the +server (including files in sub-directories). + +\begin{tabular}{l|lc|l} \hline +No.\ of bytes & Type & [Value] & Description \\ \hline +1 & U8 & 137 & \typestr{message-type} \\ +1 & & & \typestr{padding} \\ +2 & U16 & & \typestr{dirname-length} \\ +\typestr{dirname-length} & U8 array & & \typestr{dirname-string} \\ +\hline\end{tabular} + +The \typestr{dirname-string} should be an absolute path represented in +Unix-style format: it should start with a forward slash +(``\verb|/|''), path components should be separated also with forward +slashes. There should be no trailing slash at the end of the path, +except for the root (highest level) directory which is denoted with a +single slash. Note that Windows-style path like +``\verb|c:\Program Files\TightVNC|'' should be sent as +``\verb|/c:/Program Files/TightVNC|''. + +\newpage +\subsection{FileRenameRequest} +\begin{verbatim} +Message type: 138 +Name signature: "FTC_RNRQ" +Vendor signature: "TGHT" +\end{verbatim} + +\typestr{FileRenameRequest} message requests the server to rename the +specified file or directory. + +\begin{tabular}{l|lc|l} \hline +No.\ of bytes & Type & [Value] & Description \\ \hline +1 & U8 & 138 & \typestr{message-type} \\ +1 & & & \typestr{padding} \\ +2 & U16 & & \typestr{old-name-length} \\ +2 & U16 & & \typestr{new-name-length} \\ +\typestr{old-name-length} & U8 array & & \typestr{old-name-string} \\ +\typestr{new-name-length} & U8 array & & \typestr{new-name-string} \\ +\hline\end{tabular} + +Both \typestr{old-name-string} and \typestr{new-name-string} should be +file names with complete absolute paths and should be represented in +Unix-style format: the strings should start with forward slashes +(``\verb|/|''), path components should be separated also with forward +slashes. For example, Windows-style file name +``\verb|c:\Temp\Report.doc|'' should be sent as +``\verb|/c:/Temp/Report.doc|''. + +% All components of two paths except the last one should be the same? + +\newpage +\subsection{FileDeleteRequest} +\begin{verbatim} +Message type: 139 +Name signature: "FTC_RMRQ" +Vendor signature: "TGHT" +\end{verbatim} + +\typestr{FileDeleteRequest} message requests the server to delete the +specified file or directory. + +\begin{tabular}{l|lc|l} \hline +No.\ of bytes & Type & [Value] & Description \\ \hline +1 & U8 & 139 & \typestr{message-type} \\ +1 & & & \typestr{padding} \\ +2 & U16 & & \typestr{filename-length} \\ +\typestr{filename-length} & U8 array & & \typestr{filename-string} \\ +\hline\end{tabular} + +The \typestr{filename-string} should be a file name with complete +absolute path represented in Unix-style format: it should start with a +forward slash (``\verb|/|''), path components should be separated also +with forward slashes. For example, Windows-style file name +``\verb|c:\Temp\Report.doc|'' should be sent as +``\verb|/c:/Temp/Report.doc|''. + +\newpage +\section{Protocol messages (server to client)} + +\subsection{FileListData} +\begin{verbatim} +Message type: 130 +Name signature: "FTS_LSDT" +Vendor signature: "TGHT" +\end{verbatim} + +The server sends \typestr{FileListData} message in response to +\typestr{FileListRequest} client message. \typestr{FileListData} +message lists files and sub-directories in a particular directory, and +includes information about file sizes and last modification times. + +\begin{tabular}{l|lc|l} \hline +No.\ of bytes & Type & [Value] & Description \\ \hline +1 & U8 & 130 & \typestr{message-type} \\ +1 & U8 & & \typestr{flags} \\ +2 & U16 & & \typestr{number-of-files} \\ +2 & U16 & & \typestr{raw-length} \\ +2 & U16 & & \typestr{compressed-length} \\ +8 $\times$ \typestr{number-of-files} & U32 array & & \typestr{file-properties-data} \\ +\typestr{compressed-length} & U8 array & & \typestr{file-names-data} \\ +\hline\end{tabular} + +The \typestr{flags} byte has the following format: + +\begin{tabular}{l|l|l} +\hline +Bits & Binary value & Description \\ \hline +3-0 & 0000 & file list data is not compressed \\ + & 0001..1001 & compression level used (1..9) \\ + & 1010 or greater & invalid \\ +\hline +4 & 0 & list of files and directories requested \\ + & 1 & list of directories only requested \\ +\hline +5 & 0 & success \\ + & 1 & non-existent or inaccessible directory requested \\ +\hline +\end{tabular} + +In the \typestr{flags} byte: + +\begin{itemize} +\item bit 4 duplicates the same bit from the corresponding + \typestr{FileListRequest} message; +\item if bit 5 is set to 1, then \typestr{number-of-files}, + \typestr{raw-length} and \typestr{compressed-length} all should be + set to zero values. In that case, \typestr{file-properties-data} and + \typestr{file-names-data} should be empty; +\item compression bits (bits 3-0) should be set only if compression + was requested by the client in the corresponding + \typestr{FileListRequest} message. +\end{itemize} + +\typestr{File-properties-data} array is sent as +\typestr{number-of-files} repetitions of the following structure: + +\begin{tabular}{l|lc|l} \hline +No.\ of bytes & Type & [Value] & Description \\ \hline +4 & U32 & & \typestr{file-size} \\ +4 & U32 & & \typestr{modification-time} \\ +\hline\end{tabular} + +In that structure, \typestr{file-size} is specified in bytes, +\typestr{modification-time} is an offset is seconds since the Epoch +(00:00:00 UTC, January 1, 1970). + +\typestr{File-names-data} is a sequence of file and directory names +found in the requested directory. Names do not include paths. +Each individual record is terminated with a zero byte. The +\typestr{file-names-data} list should include +\typestr{number-of-files} individual records. If compression is +enabled (bits 3-0 of \typestr{flags} designate a valid compression +level), then \typestr{file-names-data} is compressed using zlib +library. + +% the number-of-files may be 0; in that case ... +% how directories should be ditinguished +% what about symbolic links etc. +% describe raw-length and compressed-length + +\newpage +\subsection{FileDownloadData} +\begin{verbatim} +Message type: 131 +Name signature: "FTS_DNDT" +Vendor signature: "TGHT" +\end{verbatim} + +The server uses \typestr{FileDownloadData} message to send each +successive portion of file data, as a part of file download procedure. + +\begin{tabular}{l|lc|l} \hline +No.\ of bytes & Type & [Value] & Description \\ \hline +1 & U8 & 131 & \typestr{message-type} \\ +1 & U8 & & \typestr{flags} \\ +2 & U16 & & \typestr{raw-length} \\ +2 & U16 & & \typestr{compressed-length} \\ +\typestr{compressed-length} & U8 array & & \typestr{file-data} \\ +\hline\end{tabular} + +Last message per file (both \typestr{raw-length} and +\typestr{compressed-length} are set to zeroes): + +\begin{tabular}{l|lc|l} \hline +No.\ of bytes & Type & [Value] & Description \\ \hline +1 & U8 & 131 & \typestr{message-type} \\ +1 & & & \typestr{padding} \\ +2 & U16 & 0 & \typestr{raw-length} \\ +2 & U16 & 0 & \typestr{compressed-length} \\ +4 & U32 & & \typestr{modification-time} \\ +\hline\end{tabular} + +The \typestr{flags} byte has the following format: + +\begin{tabular}{l|l|l} +\hline +Bits & Binary value & Description \\ \hline +3-0 & 0000 & file data is not compressed \\ + & 0001..1001 & compression level used (1..9) \\ + & 1010 or greater & invalid \\ +\hline +\end{tabular} + +Compression should be used only if it was requested by the client in +corresponding \typestr{FileListRequest} message. + +% data is compressed with zlib +% format of the modification-time + +\newpage +\subsection{FileUploadCancel} +\begin{verbatim} +Message type: 132 +Name signature: "FTS_UPCN" +Vendor signature: "TGHT" +\end{verbatim} + +The server sends \typestr{FileUploadCancel} message to make the client +break current upload operation. + +\begin{tabular}{l|lc|l} \hline +No.\ of bytes & Type & [Value] & Description \\ \hline +1 & U8 & 132 & \typestr{message-type} \\ +1 & & & \typestr{padding} \\ +2 & U16 & & \typestr{reason-length} \\ +\typestr{reason-length} & U8 array & & \typestr{reason-string} \\ +\hline\end{tabular} + +% reason-string may be empty + +\newpage +\subsection{FileDownloadFailed} +\begin{verbatim} +Message type: 133 +Name signature: "FTS_DNFL" +Vendor signature: "TGHT" +\end{verbatim} + +The server sends \typestr{FileDownloadFailed} message to notify the +client that current download operation will not be completed. + +\begin{tabular}{l|lc|l} \hline +No.\ of bytes & Type & [Value] & Description \\ \hline +1 & U8 & 133 & \typestr{message-type} \\ +1 & & & \typestr{padding} \\ +2 & U16 & & \typestr{reason-length} \\ +\typestr{reason-length} & U8 array & & \typestr{reason-string} \\ +\hline\end{tabular} + +% reason-string may be empty + +\newpage +\subsection{FileDirSizeData} +\begin{verbatim} +Message type: 134 +Name signature: "FTS_DSDT" +Vendor signature: "TGHT" +\end{verbatim} + +The server sends \typestr{FileDirSizeData} message in response to +\typestr{FileDirSizeRequest} client message. \typestr{FileDirSizeData} +message returns total size of all files within the requested directory +on the server (including files in sub-directories). The size in bytes +is returned as an unsigned 48-bit value. + +\begin{tabular}{l|lc|l} \hline +No.\ of bytes & Type & [Value] & Description \\ \hline +1 & U8 & 134 & \typestr{message-type} \\ +1 & & & \typestr{padding} \\ +2 & U16 & & \typestr{dir-size-high-bits} \\ +4 & U32 & & \typestr{dir-size-low-bits} \\ +\hline\end{tabular} + +\newpage +\subsection{FileLastRequestFailed} +\begin{verbatim} +Message type: 135 +Name signature: "FTS_RQFL" +Vendor signature: "TGHT" +\end{verbatim} + +The server sends \typestr{FileLastRequestFailed} message if it cannot +execute an operation requested by the client. It can be sent in +response to the following client messages: +\typestr{FileDownloadRequest}, \typestr{FileCreateDirRequest}, +\typestr{FileRenameRequest}, \typestr{FileDeleteRequest}. + +\begin{tabular}{l|lc|l} \hline +No.\ of bytes & Type & [Value] & Description \\ \hline +1 & U8 & 135 & \typestr{message-type} \\ +1 & U8 & & \typestr{message-type-of-request} \\ +2 & U16 & & \typestr{reason-length} \\ +\typestr{reason-length} & U8 array & & \typestr{reason-string} \\ +\hline\end{tabular} + +% reason-string may be empty + +\newpage +\subsection{FileEnableCompression} +\begin{verbatim} +Message type: 137 +Name signature: "FTS_CMPR" +Vendor signature: "TGHT" +\end{verbatim} + +This message controls compression in file transfer operations. +\typestr{Enable-flag} is non-zero (true) if the client should be +allowed to request and use compression for file transfers, or zero +(false) otherwise. + +\begin{tabular}{l|lc|l} \hline +No.\ of bytes & Type & [Value] & Description \\ \hline +1 & U8 & 137 & \typestr{message-type} \\ +1 & U8 & & \typestr{enable-flag} \\ +\hline\end{tabular} + +\typestr{FileEnableCompression} message controls how clients send the +following messages: + +\begin{itemize} +\item \typestr{FileListRequest} +\item \typestr{FileDownloadRequest} +\item \typestr{FileUploadRequest} +\item \typestr{FileUploadData} +\end{itemize} + +If the client did not receive a \typestr{FileEnableCompression} +message from the server, or the most recent +\typestr{FileEnableCompression} message included \typestr{enable-flag} +set to false, then it must specify zero as compression level in the +messages listed above and, most importantly, may not compress file +data on uploading files. + +Otherwise, if the most recent \typestr{FileEnableCompression} message +included non-zero \typestr{enable-flag}, then the client is allowed to +request non-zero compression level and may send compressed data in +\typestr{FileUploadData} messages. + +This message should not have effect on file transfers that are already +in progress. + +\begin{quote} +Note: this message was introduced to preserve compatibility with +servers that do not support compression in file transfers. Old servers +expect uncompressed data in \typestr{FileUploadData} messages but new +clients might send it compressed. Using +\typestr{FileEnableCompression} message makes sure the client will +never compress upload data unless enabled explicitly by the server. +\end{quote} + +\end{document} -- 2.39.5