The XRootD Protocol

Version 4.0.0

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Andrew Hanushevsky

22-July-2018

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

©2004-2018 by the Board of Trustees of the Leland Stanford, Jr., University

All Rights Reserved

Produced under contract DE-AC02-76-SFO0515 with the Department of Energy

The protocol specification described in this document falls under BSD license terms.

The specification may be used for any purpose whatsoever.

Use of this specification must cite the original source -- xrootd.org.

Binary definition in header file XProtocol.hh superceed any such definitions in this document.

 

 


1         Contents

1       Contents. 3

2       Request/Response Protocol 5

2.1        Format of Client-Server Initial Handshake. 5

2.2        Data Serialization.. 7

2.3        Client Request Format 9

2.3.1         Valid Client Requests. 11

2.3.2         Valid Client Paths. 12

2.3.3         Client Recovery from Server Failures. 12

2.4        Server Response Format 13

2.4.1         Valid Server Response Status Codes. 14

2.4.2         Server kXR_attn Response Format 15

2.4.2.1      Server kXR_attn Response for kXR_asyncab Client Action.. 17

2.4.2.2      Server kXR_attn Response for kXR_asyncdi Client Action.. 18

2.4.2.3      Server kXR_attn Response for kXR_asyncgo Client Action.. 19

2.4.2.4      Server kXR_attn Response for kXR_asyncms Client Action.. 20

2.4.2.5      Server kXR_attn Response for kXR_asyncrd Client Action.. 21

2.4.2.6      Server kXR_attn Response for kXR_asynresp Client Action.. 23

2.4.2.7      Server kXR_attn Response for kXR_asyncwt Client Action.. 25

2.4.3         Server kXR_authmore Response Format 26

2.4.4         Server kXR_error Response Format 27

2.4.4.1      Server kXR_error Sub-Codes & Recovery Actions. 29

2.4.5         Server kXR_ok Response Format 31

2.4.6         Server kXR_oksofar Response Format 32

2.4.7         Server kXR_redirect Response Format 33

2.4.8         Server kXR_wait Response Format 36

2.4.9         Server kXR_waitresp Response Format 37

2.5        Binary Definitions of Status and Error codes. 39

2.5.1         Status Codes. 39

2.5.2         kXR_attn Status Subcodes. 39

2.5.3         Error Codes. 40

3       Detailed Protocol Specifications. 41

3.1        kXR_admin Request 41

3.2        kXR_auth Request 43

3.3        kXR_bind Request 45

3.4        kXR_chmod Request 47

3.5        kXR_close Request 49

3.6        kXR_decrypt Request 51

3.7        kXR_dirlist Request 52

3.8        kXR_endsess Request 55

3.9        kXR_fattr Request 57

3.9.1         Layout of namevec. 59

3.9.2         Layout of valuvec. 60

3.9.3         kXR_fattr Request – Delete Subcode. 61

3.9.4         kXR_fattr Request – Get Subcode. 63

3.9.5         kXR_fattr Request – List Subcode. 65

3.9.6         kXR_fattr Request – Set Subcode. 67

3.10     kXR_getfile Request 69

3.11     kXR_locate Request 71

3.12     kXR_login Request 75

3.12.1      Additional Login CGI Tokens. 78

3.13     kXR_mkdir Request 79

3.14     kXR_mv Request 81

3.15     kXR_open Request 83

3.15.1      Passing Opaque Information.. 87

3.16     kXR_ping Request 89

3.17     kXR_prepare Request 90

3.18     kXR_protocol Request 93

3.18.1      Protocol Security Requirements vs Response Implications. 98

3.19     kXR_putfile Request 101

3.20     kXR_query Request 103

3.20.1      KXR_query Checksum Cancellation Request 107

3.20.2      KXR_query Checksum Request 109

3.20.3      KXR_query Configuration Request 111

3.20.3.1    Format for Query Config cms. 113

3.20.3.2    Format for Query Config role. 114

3.20.3.3    Format for Query Config xattrs. 114

3.20.4      KXR_query Opaque Request 115

3.20.5      KXR_query Space Request 117

3.20.6      KXR_query Statistics Request 118

3.20.7      KXR_query Visa Request 121

3.20.8      KXR_query Xattr Request 123

3.21     kXR_read Request 125

3.22     kXR_readv Request 129

3.23     kXR_rm Request 133

3.24     kXR_rmdir Request 134

3.25     kXR_set Request 135

3.25.1      Valid kXR_Set Values. 137

3.26     kXR_sigver Request 139

3.26.1      Signing a request 141

3.26.2      Verifying a signed request 142

3.27     kXR_stat Request 143

3.28     kXR_statx Request 147

3.29     kXR_sync Request 149

3.30     kXR_truncate Request 150

3.31     kXR_verifyw Request 153

3.32     kXR_write Request 155

3.33     kXR_writev Request 157

4       The Security Framework. 159

4.1        Framework for Transport Layer Protocols. 163

4.2        Request Verification.. 164

5       Document Change History. 165

 


2         Request/Response Protocol

2.1       Format of Client-Server Initial Handshake

When a client first connects to the XRootD server, it must perform a special handshake. This handshake should determine whether the client is communicating using XRootD protocol or another protocol hosted by the server.

 

The handshake consists of the client sending 20 bytes, as follows:

 

kXR_int32

              0

 

kXR_int32

              0

 

kXR_int32

              0

 

kXR_int32

              4

(network byte order)

kXR_int32

        2012

(network byte order)

 

XRootD protocol, servers should respond, as follows:

 

streamid:

kXR_char

smid[2]

status:

kXR_unt16

0

msglen:

kXR_int32

rlen

msgval1:

kXR_int32

pval

msgval2:

kXR_int32

flag

 

Where:

 

smid     is the initial streamid. The smid for the initial response is always two null characters (i.e., ‘\0’);

 

rlen      is the binary response length (e.g., 8 for the indicated response).

 

pval     is the binary protocol version number.

 

flag      is additional bit-encoded information about the server; as follows:

            kXR_DataServer - 0x00 00 00 01 This is a data server.

            KXR_LBalServer - 0x00 00 00 00 This is a load-balancing server.

 


Notes

1)      All binary fields are transmitted in network byte order using an explicit length. The kXR_char and kXR_unt16 data types are treated as unsigned values. All reserved fields must be initialized to binary zero.

2)      The particular response format was developed for protocol version 2.0 and does not convey all of the information to capture features provided by subsequent protocol versions. In order to provide backward compatibility, this response format has been kept. The recommended mechanism to obtain all of the information that may be needed is to “piggy-back” a kXR_protocol Request with the handshake (i.e. send the handshake and the request with a single write).

3)      All twenty bytes must be received by the server at one time. All known TCP implementations should guarantee that the first message is sent intact if all twenty bytes are sent in a single system call. Using multiple system calls for the first message may cause unpredictable results.


 

2.2       Data Serialization

All data sent and received is serialized (i.e., marshaled) in three ways:

1.      Bytes are sent unaligned without any padding,

2.      Data type characteristics are predefined (see table below), and

3.      All integer quantities are sent in network byte order (i.e, big endian).

 

XRootD Type

Sign

Bit Length

Bit Alignment

Typical Host Type

kXR_char8

unsigned

 8

 8

unsigned char

kXR_unt16

unsigned

16

16

unsigned short

kXR_int32

  signed

32

32

long[1]

kXR_int64

  signed

64

64

long long

Table 1: XRootD Protocol Data Types

Network byte order is defined by the Unix htons() and htonl() macros for host to network short and host to network long, respectively. The reverse is defined by the ntohs() and ntohl() macros. Many systems do not define the long long versions of these macros. XRootD protocol requires that the POSIX version of long long serialization be used, as defined in the following figures. The OS-dependent isLittleEndian() function returns true if the underlying hardware using little endian integer representation.

 

 

unsigned long long htonll(unsigned long long x)

       {unsigned long long ret_val;

        if (isLittleEndian())

          {*( (unsigned long *)(&ret_val) + 1) =

                     htonl(*(  (unsigned long *)(&x)));

           *(((unsigned long *)(&ret_val))) =

                     htonl(*( ((unsigned long *)(&x))+1) );

           } else {

           *( (unsigned long *)(&ret_val)) =

                     htonl(*(  (unsigned long *)(&x)));

           *(((unsigned long *)(&ret_val)) + 1) =

                     htonl(*( ((unsigned long *)(&x))+1) );

           }

       return ret_val;

      };

 

Figure 1: POSIX Host to Network Byte Order Serialization


 

 

unsigned long long ntohll(unsigned long long x)

       {unsigned long long ret_val;

        if (isLittleEndian())

           {*( (unsigned long *)(&ret_val) + 1) =

                            ntohl(*( (unsigned long *)(&x)));

            *(((unsigned long *)(&ret_val))) =

                            ntohl(*(((unsigned long *)(&x))+1));

           } else {

            *( (unsigned long *)(&ret_val)) =

                            ntohl(*( (unsigned long*)(&x)));

            *(((unsigned long*)(&ret_val)) + 1) =

                            ntohl(*(((unsigned long*)(&x))+1));

           }

        return ret_val;

       };

 

Figure 2: Network and Host Byte Order Seialization

 

More compact and efficient, though OS restricted (i.e., Solaris and Linux), versions of 64-bit network byte ordering routines are given in the following figure.

 

 
#if defined(__sparc) || __BYTE_ORDER==__BIG_ENDIAN
#ifndef htonll
#define htonll(x) x
#endif
#ifndef ntohll
#define ntohll(x) x
#endif
#else
#ifndef htonll
#define htonll(x) __bswap_64(x)
#endif
#ifndef ntohll
#define ntohll(x) __bswap_64(x)
#endif
 

Figure 3: Network and Host Byte Ordering Macros


2.3       Client Request Format

Requests sent to the server are a mixture of ASCII and binary. All requests, other than the initial handshake request, have the same format, as follows:

 

kXR_char

streamid[2]

kXR_unt16

requestid

kXR_char

parms[16]

kXR_int32

dlen

kXR_char

data[dlen]

 

Where:

 

streamid

            is the binary identifier that is associated with this request stream. This identifier should be echoed along with any response to the request.

 

requestid

            is the binary identifier of the operation to be performed by the server.

 

parms  are parameters specific to the requestid.

 

dlen     is the binary length of the data portion of the message. If no data is present, then the value is zero.

 

data     are data specific to the requestid. Not all requests have associated data. If the request does have data, the length of this field is recorded in the dlen field.

 

Notes

1)      All binary fields are transmitted in network byte order using an explicit length. The kXR_char and kXR_unt16 data types are treated as unsigned values. All reserved fields must be initialized to binary zero.

2)      All XRootD client requests consist of a standard 24-byte fixed length message. The 24-byte header may then be optionally followed by request specific data.

3)      Stream id’s are arbitrary and are assigned by the client. Typically these id’s correspond to logical connections multiplexed over a physical connection established to a particular server.

4)      The client may send any number of requests to the same server. The order in which requests are performed is undefined. Therefore, each request should have a different streamid so that returned results may be paired up with associated requests.

5)      Requests sent by a client over a single physical connection may be processed in an arbitrary order. Therefore the client is responsible for serializing requests, as needed.


 

2.3.1        Valid Client Requests

 

Requestid

Value

Login?

Auth?

Redirect?

Arguments

kXR_admin*

3020

yes

yes

no

args

kXR_auth

3000

y

n

n

authtype, authinfo

KXR_bind

3024

n

n

n

sessid

kXR_chmod

3002

y

y

yes

mode, path

kXR_close

3003

y

-

n

fhandle

kXR_decrypt*

3030

y

y

n

 

KXR_dirlist

3004

y

y

y

path

KXR_endsess

3023

y

-

n

sessid

kXR_fattr

3032

y

y

y

Arguments vary by subcode

kXR_getfile*

3005

y

y

y

path

kXR_locate

3027

y

y

y

path

kXR_login

3007

n

n

n

userid, token

kXR_mkdir

3008

y

y

y

mode, path

kXR_mv

3009

y

y

y

old_name, new_name

kXR_open

3010

y

y

y

mode, flags, path

kXR_ping

3011

y

n

n

 

kXR_prepare

3021

y

y

n

paths

kXR_protocol

3006

n

n

n

 

kXR_putfile*

3012

y

y

y

mode, flags, path

kXR_query

3001

y

y

y

args

kXR_read

3013

y

-

y

fhandle, pathid, length, offset

kXR_readv

3025

y

-

y

fhandle, pathid, length, offset

kXR_rm

3014

y

y

y

path

kXR_rmdir

3014

y

y

y

path

kXR_set

3018

y

y

y

info

kXR_sigver

3029

y

y

n

signature

kXR_stat

3017

y

-

n

fhandle

kXR_stat

3017

y

y

y

path

kXR_statx

3022

y

y

n

pathlist

kXR_sync

3016

y

-

n

fhandle

kXR_truncate

3028

y

-

n

fhandle, length

kXR_truncate

3028

y

-

y

path, length

kXR_verifyw*

 

y

-

y

fhandle, length, offset, data

kXR_write

3019

y

-

y

fhandle, pathid, length, offset, data

kXR_writev

3031

y

y

n

fhandle, length, offset

 

Table 2: Valid Client Requests

*


2.3.2        Valid Client Paths

The XRootD server accepts only absolute paths where a path may be specified. Relative paths must be resolved by the client interface prior to sending them to XRootD. This means that the interface must handle a virtual “current working directory” to resolve relative paths should they arise.

 

Path names are restricted to the following set of characters:

 

In general, paths may not contain shell meta-characters.

 

2.3.3        Client Recovery from Server Failures

A server failure should be recognized when the server unexpectedly closes its TCP/IP connection or does not respond for an extended period of time. Should this happen, the client may recover all operations by treating the termination of the connection or unresponsiveness as a redirection request (see page 33) to the initial XRootD server for all streams associated with the closed TCP/IP connections.

 

The initial XRootD server is defined as the first manager or the last meta-manager encountered. In the absence of any manager, the first data server encountered. See the kXR_protocol request on how to determine a node’s type.

 

Because many clients are likely to be affected by a server failure, it is important that clients pace their reconnection to the initial XRootD server. One effective way to do this is to use the last three bits of the client’s IP address as the number of seconds to wait before attempting a reconnection. It is up to the client to determine either the number of times or the time window in which reconnections should be attempted before failure is declared. Typical values are 16 attempts or 3 minutes, whichever is longer.

 

Note that it may not be possible to recover in this way for files that were opened in update mode. Clients who do not provide proper transactional support generally cannot recover via redirection for any read/write resources.


2.4       Server Response Format

All responses, including the initial handshake response, have the same format, as follows:

 

kXR_char

streamid[2]

kXR_unt16

status

kXR_int32

dlen

kXR_char

data[dlen]

 

Where:

 

streamid

            is the binary identifier that is associated with this request stream corresponding to a previous request.

 

status   is the binary status code indicating how the request completed. The next section describes possible status codes.

 

dlen     is the binary length of the data portion of the message. If no data is present, then the value is zero.

 

data     are data specific to the requestid. Not all responses have associated data. If the response does have data, the length of this field is recorded in the dlen field.

 

Notes

1)      All binary fields are transmitted in network byte order using an explicit length. The kXR_char and kXR_unt16 data types are treated as unsigned values. All reserved fields must be initialized to binary zero.

2)      Since requests may be completed in any order, the ordering of responses is undefined. The client must appropriately pair responses with requests using the streamid value.

3)      Unsolicited responses are server requests for client configuration changes to make better use of the overall system. Since these responses do not correspond to any request, the streamid value has no meaning.

4)      Unsolicited responses must be immediately acted upon. They should not be paired with any previous request.

 


2.4.1        Valid Server Response Status Codes

The following table lists all possible responses and their arguments.

 

Status

Response Data

kXR_attn

Parameters to direct immediate client action

kXR_authmore

Authentication specific data

kXR_error

Error number and corresponding ASCII message text

kXR_ok

Depends on request (this is predefined to be the value 0)

KXR_oksofar

Depends on request

kXR_redirect

Target port number and ASCII host name

kXR_wait

Binary number of seconds and optional ASCII message

kXR_waitresp

Binary number of seconds

 

Notes

1)      Any request may receive any of the previous status codes.

2)      The following sections detail the response format used for each status code.


2.4.2        Server kXR_attn Response Format

 

kXR_char

pad[2]

kXR_unt16

kXR_attn

kXR_int32

plen

kXR_int32

actnum

kXR_char

parms[plen-4]

 

Where:

 

plen     is two bytes of padding required by the standard response format. These two bytes can be ignored for this particular response code.

 

plen     is the binary length of the parms portion of the message (i.e., the subsequent bytes).

 

actnum

            is the binary action code describing the action that the client is to take. These are:

            kXR_asyncav      -  The file or file(s) the client previously requested to be

                                             prepared are now available.

            kXR_asyncab     -  The client should immediately disconnect (i.e., close

                                             the socket connection) from the server and abort further

                                             execution.

            kXR_asyncdi      -  The client should immediately disconnect (i.e., close

                                             the socket connection) from the server. Parameters

                                             indicate when a reconnect may be attempted.

            kXR_asyncgo     -  The client may start sending requests. This code is sent

                                             to cancel the effects of a previous kXR_asyncwt code.

            kXR_asyncms     -  The client should send the indicated message to the

                                             console. The parameters contain the message text.

            kXR_asyncrd      -  The client should immediately disconnect (i.e., close the

                                             socket connection) and reconnect to the indicated

                                             server.

         kXR_asynresp    -  The client should use the response data in the message to complete the request associated with the indicated streamid.

            kXR_asynunav  -  The file or file(s) the client previously requested to be

                                             prepared cannot be made available.

 

            kXR_asyncwt     -  The client should hold off sending any new requests

                                             until the indicated amount of time has passed or until

                                             receiving a kXR_asyncgo action code.

 

parms          is the parameter data, if any, that is to steer client action.

 

Notes

1)      All binary fields are transmitted in network byte order using an explicit length. The kXR_char and kXR_unt16 data types are treated as unsigned values. All reserved fields must be initialized to binary zero.

2)      Servers use the kXR_attn response code to optimize overall system performance and to notify clients of any impending events. All responses except for kXR_asynresp, do not correspond to any client request and should not be paired up with any request.

3)      When kXR_attn is received, the client must perform the requested action and indicated by the actnum value.


2.4.2.1       Server kXR_attn Response for kXR_asyncab Client Action

 

kXR_char

pad[2]

kXR_unt16

kXR_attn

kXR_int32

mlen

kXR_int32

kXR_asyncab

kXR_char

msg[mlen-4]

 

Where:

 

mlen    is the binary length of the following action code and message.

 

msg      is the message to be sent to the terminal. The mlen value, less four, indicates the length of the message. The ending null byte (‘\0’) is transmitted and included in the message length.

 

Notes

1)      All binary fields are transmitted in network byte order using an explicit length. The kXR_char and kXR_unt16 data types are treated as unsigned values. All reserved fields must be initialized to binary zero.

2)      Servers use the kXR_attn response code to optimize overall system performance and to notify clients of any impending events. This response does not correspond to any client request and should not be paired up with any request.

3)      When kXR_attn is received with the kXR_asyncab action code, the client should close all physical connections, write the message (msg), if any, to standard error, and terminate execution.


2.4.2.2       Server kXR_attn Response for kXR_asyncdi Client Action

 

kXR_char

pad[2]

kXR_unt16

kXR_attn

kXR_int32

12

kXR_int32

kXR_asyncdi

kXR_int32

wsec

kXR_int32

msec

 

Where:

 

wsec    is the number of seconds the client should wait before attempting to reconnect to the server.

 

msec    is the maximum number of seconds the client should wait before declaring reconnect failure.

 

Notes

1)      All binary fields are transmitted in network byte order using an explicit length. The kXR_char and kXR_unt16 data types are treated as unsigned values. All reserved fields must be initialized to binary zero.

2)      Servers use the kXR_attn response code to optimize overall system performance and to notify clients of any impending events. This response does not correspond to any client request and should not be paired up with any request.

3)      When kXR_attn is received with the kXR_asyncdi action code, the client should close the physical connection, wait wsec seconds, and attempt to reconnect to the server.

4)      If a server reconnect fails, the client should wait either an additional wsec seconds or some other predetermined time and try again. If msec seconds have gone since the initial wait and the client has not reconnected to the server, a reconnect failure should be declared.

5)      When a reconnect failure is declared, the client may either terminate the program or perform an internal redirection to a load-balancing server.

6)      A reconnect is essentially a delayed redirect to the same server. The actions that must be carried out when reconnecting are identical to those that must be performed when reconnecting to a different server. Refer to the description of the kXR_asyncrd action for the set steps that the client must take to successfully reconnect.


2.4.2.3       Server kXR_attn Response for kXR_asyncgo Client Action

 

kXR_char

pad[2]

kXR_unt16

kXR_attn

kXR_int32

4

kXR_int32

kXR_asyncgo

 

Notes

1)      All binary fields are transmitted in network byte order using an explicit length. The kXR_char and kXR_unt16 data types are treated as unsigned values. All reserved fields must be initialized to binary zero.

2)      Servers use the kXR_attn response code to optimize overall system performance and to notify clients of any impending events. This response does not correspond to any client request and should not be paired up with any request.

3)      When kXR_attn is received with the kXR_asyncgo action code, the client may resume sending requests to the server.

4)      The kXR_asyncgo code is sent to cancel the effects of a previously sent kXR_asyncwt code. Therefore, if the client is still waiting for the kXR_asyncwt interval to expire, the interval should be cancelled.


2.4.2.4       Server kXR_attn Response for kXR_asyncms Client Action

 

kXR_char

pad[2]

kXR_unt16

kXR_attn

kXR_int32

mlen

kXR_int32

kXR_asyncms

kXR_char

msg[mlen-4]

 

Where:

 

mlen    is the binary length of the following action code and message.

 

msg      is the message to be sent to the terminal. The mlen value, less four, indicates the length of the message. The ending null byte (‘\0’) is transmitted and included in the message length.

 

Notes

1)      All binary fields are transmitted in network byte order using an explicit length. The kXR_char and kXR_unt16 data types are treated as unsigned values. All reserved fields must be initialized to binary zero.

2)      Servers use the kXR_attn response code to optimize overall system performance and to notify clients of any impending events. This response does not correspond to any client request and should not be paired up with any request.

3)      When kXR_attn is received with the kXR_asyncms action code, the client should simply write the indicated message to the terminal.


2.4.2.5       Server kXR_attn Response for kXR_asyncrd Client Action

 

kXR_char

pad[2]

kXR_unt16

kXR_attn

kXR_int32

plen

kXR_int32

kXR_asyncrd

kXR_int32

port

kXR_char

host[?token][plen-8]

 

Where:

 

plen     is the binary length of the parameter portion of the message (i.e., the subsequent bytes).

 

port      is the binary port number to which the client must connect. If the value is zero, the default XRootD port number must be used. If the value is negative, then the text after port contains a standard URL that must be used to effect a new connection. This should only occur if the client has indicated that URL redirection responses are acceptable during the most recent kXR_login request to the redirecting server.

 

host      is the ASCII name of the to which the client must connect. The host does not end with a null (\0) byte. The host should be interpreted as a standard URL if port is negative (see above).

 

token    is an optional ASCII token that, when present, must be delivered to the new host during the login phase, if one is needed. The token, if present, is separated from the host by a single question mark. The token does not end with a null (\0) byte.

 

Notes

1)      All binary fields are transmitted in network byte order using an explicit length. The kXR_char and kXR_unt16 data types are treated as unsigned values. All reserved fields must be initialized to binary zero.

2)      Servers use the kXR_attn response code to optimize overall system performance and to notify clients of any impending events. This response does not correspond to any client request and should not be paired up with any request.


 

3)      When kXR_attn is received with the kXR_asyncrd action code, the client should perform the following steps:

a.   Decompose the response to extract the port number, host name, and possible token value.

b.   Physically close the connection to the current host, regardless of type.

c.    Establish a new physical connection with the indicated host at the specified or default port number.

d.  Perform the initial handshake, login with token (see kXR_login description), and authentication (see kXR_auth description).

e.   Re-establish all open files, as needed. Previously opened files may be re-opened all at once or when a request attempts to use the file.

f.     Re-issue any requests that were sent to the previous server but have not received a response.

4)      Since XRootD allows multiple open files per physical connection, a kXR_asyncrd response can become somewhat complicated to handle. The client can re-open files immediately after a new connection is made or can re-open files as they are needed. In either case, the client must:

g.   Issue a kXR_open request using the same file name and options as was originally used.

h.   Use the returned file handle for all subsequent requests for that file (i.e., substitute the new fhandle for the old fhandle).

5)      An XRootD server should never redirect a physical connection to a rootd server. This differs for logical connections where a logical connection may be so redirected.

6)      After 256 redirect responses within 10 minutes on the same physical connection, the client should declare an internal system error since it is obvious that effective work is not being performed.


2.4.2.6       Server kXR_attn Response for kXR_asynresp Client Action

 

kXR_char

pad[2]

kXR_unt16

kXR_attn

kXR_int32

plen

kXR_int32

kXR_asynresp

kXR_char

reserved[4]

kXR_char

streamid[2]

kXR_unt16

status

kXR_int32

dlen

kXR_char

data[dlen]

 

Where:

 

rlen      is the binary length of the following action code and response.

 

streamid

            is the stream identifier associated with a previously issued request that received a  kXR_waitresp response.

 

status   is the binary status code indicating how the request completed. The codes definitions are identical as to those described for synchronous responses.

 

dlen     is the binary length of the data portion of the message. If no data is present, then the value is zero.

 

data     are data specific to the request. Not all responses have associated data. If the response does have data, the length of this field is recorded in the dlen field.

 

Notes

1)      All binary fields are transmitted in network byte order using an explicit length. The kXR_char and kXR_unt16 data types are treated as unsigned values. All reserved fields must be initialized to binary zero.

2)      Servers use the kXR_attn response code to optimize overall system performance and to notify clients of any impending events.

3)      Unlike other asynchronous events, this response is associated with a previous request and the response data must be used to complete that request.

4)      The rlen-dlen is always 16.

5)      When kXR_attn is received with the kXR_asynresp action code, the client should remove the request paired with streamid from wait state and complete it using the response data.


2.4.2.7       Server kXR_attn Response for kXR_asyncwt Client Action

 

kXR_char

pad[2]

kXR_unt16

kXR_attn

kXR_int32

8

kXR_int32

kXR_asyncwt

kXR_int32

wsec

 

Where:

 

wsec    is the number of seconds the client should wait before sending any more requests to the server.

 

Notes

1)      All binary fields are transmitted in network byte order using an explicit length. The kXR_char and kXR_unt16 data types are treated as unsigned values. All reserved fields must be initialized to binary zero.

2)      Servers use the kXR_attn response code to optimize overall system performance and to notify clients of any impending events. This response does not correspond to any client request and should not be paired up with any request.

3)      When kXR_attn is received with the kXR_asyncwt action code, the client should queue any new requests (i.e., not send new requests) until wsec seconds have elapsed.

4)      While waiting, the client should still be receiving messages from the server. It is possible for the server to send additional unsolicited responses even after a kXR_asyncwt has been sent. For example, the server may send a kXR_asyncgo request to cancel the effects of the kXR_asyncwt request before the wsec interval has gone by.

 


2.4.3        Server kXR_authmore Response Format

 

kXR_char

streamid[2]

kXR_unt16

kXR_authmore

kXR_int32

dlen

kXR_char

data[dlen]

 

Where:

 

streamid

            is the binary identifier that is associated with this request stream corresponding to a previous request.

 

dlen     is the binary length of the data portion of the message (i.e., the subsequent bytes).

 

data     is the data, if any, required to continue the authentication process.

 

Notes

1)      All binary fields are transmitted in network byte order using an explicit length. The kXR_char and kXR_unt16 data types are treated as unsigned values. All reserved fields must be initialized to binary zero.

2)      Since requests may be completed in any order, the ordering of responses is undefined. The client must appropriately pair responses with requests using the streamid value.

3)      The kXR_authmore response code is issued only for those authentication schemes that require several handshakes in order to complete (e.g., .x500).

4)      When a kXR_authmore response is received, the client must call the appropriate authentication continuation method and pass it data, if present. The output of the continuation method should be sent to the server using another kXR_auth request. This handshake continues until either the continuation method fails or the server returns a status code of kXR_error or kXR_ok.

5)      Refer to the description of the security framework for detailed information.

 


2.4.4        Server kXR_error Response Format

 

kXR_char

streamid[2]

kXR_unt16

kXR_error

kXR_int32

dlen

kXR_int32

errnum

kXR_char

errmsg[dlen-4]

 

Where:

 

streamid

            is the binary identifier that is associated with this request stream corresponding to a previous request.

 

dlen     is the binary length of the data portion of the message (i.e., the subsequent bytes).

 

errnum

            is the binary error number indicating the nature of the problem encountered when processing the request.

 

errmsg

            is the human-readable null-terminated message that describes the error. This message may be displayed for informational purposes.

 

Notes

1)      All binary fields are transmitted in network byte order using an explicit length. The kXR_char and kXR_unt16 data types are treated as unsigned values. All reserved fields must be initialized to binary zero.

2)      Since the error message is null-terminated, dlen includes the null byte in its count of bytes that were sent.

3)      Since requests may be completed in any order, the ordering of responses is undefined. The client must appropriately pair responses with requests using the streamid value.


2.4.4.1       Server kXR_error Sub-Codes & Recovery Actions

 

The following table lists possible error sub-codes included in the errnum field as part of the kXR_error response:

 

 

Status

 

Meaning

Redirector

Recovery

Server

Recovery

kXR_ArgInvalid

A request argument was not valid

n/a

n/a

kXR_ArgMissing

Required request argument was not provided

n/a

n/a

kXR_ArgTooLong

A request argument was too long (e.g., path)

n/a

n/a

kXR_AttrNotFound

The requested file attribute does not exist

n/a

n/a

kXR_BadPayload

The request arguments were malformed

n/a

n/a

kXR_Cancelled

The operation was cancelled by the administrator

n/a

n/a

kXR_ChkLenErr

The close length does not equal the file size

n/a

n/a

kXR_ChkSumErr

The kXR_verifyw checksum does not match

n/a

n/a

kXR_DecryptErr

Data could not be decrypted

n/a

n/a

kXR_FileLocked

File is locked, open request was rejected

n/a

n/a

kXR_FileNotOpen

File if not open for the request (e.g., read)

n/a

n/a

kXR_FSError

The file system indicated an error

n/a

A

kXR_fsReadOnly

The file system is marked read-only.

n/a

n/a

kXR_inProgress

Operation already in progress

B

B

kXR_InvalidRequest

The request code is invalid

n/a

n/a

kXR_IOError

An I/O error has occurred

n/a

A

kXR_isDirectory

Object being opened with kXR_open is a directory

n/a

n/a

kXR_NoMemory

Insufficient memory to complete the request

C

B

kXR_NoSpace

Insufficient disk space to write data

n/a

n/a

kXR_NotAuthorized

Client is not authorized for the request

n/a

n/a

kXR_NotFile

Object being opened with kXR_open is not a file.

n/a

n/a

kXR_NotFound

The requested file was not found

n/a

D

kXR_noserver

There are no servers available to process the request

n/a

n/a

kXR_overQuota

Space quota exceeded

n/a

n/a

kXR_overloaded

Server is overloaded

C

D

kXR_ServerError

An internal server error has occurred

C

A

kXR_SigVerErr

Request signature could not be verified

n/a

n/a

kXR_Unsupported

The request is valid but not supported

n/a

n/a

 

A.    Go back to the redirector and ask for a different server. kXR_refresh should not be turned on and “tried=” opaque value should indicate the hostname of the failing server.

B.     Generally, this represents a programming error. However, should an operation subject to a callback response be retried prior to the callback, this status code may be returned. Clients should honor server’s callback requests and wait for a callback response. Therefore, this error can be ignored as long as a callback is outstanding. Otherwise, it should be treated as a fatal error.

C.    If the redirector is replicated, a different redirector should be tried. If all redirectors provide the same response, a fatal error should be reported. In the case of intermediate redirectors (i.e., a redirector transferring the request to another redirector), the recovery may be attempted by treating the intermediate as a server and performing the action outline in A.

D.    Go back to the redirector and ask for a different server. kXR_refresh should be turned on and “tried=” opaque value should indicate the hostname of the failing server. This should normally be done only once.


2.4.5        Server kXR_ok Response Format

 

kXR_char

streamid[2]

kXR_unt16

kXR_ok

kXR_int32

dlen

kXR_char

data[dlen]

 

Where:

 

streamid

            is the binary identifier that is associated with this request stream corresponding to a previous request.

 

dlen     is the binary length of the data portion of the message (i.e., the subsequent bytes).

 

data     is the result, if any, of the corresponding request.

 

Notes

1)      All binary fields are transmitted in network byte order using an explicit length. The kXR_char and kXR_unt16 data types are treated as unsigned values. All reserved fields must be initialized to binary zero.

2)      Since requests may be completed in any order, the ordering of responses is undefined. The client must appropriately pair responses with requests using the streamid value.

3)      The kXR_ok response indicates that the request fully completed and no additional responses will be forthcoming.


2.4.6        Server kXR_oksofar Response Format

 

kXR_char

streamid[2]

kXR_unt16

kXR_oksofar

kXR_int32

dlen

kXR_char

data[dlen]

 

Where:

 

streamid

            is the binary identifier that is associated with this request stream corresponding to a previous request.

 

dlen     is the binary length of the data portion of the message (i.e., the subsequent bytes).

 

data     is the result, if any, of the corresponding request.

 

Notes

1)      All binary fields are transmitted in network byte order using an explicit length. The kXR_char and kXR_unt16 data types are treated as unsigned values. All reserved fields must be initialized to binary zero.

2)      Since requests may be completed in any order, the ordering of responses is undefined. The client must appropriately pair responses with requests using the streamid value.

3)      The kXR_oksofar response indicates that the server is providing partial results and the client should be prepared to receive additional responses on the same stream. This response is primarily used when a read request would transmit more data than the internal server segment size. Refer to the kXR_getfile and kXR_read requests.

4)      Sending requests using the same streamid when a kXR_oksofar status code has been returned may produced unpredictable results. A client must serialize all requests using the streamid in the presence of partial results.

5)      Any status code other than kXR_oksofar indicates the end of transmission

 


2.4.7        Server kXR_redirect Response Format

 

kXR_char

streamid[2]

kXR_unt16

kXR_redirect

kXR_int32

dlen

kXR_int32

port | 0xffffffff

kXR_char

host[?[opaque][?token]][dlen-4] | url

 

Where:

 

streamid

            is the binary identifier that is associated with this request stream corresponding to a previous request.

 

dlen     is the binary length of the data portion of the message (i.e., the subsequent bytes).

 

port      is the binary port number to which the client must connect. If the value is zero, the default XRootD port number must be used. If the value is negative, then the text after port contains a standard URL that must be used to effect a new connection. This should only occur if the client has indicated that URL redirection responses are acceptable during the most recent kXR_login request to the redirecting server.

 

host      is the ASCII name of the to which the client must connect. The host does not end with a null (\0) byte. The host should be interpreted as a standard URL if port is negative (see above).

 

opaque is an optional ASCII token that, when present, must be delivered to the new host as opaque information added to the file name[2] associated with the operation being redirected. The opaque, if present, is separated from the host by a single question mark. The opaque does not end with a null (\0) byte but may end with a question mark (see token below). Therefore, opaque may never contain a question mark.


 

token    is an optional ASCII token that, when present, must be delivered to the new host during the login phase, if one is needed (i.e. established connections to the specified host may be re-used without a login). The token, if present, is separated from the host by a two question marks. The first question mark may be followed by opaque information. If none is present, another question mark immediately follows the first one. The token does not end with a null (\0) byte.

 

url       when a client indicates that it supports multi-protocol redirects, the server may respond with an actual url. In this case, the port value is set to -1.

 

Notes

1)      All binary fields are transmitted in network byte order using an explicit  length. The kXR_char and kXR_unt16 data types are treated as unsigned values. All reserved fields must be initialized to binary zero.

2)      Since requests may be completed in any order, the ordering of responses is undefined. The client must appropriately pair responses with requests using the streamid value.

3)      After 256 redirect responses within 10 minutes on the same logical connection, the client should declare an internal system error since it is obvious that effective work is not being performed.

4)      The client must be prepared to handle a redirect response at any time. A redirect response requires that the client

i.     Decompose the response to extract the port number, host name, and possible token value.

j.     Possibly close the connection of the current host, if the current host is a data server and this is the last logical connection to the server. Otherwise, if this is the first load-balancing server encountered in the operation sequence, the connection should remain open since a load-balancing server always responds with a redirect.

k.   Establish a new logical connection with the indicated host at the specified or default port number. If a physical connection already exists and is session compatible with the new logical connection; the existing physical connection should be reused and the next step (i.e. handshake and login) should be skipped.

l.     Perform the initial handshake, login with token (see kXR_login description), and authentication (see kXR_auth description).

m.If the redirection occurred for a request using a file handle (i.e., fhandle) then a new file handle must be obtained.

                                                              i.      A kXR_open request must be issued using the same file name and options as was originally used.

                                                           ii.      The returned file handle must be used for the request that is to be re-issued as well as all subsequent requests relating o the file.

n.   Re-issue the request that was redirected.

5)      Opaque data must be treated as truly opaque. The client should not inspect nor modify the data in any way.

 


 

2.4.8        Server kXR_wait Response Format

 

kXR_char

streamid[2]

kXR_unt16

kXR_wait

kXR_int32

dlen

kXR_int32

seconds

kXR_char

infomsg[dlen-4]

 

Where:

 

streamid

            is the binary identifier that is associated with this request stream corresponding to a previous request.

 

dlen     is the binary length of the data portion of the message (i.e., the subsequent bytes).

 

seconds

            is the maximum binary number of seconds that the client needs to wait before re-issuing the request.

 

infomsg

            is the human-readable message that describes the reason of why the wait is necessary. The message does not end with a null (\0) byte. This message may be displayed for informational purposes.

 

Notes

1)      All binary fields are transmitted in network byte order using an explicit length. The kXR_char and kXR_unt16 data types are treated as unsigned values. All reserved fields must be initialized to binary zero.

2)      Since requests may be completed in any order, the ordering of responses is undefined. The client must appropriately pair responses with requests using the streamid value.

3)      The client should wait the indicated number of seconds and retry the request.

4)      Nothing prohibits the client from waiting for less time than the indicated number of seconds.

 


2.4.9        Server kXR_waitresp Response Format

 

kXR_char

streamid[2]

kXR_unt16

kXR_waitresp

kXR_int32

4

kXR_int32

seconds

 

Where:

 

streamid

            is the binary identifier that is associated with this request stream corresponding to a previous request.

 

seconds

            is the estimated maximum binary number of seconds that the client needs to wait for the response.

 

Notes

1)      All binary fields are transmitted in network byte order using an explicit length. The kXR_char and kXR_unt16 data types are treated as unsigned values. All reserved fields must be initialized to binary zero.

2)      Since requests may be completed in any order, the ordering of responses is undefined. The client must appropriately pair responses with requests using the streamid value.

3)      The client should wait the indicated number of seconds for the response. The response should be returned via an unsolicited response (kXR_attn with kXR_asynresp) at some later time which may be earlier than the time indicated in seconds. When the response arrives, the client must use the response data to complete the request that received the kXR_waitresp.

4)      Nothing prohibits the client from waiting for different time than the indicated number of seconds. Generally, if no response is received after at least seconds have elapsed; the client should treat the condition as a fatal error.

 


2.5       Binary Definitions of Status and Error codes

2.5.1        Status Codes

 

Status Code

Value

kXR_ok

0

kXR_oksofar

4000

kXR_attn

4001

kXR_authmore

4002

kXR_error

4003

kXR_redirect

4004

kXR_wait

4005

kXR_waitresp

4006

 

2.5.2        kXR_attn Status Subcodes

 

kXR_attn Subcode

Value

kXR_asyncab

5000

kXR_asyncdi

5001

kXR_asyncms

5002

kXR_asyncrd

5003

kXR_asyncwt

5004

kXR_asyncav

5005

kXR_asynunav

5006

kXR_asyncgo

5007

kXR_asynresp

5008

 


 

2.5.3        Error Codes

 

Error

Value

Corresponding POSIX errno Value

kXR_ArgInvalid

3000

EINVAL

kXR_ArgMissing

3001

EINVAL

kXR_ArgTooLong

3002

ENAMETOOLONG

kXR_FileLocked

3003

EDEADLK

kXR_FileNotOpen

3004

EBADF

kXR_FSError

3005

EIO

kXR_InvalidRequest

3006

EEXIST

kXR_IOError

3007

EIO

kXR_NoMemory

3008

ENOMEM

kXR_NoSpace

3009

ENOSPC

kXR_NotAuthorized

3010

EACCES

kXR_NotFound

3011

ENOENT

kXR_ServerError

3012

ENOMSG

kXR_Unsupported

3013

ENOTSUP

kXR_noserver

3014

EHOSTUNREACH

kXR_NotFile

3015

ENOTBLK

kXR_isDirectory

3016

EISDIR

kXR_Cancelled

3017

ECANCELED

kXR_ChkLenErr

3018

EDOM

kXR_ChkSumErr

3019

EDOM

kXR_inProgress

3020

EINPROGRESS

kXR_overQuota

3021

EDQUOT

kXR_SigVerErr

3022

EILSEQ

kXR_DecryptErr

3023

ERANGE

kXR_Overloaded

3024

EUSERS

kXR_fsReadOnly

3025

EROFS

kXR_BadPayload

3026

EINVAL

kXR_AttrNotFound

3027

ENOATTR


3         Detailed Protocol Specifications

3.1       kXR_admin Request

Purpose: Perform an administrative function.

 

Request

Normal Response

kXR_char

streamid[2]

kXR_char

streamid[2]

kXR_unt16

kXR_admin

kXR_unt16

kXR_ok

kXR_char

reserved[16]

kXR_int32

rlen

kXR_int32

rlen

kXR_char

resp[rlen]

kXR_char

reqs[rlen]

 

 

 

Where:

 

streamid

            is the binary identifier that is associated with this request stream. This identifier should be echoed along with any response to the request.

 

reserved

            is an area reserved for future use and must be initialized to null characters (i.e., ‘\0’).

 

rlen      is the binary length of the supplied request, reqs.

 

reqs      is the request.

 

ilen      is the binary length of the response, resp, that follows ilen.

 

resp      is the response to the administrative request.

 

Notes

1)      All binary fields are transmitted in network byte order using an explicit length. The kXR_char and kXR_unt16 data types are treated as unsigned values. All reserved fields must be initialized to binary zero.

2)      The kXR_admin request is only valid for users who have successfully performed a kXR_login operation in an administrative role (i.e., logged in as administrator).

3)      This request type is not currently supported. Use the local socket interface protocol to execute administrative requests.

 

Binary Definitions

 

Request

Modifiers

Value

Explanation

kXR_admin

 

3020

Perform administrative actions.

 


3.2       kXR_auth Request

Purpose: Authenticate client’s username to the server.

 

Request

Normal Response

kXR_char

streamid[2]

kXR_char

streamid[2]

kXR_unt16

kXR_auth

kXR_unt16

kXR_ok

kXR_char

reserved[12]

kXR_int32

0

kXR_char

credtype[4]

 

 

kXR_int32

credlen

 

 

kXR_char

cred[credlen]

 

 

 

Where:

 

streamid

            is the binary identifier that is associated with this request stream. This identifier should be echoed akXR_int32 with any response to the request.

 

reserved

            is an area reserved for future use and must be initialized to null characters (i.e., ‘\0’).

 

credtype

            the first four characters of the protocol name. If the protocol name is less than four characters, the name should be null terminated.

 

credlen

            is the binary length of the supplied credentials, cred.

 

cred     are the credentials used to provide authentication information.

 


 

Notes

1)      All binary fields are transmitted in network byte order using an explicit length. The kXR_char and kXR_unt16 data types are treated as unsigned values. All reserved fields must be initialized to binary zero.

2)      Authentication credentials may be supplied by many means. The common mechanism used by XRootD is to use the classes in the libXrdSec.so library. See the “Authentication & Access Control Configuration Reference” for more information.

3)      Refer to the description of the security framework on how a client authenticates to an XRootD server.

 

Binary Definitions

 

Request

Modifiers

Value

Explanation

kXR_auth

 

3000

Perform authenication

 



3.3       kXR_bind Request

Purpose: Bind a socket to a pre-existing session.

 

Request

Normal Response

kXR_char

streamid[2]

kXR_char

streamid[2]

kXR_unt16

kXR_bind

kXR_unt16

kXR_ok

kXR_char

sessid[16]

kXR_int32

1

kXR_int32

0

kXR_char

pathid

 

Where:

 

streamid

            is the binary identifier that is associated with this request stream. This identifier should be echoed along with any response to the request.

 

sessid   is the session identifier returned by a previous kXR_login request.

 

pathid  is the socket identifier associated with this connection. The pathid may be used in subqsequent kXR_read, kXR_readv, and kXR_write requests to indicate which socket should be used for a response or as a source of data.

 

Notes

1)      All binary fields are transmitted in network byte order using an explicit length. The kXR_char and kXR_unt16 data types are treated as unsigned values. All reserved fields must be initialized to binary zero.

2)      The sessid value should be treated as opaque data.

3)      The socket issuing the kXR_bind request must neither have a session id (i.e., be logged in) nor be already bound.

4)      Once a socket is bound to a session, if may only supply data for kXR_write requests or receive responses for kXR_read and kXR_readv requests.

5)      Each login session is limited to the number of bound sockets. Use the kXR_Qconfig sub-request code of kXR_query to determine the maximum number of sockets that can be bound to a login session.

6)      Bound sockets are meant to support parallel data transfer requests across wide-area networks.

 


 

Binary Definitions

 

Request

Modifiers

Value

Explanation

kXR_bind

 

3024

Bind additional sockets to session

 

 


3.4       kXR_chmod Request

Purpose: Change the access mode on a directory or a file.

 

Request

Normal Response

kXR_char

streamid[2]

kXR_char

streamid[2]

kXR_unt16

kXR_chmod

kXR_unt16

kXR_ok

kXR_char

reserved[14]

kXR_int32

0

kXR_int16

mode

 

 

kXR_int32

plen

 

 

kXR_char

path[plen]

 

 

 

Where:

 

streamid

            is the binary identifier that is associated with this request stream. This identifier should be echoed along with any response to the request.

 

reserved

            is an area reserved for future use and must be initialized to null characters (i.e., ‘\0’).

 

mode    is the access mode to be set for path. The access mode is an “or’d” combination of the following values:

 

Access

Readable

Writeable

Executable

Owner

kXR_ur

kXR_uw

not supported

Group

kXR_gr

kXR_gw

not supported

Other

kXR_or

not supported

not supported

 

plen     is the binary length of the supplied path, path.

 

path     is the path whose mode is to be set.

 

Notes

1)      All binary fields are transmitted in network byte order using an explicit length. The kXR_char and kXR_unt16 data types are treated as unsigned values. All reserved fields must be initialized to binary zero.

2)      No umask is applied to the specified mode.

 


 

Binary Definitions

 

Request

Modifiers

Value

Explanation

kXR_chmod

 

3002

Change directory or file permissions

 

mode

 

 

 

kXR_ur

0x01 00

Owner readable

 

kXR_uw

0x00 80

Owner writable

 

kXR_ux

0x00 40

Owner searchable (directories)

 

kXR_gr

0x00 20

Group readable

 

kXR_gw

0x00 10

Group writable

 

kXR_gx

0x00 08

Group searchable (directories)

 

kXR_or

0x00 04

Other readable

 

kXR_ow

0x00 02

Other writable

 

kXR_ox

0x00 01

Other searchable (directories)

 

 


3.5       kXR_close Request

Purpose: Close a previously opened file, communications path, or path group.

 

Request

Normal Response

kXR_char

streamid[2]

kXR_char

streamid[2]

kXR_unt16

kXR_close

kXR_unt16

kXR_ok

kXR_char

fhandle[4]

kXR_int32

0

kXR_char

reserved[12]

 

 

kXR_int32

0

 

 

 

Where:

 

streamid

            is the binary identifier that is associated with this request stream. This identifier should be echoed along with any response to the request.

 

reserved

            is an area reserved for future use and must be initialized to null characters (i.e., ‘\0’).

 

fhandle

            is the file handle value supplied by the successful response to the associated kXR_open request.

 

Notes

1)      All binary fields are transmitted in network byte order using an explicit length. The kXR_char and kXR_unt16 data types are treated as unsigned values. All reserved fields must be initialized to binary zero.

2)      The fhandle value should be treated as opaque data.

 

Binary Definitions

 

Request

Modifiers

Value

Explanation

kXR_close

 

3003

Close an open file

 


3.6       kXR_decrypt Request

Purpose: Signal when the data stream is encrypted (placeholder for future enhancement)..

 

Request

Normal Response

kXR_char

streamid[2]

kXR_char

streamid[2]

kXR_unt16

kXR_decrypt

kXR_unt16

kXR_ok

kXR_char

reserved[16]

kXR_int32

0

kXR_int32

0

 

 

 

Where:

 

streamid

            is the binary identifier that is associated with this request stream. This identifier should be echoed along with any response to the request.

 

reserved

            is a reserved field and should be set to zero.

 

Notes

1)      All binary fields are transmitted in network byte order using an explicit length. The kXR_char and kXR_unt16 data types are treated as unsigned values. All reserved fields must be initialized to binary zero.

2)      The kXR_decrypt request should be considered as not fully specified. It is currently a place-holder for future enhancement.

 

Binary Definitions

 

Request

Modifiers

Value

Explanation

kXR_decrypt

 

3030

Indicate an encrypted data stream

 


3.7       kXR_dirlist Request

Purpose: Enumerate the contents of a directory.

 

Request

Normal Response

kXR_char

streamid[2]

kXR_char

streamid[2]

kXR_unt16

kXR_dirlist

kXR_unt16

kXR_ok

kXR_char

reserved[15]

kXR_int32

dlen

kXR_char

options

kXR_char

Dirname0\n

kXR_int32

plen

 

kXR_char

path[plen]

 

 

 

 

kXR_char

kXR_char

dirnamen

0

 

Normal Response w/ kXR_dstat

 

 

kXR_char

streamid[2]

 

 

kXR_unt16

kXR_ok

 

 

kXR_int32

dlen

 

 

kXR_char

“.\n”

 

 

kXR_char