4 SMB RequestsThis section lists the "best practice" SMB requests ones that would permit a client to exercise full CIFS functionality and optimum performance when interoperating with a server speaking the latest dialect as of this writing ("NT LM 0.12"). Note that, as of this writing, no existing client restricts itself to only these requests, so no useful server can be written that supports just them. The classification is provided so that future clients will be written to permit future servers to be simpler. 4.1 Session Requests4.1.1 NEGOTIATE: Negotiate ProtocolThe following list describes the format of the NEGOTIATE client request: Client Request Description =============== ============ UCHAR WordCount; Count of parameter words = 0 USHORT ByteCount; Count of data bytes; min = 2 struct { UCHAR BufferFormat; 0x02 -- Dialect UCHAR DialectName[]; ASCII null-terminated string } Dialects[]; The Client sends a list of dialects with which it can communicate. The response is a selection of one of those dialects (numbered 0 through n) or -1 (hex FFFF) indicating that none of the dialects were acceptable. The negotiate message is binding on the virtual circuit and must be sent. One and only one negotiate message may be sent, subsequent negotiate requests will be rejected with an error response and no action will be taken. The protocol does not impose any particular structure to the dialect strings. Implementers of particular protocols may choose to include, for example, version numbers in the string. If the server does not understand any of the dialect strings, or if PC NETWORK PROGRAM 1.0 is the chosen dialect, the response format is: Server Response Description ================ ============ UCHAR WordCount; Count of parameter words = 1 USHORT DialectIndex; Index of selected dialect USHORT ByteCount; Count of data bytes = 0 If the chosen dialect is greater than core up to and including LANMAN2.1, the protocol response format is: Server Response Description ================ ============ UCHAR WordCount; Count of parameter words = 13 USHORT DialectIndex; Index of selected dialect USHORT SecurityMode; Security mode: bit 0: 0 = share, 1 = user bit 1: 1 = use challenge/response authentication USHORT MaxBufferSize; Max transmit buffer size (>= 1024) USHORT MaxMpxCount; Max pending multiplexed requests USHORT MaxNumberVcs; Max VCs between client and server USHORT RawMode; Raw modes supported: bit 0: 1 = Read Raw supported bit 1: 1 = Write Raw supported ULONG SessionKey; Unique token identifying this session SMB_TIME ServerTime; Current time at server SMB_DATE ServerDate; Current date at server USHORT ServerTimeZone; Current time zone at server USHORT EncryptionKeyLength; MUST BE ZERO if not LM2.1 dialect USHORT Reserved; MUST BE ZERO USHORT ByteCount; Count of data bytes UCHAR EncryptionKey[]; The challenge encryption key STRING PrimaryDomain[]; The server's primary domain MaxBufferSize is the size of the largest message which the client can legitimately send to the server. If bit0 of the Flags field is set in the negotiate response, this indicates the server supports the obsolescent SMB_COM_LOCK_AND_READ and SMB_COM_WRITE_AND_UNLOCK client requests. If the SecurityMode field indicates the server is running in user mode, the client must send appropriate SMB_COM_SESSION_SETUP_ANDX requests before the server will allow the client to access resources. If the SecurityMode field indicates the client should use challenge/response authentication, the client should use the authentication mechanism specified in the Section 2.8. Clients using the "MICROSOFT NETWORKS 1.03" dialect use a different form of raw reads than documented here, and servers are better off setting RawMode in this response to 0 for such sessions. If the negotiated dialect is "DOS LANMAN2.1" or "LANMAN2.1", then PrimaryDomain string should be included in this response. If the negotiated dialect is NT LM 0.12, the response format is: Server Response Description ================ ============ UCHAR WordCount; Count of parameter words = 17 USHORT DialectIndex; Index of selected dialect UCHAR SecurityMode; Security mode: bit 0: 0 = share, 1 = user bit 1: 1 = encrypt passwords bit 2: 1 = Security Signatures (SMB sequence numbers) enabled bit 3: 1 = Security Signatures (SMB sequence numbers) required USHORT MaxMpxCount; Max pending outstanding requests USHORT MaxNumberVcs; Max VCs between client and server ULONG MaxBufferSize; Max transmit buffer size ULONG MaxRawSize; Maximum raw buffer size ULONG SessionKey; Unique token identifying this session ULONG Capabilities; Server capabilities ULONG SystemTimeLow; System (UTC) time of the server (low) ULONG SystemTimeHigh; System (UTC) time of the server (high) USHORT ServerTimeZone; Time zone of server (minutes from UTC) CHAR EncryptionKeyLength; Length of encryption key USHORT ByteCount; Count of data bytes UCHAR EncryptionKey[]; The challenge encryption key; Present only for Non Extended Security i.e., CAP_EXTENDED_SECURITY is off in the Capabilities field UCHAR OemDomainName[]; The name of the domain (in OEM chars); Present Only for Non Extended Security i.e., CAP_EXTENDED_SECURITY is off in the Capabilities field UCHAR GUID[16]; A globally unique identifier assigned to the server; Present only when CAP_EXTENDED_SECURITY is on in Capabilities field UCHAR SecurityBlob[]; Opaque Security Blob associated with the security package if CAP_EXTENDED_SECURITY is on in the Capabilities field; else challenge for CIFS challenge/response authentication In addition to the definitions above, MaxBufferSize is the size of the largest message which the client can legitimately send to the server. If the client is using a connectionless protocol, MaxBufferSize must be set to the smaller of the server's internal buffer size and the amount of data which can be placed in a response packet. MaxRawSize specifies the maximum message size the server can send or receive for the obsolescent SMB_COM_WRITE_RAW or SMB_COM_READ_RAW requests. Connectionless clients must set Sid to 0 in the SMB request header. The Capabilities field allows the server to tell the client what it supports. The client must not ignore any capabilities specified by the server. The bit definitions are:
Undefined bit MUST be set to zero by servers, and MUST be ignored by clients. Extended security exchanges provide a means of supporting arbitrary authentication protocols within CIFS. Security blobs are opaque to the CIFS protocol; they are messages in some authentication protocol that has been agreed upon by client and server by some out of band mechanism, for which CIFS merely functions as a transport. When CAP_EXTENDED_SECURITY is negotiated, the server includes a first security blob in its response; subsequent security blobs are exchanged in SMB_COM_SESSION_SETUP_ANDX requests and responses until the authentication protocol terminates. If the negotiated dialect is NT LM 0.12, then the capabilities field of the Negotiate protocol response indicates whether the server supports Unicode. The server is not required to support Unicode. Unicode is supported in Win9x and NT clients. If Unicode is not supported by the server then some localized of these clients may experience unexpected behavior with filenames, resource names and user names . ASCII defines the values of 128 characters (0x00 through 0x7F). The remaining 128 values (0x80 through 0xFF) are mapped into different DOS Code Pages (aka the OEM character set). Different localized clients may use different code pages. (For example, Code Page 437 is the default in English based systems). Clients can create file and folder names in their default code page that follows the file naming rules and may contain both ASCII and non-ASCII characters . 4.1.1.1 ErrorsSUCCESS/SUCCESS ERRSRV/ERRerror 4.1.2 SESSION_SETUP_ANDX: Session SetupThis SMB is used to further "Set up" the session normally just established via the negotiate protocol. One primary function is to perform a "user logon" in the case where the server is in user level security mode. The Uid in the SMB header is set by the client to be the userid desired for the AccountName and validated by the AccountPassword. 4.1.2.1 Pre NT LM 0.12If the negotiated protocol is prior to NT LM 0.12, the format of SMB_COM_SESSION_SETUP_ANDX is: Client Request Description =============== ============ UCHAR WordCount; Count of parameter words = 10 UCHAR AndXCommand; Secondary (X) command; 0xFF = none UCHAR AndXReserved; Reserved (must be 0) USHORT AndXOffset; Offset to next command WordCount USHORT MaxBufferSize; Client maximum buffer size USHORT MaxMpxCount; Actual maximum multiplexed pending requests USHORT VcNumber; 0 = first (only), nonzero=additional VC number ULONG SessionKey; Session key (valid iff VcNumber != 0) USHORT PasswordLength; Account password size ULONG Reserved; Must be 0 USHORT ByteCount; Count of data bytes; min = 0 UCHAR AccountPassword[]; Account Password STRING AccountName[]; Account Name STRING PrimaryDomain[]; Client's primary domain STRING NativeOS[]; Client's native operating system STRING NativeLanMan[]; Client's native LAN Manager type The server response is: Server Response Description ================ ============ UCHAR WordCount; Count of parameter words = 3 UCHAR AndXCommand; Secondary (X) command; 0xFF = none UCHAR AndXReserved; Reserved (must be 0) USHORT AndXOffset; Offset to next command WordCount USHORT Action; Request mode: bit0 = logged in as GUEST USHORT ByteCount; Count of data bytes STRING NativeOS[]; Server's native operating system STRING NativeLanMan[]; Server's native LAN Manager type STRING PrimaryDomain[]; Server's primary domain If the server is in "share level security mode", the account name and password should be ignored by the server. If challenge/response authentication is not being used, AccountPassword should be a null terminated ASCII string with PasswordLength set to the string size including the null; the password will be case insensitive. If challenge/response authentication is being used, then AccountPassword will be the response to the server's challenge, and PasswordLength should be set to its length. The server validates the name and password supplied and if valid, it registers the user identifier on this session as representing the specified AccountName. The Uid field in the SMB header will then be used to validate access on subsequent SMB requests. The SMB requests where permission checks are required are those which refer to a symbolically named resource such as SMB_COM_OPEN, SMB_COM_RENAME, SMB_COM_DELETE, etc. The value of the Uid is relative to a specific client/server session so it is possible to have the same Uid value represent two different users on two different sessions at the server. Multiple session setup commands may be sent to register additional users on this session. If the server receives an additional SMB_COM_SESSION_SETUP_ANDX, only the Uid, AccountName and AccountPassword fields need contain valid values (the server MUST ignore the other fields). The client writes the name of its domain in PrimaryDomain if it knows what the domain name is. If the domain name is unknown, the client either encodes it as a NULL string, or as a question mark. If bit0 of Action is set, this informs the client that although the server did not recognize the AccountName, it logged the user in as a guest. This is optional behavior by the server, and in any case one would ordinarily expect guest privileges to limited. Another function of the Session Set Up protocol is to inform the server of the maximum values which will be utilized by this client. Here MaxBufferSize is the maximum message size which the client can receive. Thus although the server may support 16k buffers (as returned in the SMB_COM_NEGOTIATE response), if the client only has 4k buffers, the value of MaxBufferSize here would be 4096. The minimum allowable value for MaxBufferSize is 1024. The SMB_COM_NEGOTIATE response includes the server buffer size supported. Thus this is the maximum SMB message size which the client can send to the server. This size may be larger than the size returned to the server from the client via the SMB_COM_SESSION_SETUP_ANDX protocol which is the maximum SMB message size which the server may send to the client. Thus if the server's buffer size were 4k and the client's buffer size were only 2K, the client could send up to 4k (standard) write requests but must only request up to 2k for (standard) read requests. The VcNumber field specifies whether the client wants this to be the first VC or an additional VC. The values for MaxBufferSize, MaxMpxCount, and VcNumber must be less than or equal to the maximum values supported by the server as returned in the SMB_COM_NEGOTIATE response. If the server gets a SMB_COM_SESSION_SETUP_ANDX request with VcNumber of 0 and other VCs are still connected to that client, they will be aborted thus freeing any resources held by the server. This condition could occur if the client was rebooted and reconnected to the server before the transport level had informed the server of the previous VC termination. 4.1.2.2 NT LM 0.12If the negotiated SMB dialect is "NT LM 0.12" and the server supports ExtendedSecurity i.e. the CAP_EXTENDED_SECURITY flag is set in the Capabilities field of the Negotiate Response SMB, the Extended Security SessionSetup SMB format is: Client Request Description =============== ============ UCHAR WordCount; Count of parameter words = 12 UCHAR AndXCommand; Secondary (X) command; 0xFF = none UCHAR AndXReserved; Reserved (must be 0) USHORT AndXOffset; Offset to next command WordCount USHORT MaxBufferSize; Client's maximum buffer size USHORT MaxMpxCount; Actual maximum multiplexed pending requests USHORT VcNumber; 0 = first (only), nonzero=additional VC number ULONG SessionKey; Session key (valid iff VcNumber != 0) USHORT SecurityBlobLength; Length of opaque security blob ULONG Reserved; Must be 0 ULONG Capabilities; Client capabilities USHORT ByteCount; Count of data bytes; min = 0 UCHAR SecurityBlob[]; The opaque security blob STRING NativeOS[]; Client's native operating system, Unicode STRING NativeLanMan[]; Client's native LAN Manager type, Unicode And the server response is: Server Response Description ================ ============ UCHAR WordCount; Count of parameter words = 4 UCHAR AndXCommand; Secondary (X) command; 0xFF = none UCHAR AndXReserved; Reserved (must be 0) USHORT AndXOffset; Offset to next command WordCount USHORT Action; Request mode: bit0 = logged in as GUEST USHORT SecurityBlobLength; Length of Security Blob that follows in a later field USHORT ByteCount; Count of data bytes UCHAR SecurityBlob[]; SecurityBlob of length specified by the field, SecurityBlobLength STRING NativeOS[]; Server's native operating system STRING NativeLanMan[]; Server's native LAN Manager type STRING PrimaryDomain[]; Server's primary domain There may be multiple round trips involved in the security blob exchange. In that case, the server may return an error STATUS_MORE_PROCESSING_REQUIRED (a value of 0xC0000016) in the SMB status. The client can then repeat the SessionSetupAndX SMB with the rest of the security blob. If the negotiated SMB dialect is "NT LM 0.12" or later and the server does not support Extended Security (i.e. the CAP_EXTENDED_SECURITY flag in the Capabilities field of the Negotiate Response SMB is not set), the format of the response SMB is unchanged, but the request is: Client Request Description =============== ============ UCHAR WordCount; Count of parameter words = 13 UCHAR AndXCommand; Secondary (X) command; 0xFF = none UCHAR AndXReserved; Reserved (must be 0) USHORT AndXOffset; Offset to next command WordCount USHORT MaxBufferSize; Client's maximum buffer size USHORT MaxMpxCount; Actual maximum multiplexed pending requests USHORT VcNumber; 0 = first (only), nonzero=additional VC number ULONG SessionKey; Session key (valid iff VcNumber != 0) USHORT Account password size, ANSI CaseInsensitivePasswordLength; USHORT Account password size, Unicode CaseSensitivePasswordLength; ULONG Reserved; Must be 0 ULONG Capabilities; Client capabilities USHORT ByteCount; Count of data bytes; min = 0 UCHAR Account Password, ANSI CaseInsensitivePassword[]; UCHAR Account Password, Unicode CaseSensitivePassword[]; UCHAR Reserved2 Present if Unicode negotiated to even byte boundary STRING AccountName[]; Account Name, Unicode STRING PrimaryDomain[]; Client's primary domain, Unicode STRING NativeOS[]; Client's native operating system, Unicode STRING NativeLanMan[]; Client's native LAN Manager type, Unicode The client expresses its capabilities to the server encoded in the Capabilities field. The format of that field is:
The entire message sent and received including the optional ANDX SMB must fit in the negotiated maximum transfer size. The following are the only valid SMB commands for AndXCommand for SMB_COM_SESSION_SETUP_ANDX: SMB_COM_TREE_CONNECT_ANDX SMB_COM_OPEN SMB_COM_OPEN_ANDX SMB_COM_CREATE SMB_COM_CREATE_NEW SMB_COM_CREATE_DIRECTORY SMB_COM_DELETE SMB_COM_DELETE_DIRECTORY SMB_COM_FIND SMB_COM_FIND_UNIQUE SMB_COM_COPY SMB_COM_RENAME SMB_COM_NT_RENAME SMB_COM_CHECK_DIRECTORY SMB_COM_QUERY_INFORMATION SMB_COM_SET_INFORMATION SMB_COM_NO_ANDX_COMMAND SMB_COM_OPEN_PRINT_FILE SMB_COM_GET_PRINT_QUEUE SMB_COM_TRANSACTION 4.1.2.3 ErrorsERRSRV/ERRerror - No NEG_PROT issued ERRSRV/ERRbadpw - Password not correct for given username ERRSRV/ERRtoomanyuids - Maximum number of users per session exceeded ERRSRV/ERRnosupport - Chaining of this request to the previous is not supported 4.1.3 LOGOFF_ANDX: User LogoffThis SMB is the inverse of SMB_COM_SESSION_SETUP_ANDX. Client Request Description =============== ============ UCHAR WordCount; Count of parameter words = 2 UCHAR AndXCommand; Secondary (X) command; 0xFF = none UCHAR AndXReserved; Reserved (must be 0) USHORT AndXOffset; Offset to next command WordCount USHORT ByteCount; Count of data bytes = 0 The server response is: Server Response Description ================ ============ UCHAR WordCount; Count of parameter words = 2 UCHAR AndXCommand; Secondary (X) command; 0xFF = none UCHAR AndXReserved; Reserved (must be 0) USHORT AndXOffset; Offset to next command WordCount USHORT ByteCount; Count of data bytes = 0 The user represented by Uid in the SMB header is logged off. The server closes all files currently open by this user, and invalidates any outstanding requests with this Uid. SMB_COM_SESSION_SETUP_ANDX is the only valid AndXCommand for this SMB. 4.1.3.1 ErrorsERRSRV/invnid - TID was invalid ERRSRV/baduid - UID was invalid 4.1.4 TREE_CONNECT_ANDX: Tree ConnectThe TREE_CONNECT_ANDX client request is defined below: Client Request Description =============== ============ UCHAR WordCount; Count of parameter words = 4 UCHAR AndXCommand; Secondary (X) command; 0xFF = none UCHAR AndXReserved; Reserved (must be 0) USHORT AndXOffset; Offset to next command WordCount USHORT Flags; Additional information bit 0 set = Disconnect Tid USHORT PasswordLength; Length of Password[] USHORT ByteCount; Count of data bytes; min = 3 UCHAR Password[]; Password STRING Path[]; Server name and share name STRING Service[]; Service name The serving machine verifies the combination and returns an error code or an identifier. The full name is included in this request message and the identifier identifying the connection is returned in the Tid field of the SMB header. The Tid field in the client request is ignored. The meaning of this identifier (Tid) is server specific; the client must not associate any standard meaning to it. If the negotiated dialect is LANMAN1.0 or later, then it is a protocol violation for the client to send this message prior to a successful SMB_COM_SESSION_SETUP_ANDX, and the server ignores Password. If the negotiated dialect is prior to LANMAN1.0 and the client has not sent a successful SMB_COM_SESSION_SETUP_ANDX request when the tree connect arrives, a user level security mode server must nevertheless validate the client's credentials as discussed earlier in this document. Path follows UNC style syntax, that is to say it is encoded as \\server\share and it indicates the name of the resource to which the client wishes to connect. Because Password may be an authentication response, it is a variable length field with the length specified by PasswordLength. If authentication is not being used, Password should be a null terminated ASCII string with PasswordLength set to the string size including the terminating null. The server can enforce whatever policy it desires to govern share access. Typically, if the server is paused, administrative privilege is required to connect to any share; if the server is not paused , administrative privilege is required only for administrative shares (C$, etc.). Other such policies may include valid times of day, software usage license limits, number of simultaneous server users or share users, etc. The Service component indicates the type of resource the client intends to access. Valid values are:
If bit0 of Flags is set, the tree connection to Tid in the SMB header should be disconnected. If this tree disconnect fails, the error should be ignored. If the negotiated dialect is earlier than DOS LANMAN2.1, the response to this SMB is: Server Response Description ================ ============ UCHAR WordCount; Count of parameter words = 2 UCHAR AndXCommand; Secondary (X) command; 0xFF = none UCHAR AndXReserved; Reserved (must be 0) USHORT AndXOffset; Offset to next command WordCount USHORT ByteCount; Count of data bytes; min = 3 If the negotiated is DOS LANMAN2.1 or later, the response to this SMB is: Server Response Description ================ ============ UCHAR WordCount; Count of parameter words = 3 UCHAR AndXCommand; Secondary (X) command; 0xFF = none UCHAR AndXReserved; Reserved (must be 0) USHORT AndXOffset; Offset to next command WordCount USHORT OptionalSupport; Optional support bits SMB_SUPPORT_SEARCH_BITS = 0x0001 Exclusive search bits ("MUST HAVE BITS") supported SMB_SHARE_IS_IN_DFS = 0x0002 USHORT ByteCount; Count of data bytes; min = 3 UCHAR Service[]; Service type connected (Always ANSII) STRING NativeFileSystem[]; Native file system for this tree NativeFileSystem is the name of the filesystem. Expected values include FAT, NTFS, etc. Some servers negotiate "DOS LANMAN2.1" dialect or later and still send the "downlevel" (i.e. wordcount==2) response. Valid AndX following commands are: SMB_COM_OPEN SMB_COM_OPEN_ANDX SMB_COM_CREATE SMB_COM_CREATE_NEW SMB_COM_CREATE_DIRECTORY SMB_COM_DELETE SMB_COM_DELETE_DIRECTORY SMB_COM_FIND SMB_COM_COPY SMB_COM_FIND_UNIQUE SMB_COM_RENAME SMB_COM_CHECK_DIRECTORY SMB_COM_QUERY_INFORMATION SMB_COM_GET_PRINT_QUEUE SMB_COM_OPEN_PRINT_FILE SMB_COM_TRANSACTION SMB_COM_NO_ANDX_CMD SMB_COM_SET_INFORMATION SMB_COM_NT_RENAME 4.1.4.1 ErrorsERRDOS/ERRnomem ERRDOS/ERRbadpath ERRDOS/ERRinvdevice ERRSRV/ERRaccess ERRSRV/ERRbadpw ERRSRV/ERRinvnetname 4.1.5 TREE_DISCONNECT: Tree DisconnectThis message informs the server that the client no longer wishes to access the resource connected via a prior SMB_COM_TREE_CONNECT or SMB_COM_TREE_CONNECT_ANDX. Client Request Description =============== ============ UCHAR WordCount; Count of parameter words = 0 USHORT ByteCount; Count of data bytes = 0 The resource sharing connection identified by Tid in the SMB header is logically disconnected from the server. Tid is invalidated; it will not be recognized if used by the client for subsequent requests. All locks, open files, etc. created on behalf of Tid are released. Server Response Description ================ ============ UCHAR WordCount; Count of parameter words = 0 USHORT ByteCount; Count of data bytes = 0 4.1.5.1 ErrorsERRSRV/ERRinvnid ERRSRV/ERRbaduid 4.1.6 TRANS2_QUERY_FS_INFORMATION: Get File System InformationThis transaction requests information about a filesystem on the server. Its format is: Client Request Value ================ ====== WordCount 15 TotalParameterCount 2 or 4 MaxSetupCount 0 SetupCount 1 or 2 Setup[0] TRANS2_QUERY_FS_INFORMATION The request's parameter block encodes InformationLevel (a USHORT), describing the level of filesystem info that should be returned. Values for InformationLevel are specified in the table below. The filesystem is identified by Tid in the SMB header. MaxDataCount in the transaction request must be large enough to accommodate the response. The encoding of the response parameter block depends on the InformationLevel requested. Information levels whose values are greater than 0x102 are mapped to corresponding operating system calls (NtQueryVolumeInformationFile calls) by the server. The two levels below 0x102 are described below. The requested information is placed in the Data portion of the transaction response.
The following sections describe the InformationLevel dependent encoding of the data part of the transaction response. 4.1.6.1 SMB_INFO_ALLOCATIONInformationLevel Data Block Encoding Description ==================== ============ ULONG idFileSystem; File system identifier (NT server always returns 0) ULONG cSectorUnit; Number of sectors per allocation unit ULONG cUnit; Total number of allocation units ULONG cUnitAvail; Total number of available allocation units USHORT cbSector; Number of bytes per sector 4.1.6.2 SMB_INFO_VOLUMEInformationLevel Data Block Encoding Description ==================== ============ ULONG ulVsn; Volume serial number UCHAR cch; Number of characters in Label STRING Label; The volume label 4.1.6.3 SMB_QUERY_FS_VOLUME_INFOInformationLevel Data Block Encoding Description ==================== ============ SMB_TIME Volume Creation Time ULONG Volume Serial Number ULONG Length of Volume Label in bytes BYTE Reserved BYTE Reserved STRING Label; The volume label 4.1.6.4 SMB_QUERY_FS_SIZE_INFOInformationLevel Data Block Encoding Description ==================== ============ LARGE_INTEGER Total Number of Allocation units on the Volume LARGE_INTEGER Number of free Allocation units on the Volume ULONG Number of sectors in each Allocation unit ULONG Number of bytes in each sector 4.1.6.5 SMB_QUERY_FS_DEVICE_INFOInformationLevel Data Block Encoding Description ==================== ====== ULONG DeviceType; Values as specified below ULONG Characteristics of the device; Values as specified below For DeviceType, note that the values 0-32767 are reserved for the exclusive use of Microsoft Corporation. The following device types are currently defined: FILE_DEVICE_BEEP 0x00000001 FILE_DEVICE_CD_ROM 0x00000002 FILE_DEVICE_CD_ROM_FILE_SYSTEM 0x00000003 FILE_DEVICE_CONTROLLER 0x00000004 FILE_DEVICE_DATALINK 0x00000005 FILE_DEVICE_DFS 0x00000006 FILE_DEVICE_DISK 0x00000007 FILE_DEVICE_DISK_FILE_SYSTEM 0x00000008 FILE_DEVICE_FILE_SYSTEM 0x00000009 FILE_DEVICE_INPORT_PORT 0x0000000a FILE_DEVICE_KEYBOARD 0x0000000b FILE_DEVICE_MAILSLOT 0x0000000c FILE_DEVICE_MIDI_IN 0x0000000d FILE_DEVICE_MIDI_OUT 0x0000000e FILE_DEVICE_MOUSE 0x0000000f FILE_DEVICE_MULTI_UNC_PROVIDER 0x00000010 FILE_DEVICE_NAMED_PIPE 0x00000011 FILE_DEVICE_NETWORK 0x00000012 FILE_DEVICE_NETWORK_BROWSER 0x00000013 FILE_DEVICE_NETWORK_FILE_SYSTEM 0x00000014 FILE_DEVICE_NULL 0x00000015 FILE_DEVICE_PARALLEL_PORT 0x00000016 FILE_DEVICE_PHYSICAL_NETCARD 0x00000017 FILE_DEVICE_PRINTER 0x00000018 FILE_DEVICE_SCANNER 0x00000019 FILE_DEVICE_SERIAL_MOUSE_PORT 0x0000001a FILE_DEVICE_SERIAL_PORT 0x0000001b FILE_DEVICE_SCREEN 0x0000001c FILE_DEVICE_SOUND 0x0000001d FILE_DEVICE_STREAMS 0x0000001e FILE_DEVICE_TAPE 0x0000001f FILE_DEVICE_TAPE_FILE_SYSTEM 0x00000020 FILE_DEVICE_TRANSPORT 0x00000021 FILE_DEVICE_UNKNOWN 0x00000022 FILE_DEVICE_VIDEO 0x00000023 FILE_DEVICE_VIRTUAL_DISK 0x00000024 FILE_DEVICE_WAVE_IN 0x00000025 FILE_DEVICE_WAVE_OUT 0x00000026 FILE_DEVICE_8042_PORT 0x00000027 FILE_DEVICE_NETWORK_REDIRECTOR 0x00000028 FILE_DEVICE_BATTERY 0x00000029 FILE_DEVICE_BUS_EXTENDER 0x0000002a FILE_DEVICE_MODEM 0x0000002b FILE_DEVICE_VDM 0x0000002c Some of these device types are not currently accessible over the network, and may never be accessible on the network. Some may change to be accessible in the future. The values for device types that will never be accessible over the network may be redefined to be "reserved". For the encoding of "Characteristics" in the protocol request, this field is the sum of any of the following: FILE_REMOVABLE_MEDIA 0x00000001 FILE_READ_ONLY_DEVICE 0x00000002 FILE_FLOPPY_DISKETTE 0x00000004 FILE_WRITE_ONE_MEDIA 0x00000008 FILE_REMOTE_DEVICE 0x00000010 FILE_DEVICE_IS_MOUNTED 0x00000020 FILE_VIRTUAL_VOLUME 0x00000040 4.1.6.6 SMB_QUERY_FS_ATTRIBUTE_INFOInformationLevel Data Block Encoding Description ==================== ============ ULONG File System Attributes; possible values described below LONG Maximum length of each file name component in number of bytes ULONG Length, in bytes, of the name of the file system STRING Name of the file system Where FileSystemAttributes are the sum of any of the following: FILE_CASE_SENSITIVE_SEARCH 0x00000001 FILE_CASE_PRESERVED_NAMES 0x00000002 FILE_PERSISTENT_ACLS 0x00000004 FILE_FILE_COMPRESSION 0x00000008 FILE_VOLUME_QUOTAS 0x00000010 FILE_DEVICE_IS_MOUNTED 0x00000020 FILE_VOLUME_IS_COMPRESSED 0x00008000 4.1.6.7 SMB_QUERY_CIFS_UNIX_INFOInformationLevel Data Block Encoding Description ==================== ============ UNIT16 MajorVersionNumber; Major version of CIFS UNIX supported by server UNIT16 MinorVersionNumber; Minor version of CIFS UNIX supported by server LARGE_INTEGER Capability; Capabilities of CIFS UNIX support by Server Where Capability is the sum of the following:
4.1.6.8 SMB_QUERY_MAC_FS_INFOInformationLevel Data Block Encoding Description ==================== ============ LARGE_INTEGER CreationTime; Volume creation time - NT TIME. LARGE_INTEGER ModifyTime; Volume Modify time - NT TIME. LARGE_INTEGER BackUpTime; Volume was last Backup time - NT TIME. Defaults to Create Time. ULONG NmAlBlks; The number of allocation blocks in the volume ULONG AlBlkSiz; The allocation block size (in bytes) Must be in multiple of 512 bytes ULONG FreeBks; The number of unused allocations blocks on the volume UCHAR [32]; FndrInfo[32]; Information used by the finder that is always in Big Endian. Bytes 0-3 File Type If a file default to 'TEXT' otherwise default to zero Bytes 4-7 File Creator If a file default to 'dosa' otherwise default to zero Bytes 8-9 a UWORD flags field If hidden item set this UWORD to 0x4000 else defaults to zero All other bytes should default to zero and are only changeable by the Macintosh LONG NmFls; The number of files in the root directory; Zero if not known LONG NmRtDirs; The number of directories in the root directory; Zero if not known LONG FilCnt; The number of files on the volume; Zero if not known LONG DirCnt; The number of directories on the volume; Zero if not known LONG MacSupportFlags; Must be zero unless you support the other Macintosh options Where MacSupportFlags is the sum of any of the following:
4.1.6.9 ErrorsERRSRV/invnid - TID was invalid ERRSRV/baduid - UID was invalid ERRHRD/ERRnotready - The file system has been removed ERRHRD/ERRdata - Disk I/O error ERRSRV/ERRaccess - User does not have rights to perform this operation ERRSRV/ERRinvdevice - Resource identified by TID is not a file system 4.1.7 ECHO: Ping the ServerThis request is used to test the connection to the server, and to see if the server is still responding. The client request is defined as: Client Request Description =============== ============ UCHAR WordCount; Count of parameter words = 1 USHORT EchoCount; Number of times to echo data back USHORT ByteCount; Count of data bytes; min = 1 UCHAR Buffer[1]; Data to echo And, the server response is: Server Response Description ================ ============ UCHAR WordCount; Count of parameter words = 1 USHORT SequenceNumber; Sequence number of this echo USHORT ByteCount; Count of data bytes; min = 4 UCHAR Buffer[1]; Echoed data Each response echoes the data sent, though ByteCount may indicate "no data". If EchoCount is zero, no response is sent. Tid in the SMB header is ignored, so this request may be sent to the server even if there are no valid tree connections to the server. The flow for the ECHO protocol is:
4.1.7.1 ErrorsERRSRV/ERRbaduid - UID was invalid ERRSRV/ERRnoaccess - session has not been established ERRSRV/ERRnosupport - ECHO function is not supported 4.1.8 NT_CANCEL: Cancel requestThis SMB allows a client to cancel a request currently pending at the server. The client request is defined as: Client Request Description =============== ============ UCHAR WordCount; No words are sent (== 0) USHORT ByteCount; No bytes (==0) The Sid, Uid, Pid, Tid, and Mid fields of the SMB are used to locate an pending server request from this session. If a pending request is found, it is "hurried along" which may result in success or failure of the original request. No other response is generated for this SMB. 4.2 File Requests4.2.1 NT_CREATE_ANDX: Create or Open FileThis command is used to create or open a file or a directory. The client request is defined as: Client Request Description =============== ============ UCHAR WordCount; Count of parameter words = 24 UCHAR AndXCommand; Secondary command; 0xFF = None UCHAR AndXReserved; Reserved (must be 0) USHORT AndXOffset; Offset to next command WordCount UCHAR Reserved; Reserved (must be 0) USHORT NameLength; Length of Name[] in bytes ULONG Flags; Create bit set: 0x02 - Request an oplock 0x04 - Request a batch oplock 0x08 - Target of open must be directory ULONG RootDirectoryFid; If non-zero, open is relative to this directory ACCESS_MASK DesiredAccess; Access desired (See Section 3.8 for an explanation of this field) LARGE_INTEGER AllocationSize; Initial allocation size ULONG ExtFileAttributes; File attributes ULONG ShareAccess; Type of share access ULONG CreateDisposition; Action if file does/does not exist ULONG CreateOptions; Options to use if creating a file ULONG ImpersonationLevel; Security QOS information UCHAR SecurityFlags; Security tracking mode flags: 0x1 - SECURITY_CONTEXT_TRACKING 0x2 - SECURITY_EFFECTIVE_ONLY USHORT ByteCount; Length of byte parameters STRING Name[]; File to open or create The Name parameter contains the full path from the tree connect point unless the RootDirectoryFid is used. To use the RootDirectoryFid perform a NT_CREATE_ANDX to open the directory and then use the returned Fid for subsequent NT_CREATE_ANDX calls to open/create files within that directory. The DesiredAccess parameter is specified in section 3.8, Access Mask Encoding. If no value is specified, an application can still query attributes without actually accessing the file. The ExtFileAttributes parameter specifies the file attributes and flags for the file. The parameter's value is the sum of allowed attributes and flags defined in section 3.12, Extended File Attribute Encoding. The ShareAccess field specifies how the file can be shared. This parameter must be some combination of the following values:
The CreateDisposition parameter can contain one of the following values:
The ImpersonationLevel parameter can contain one or more of the following values:
The SecurityFlags parameter can have either of the following two flags set:
The server response to the NT_CREATE_ANDX request is as follows: Server Response Description ================ ============ UCHAR WordCount; Count of parameter words = 26 UCHAR AndXCommand; 0xFF = None UCHAR AndXReserved; MUST BE ZERO USHORT AndXOffset; Offset to next command WordCount UCHAR OplockLevel; The oplock level granted: 0 - No oplock granted 1 - Exclusive oplock granted 2 - Batch oplock granted 3 - Level II oplock granted USHORT Fid; The file ID ULONG CreateAction; The action taken TIME CreationTime; The time the file was created TIME LastAccessTime; The time the file was accessed TIME LastWriteTime; The time the file was last written TIME ChangeTime; The time the file was last changed ULONG ExtFileAttributes; The file attributes LARGE_INTEGER AllocationSize; The number of byes allocated LARGE_INTEGER EndOfFile; The end of file offset USHORT FileType; USHORT DeviceState; State of IPC device (e.g. pipe) BOOLEAN Directory; TRUE if this is a directory USHORT ByteCount; = 0 The following SMBs may follow SMB_COM_NT_CREATE_ANDX: SMB_COM_READ SMB_COM_READ_ANDX SMB_COM_IOCTL 4.2.1.1 ErrorsERRDOS codes ------------ ERRbadfile ERRbadpath ERRnofids ERRnoaccess ERRnomem ERRbadaccess ERRbadshare ERRfileexists ERRquota ERRSRV codes ------------ ERRaccess ERRinvdevice ERRinvtid ERRbaduid 4.2.2 NT_TRANSACT_CREATE: Create or Open File with EAs or SDThis command is used to create or open a file or a directory, when EAs or an SD must be applied to the file. The parameter and data blocks for the client's CREATE request include the following data: Request Parameter Block Encoding Description ================================= ============ ULONG Flags; Creation flags (see below) ULONG RootDirectoryFid; Optional directory for relative open ACCESS_MASK DesiredAccess; Access desired (See Section 3.8 for an explanation of this field) LARGE_INTEGER AllocationSize; The initial allocation size in bytes, if file created ULONG ExtFileAttributes; The extended file attributes ULONG ShareAccess; The share access ULONG CreateDisposition; Action if file does/does not exist ULONG CreateOptions; Options for creating a new file ULONG SecurityDescriptorLength; Length of SD in bytes ULONG EaLength; Length of EA in bytes ULONG NameLength; Length of name in characters ULONG ImpersonationLevel; Security QOS information UCHAR SecurityFlags; Security QOS information STRING Name[NameLength]; The name of the file (not NULL terminated) Request Data Block Encoding Description ============================ ============ UCHAR SecurityDescriptor[ SecurityDescriptorLength]; UCHAR ExtendedAttributes[EaLength]; The Flags parameter can contain one of the following values:
The parameter block of the server response is defined as: Response Parameter Block Encoding Description ================================== ============ UCHAR OplockLevel; The oplock level granted UCHAR Reserved; USHORT Fid; The file ID ULONG CreateAction; The action taken ULONG EaErrorOffset; Offset of the EA error TIME CreationTime; The time the file was created TIME LastAccessTime; The time the file was accessed TIME LastWriteTime; The time the file was last written TIME ChangeTime; The time the file was last changed ULONG ExtFileAttributes; The file attributes LARGE_INTEGER AllocationSize; The number of byes allocated LARGE_INTEGER EndOfFile; The end of file offset USHORT FileType; USHORT DeviceState; State of IPC device (e.g. pipe) BOOLEAN Directory; TRUE if this is a directory See the description of NT_CREATE_ANDX (section 4.2.1) for further definition of the CREATE request/response parameters. 4.2.2.1 ErrorsERRDOS codes ------------ ERRbadfile ERRbadpath ERRnofids ERRnoaccess ERRnomem ERRbadaccess ERRbadshare ERRfileexists ERRquota ERRSRV codes ------------ ERRaccess ERRinvdevice ERRinvtid ERRbaduid 4.2.3 CREATE_TEMPORARY: Create Temporary FileThe server creates a data file in the specified Directory, relative to Tid in the SMB header, and assigns a unique name to it. The client request and server response for the command are: Client Request Description =============== ============ UCHAR WordCount; Count of parameter words = 3 USHORT reserved; Ignored by the server UTIME CreationTime; New file's creation time stamp USHORT ByteCount; Count of data bytes; min = 2 UCHAR BufferFormat; 0x04 STRING DirectoryName[]; Directory name Server Response Description ================ ============ UCHAR WordCount; Count of parameter words = 1 USHORT Fid; File handle USHORT ByteCount; Count of data bytes; min = 2 UCHAR BufferFormat; 0x04 STRING Filename[]; File name Fid is the returned handle for future file access. Filename is the name of the file that was created within the requested Directory. It is opened in compatibility mode with read/write access for the client. Support of CreationTime by the server is optional. 4.2.3.1 ErrorsERRDOS codes ------------ ERRbadfile ERRbadpath ERRnofids ERRnoaccess ERRnomem ERRbadaccess ERRbadshare ERRfileexists ERRquota ERRSRV codes ------------ ERRaccess ERRinvdevice ERRinvtid ERRbaduid 4.2.4 READ_ANDX: Read BytesClient requests a file read, using the SMB fields specified below: Client Request Description =============== ============ UCHAR WordCount; Count of parameter words = 10 or 12 UCHAR AndXCommand; Secondary (X) command; 0xFF = none UCHAR AndXReserved; Reserved (must be 0) USHORT AndXOffset; Offset to next command WordCount USHORT Fid; File handle ULONG Offset; Offset in file to begin read USHORT MaxCount; Max number of bytes to return USHORT MinCount; Reserved for obsolescent requests ULONG MaxCountHigh; High 16 bits of MaxCount if CAP_LARGE_READX; else MUST BE ZERO USHORT Remaining; Reserved for obsolescent requests ULONG OffsetHigh; Upper 32 bits of offset (only if WordCount is 12) USHORT ByteCount; Count of data bytes = 0 And, the server response is: Server Response Description ================ ============ UCHAR WordCount; Count of parameter words = 12 UCHAR AndXCommand; Secondary (X) command; 0xFF = none UCHAR AndXReserved; Reserved (must be 0) USHORT AndXOffset; Offset to next command WordCount USHORT Remaining; Reserved -- must be -1 USHORT DataCompactionMode; USHORT Reserved; Reserved (must be 0) USHORT DataLength; Number of data bytes (min = 0) USHORT DataOffset; Offset (from header start) to data USHORT DataLengthHigh; High 16 bits of number of data bytes if CAP_LARGE_READX; else MUST BE ZERO USHORT Reserved[4]; Reserved (must be 0) USHORT ByteCount; Count of data bytes; ignored if CAP_LARGE_READX UCHAR Pad[]; UCHAR Data[DataLength]; Data from resource If the file specified by Fid has any portion of the range specified by Offset and MaxCount locked for exclusive use by a client with a different connection or Pid, the request will fail with ERRlock. If the negotiated dialect is NT LM 0.12 or later, the client may use the 12 parameter word version of the request. This version allows specification of 64 bit file offsets. If CAP_LARGE_READX was indicated by the server in the negotiate protocol response, the request's MaxCount field may exceed the negotiated buffer size if Fid refers to a disk file. The server may arbitrarily elect to return fewer than MaxCount bytes in response. The SMB server MAY use the MinCount on named-pipe calls to determine if this is a blocking read or a non-blocking read. (Non blocking is determined by MinCount = 0). Note that for blocking reads, the length required to succeed is actually the ReadLength and not the MinCount. (So in some sense, MinCount has become more of an indicator of blocking vs. non-blocking rather than a true length) The following SMBs may follow SMB_COM_READ_ANDX: SMB_COM_CLOSE 4.2.4.1 ErrorsERRDOS/ERRnoaccess ERRDOS/ERRbadfid ERRDOS/ERRlock ERRDOS/ERRbadaccess ERRSRV/ERRinvid ERRSRV/ERRbaduid 4.2.5 WRITE_ANDX: Write Bytes to file or resourceClient requests a file write, using the SMB fields specified below: Client Request Description =============== ============ UCHAR WordCount; Count of parameter words = 12 or 14 UCHAR AndXCommand; Secondary (X) command; 0xFF = none UCHAR AndXReserved; Reserved (must be 0) USHORT AndXOffset; Offset to next command WordCount USHORT Fid; File handle ULONG Offset; Offset in file to begin write ULONG Reserved; Must be 0 USHORT WriteMode; Write mode bits: 0 - write through USHORT Remaining; Bytes remaining to satisfy request USHORT DataLengthHigh; High 16 bits of data length if CAP_LARGE_WRITEX; else MUST BE ZERO USHORT DataLength; Number of data bytes in buffer (>=0) USHORT DataOffset; Offset to data bytes ULONG OffsetHigh; Upper 32 bits of offset (only present if WordCount = 14) USHORT ByteCount; Count of data bytes; ignored if CAP_LARGE_WRITEX UCHAR Pad[]; Pad to SHORT or LONG UCHAR Data[DataLength]; Data to write And, the server response is: Server Response Description ================ ============ UCHAR WordCount; Count of parameter words = 6 UCHAR AndXCommand; Secondary (X) command; 0xFF = none UCHAR AndXReserved; Reserved (must be 0) USHORT AndXOffset; Offset to next command WordCount USHORT Count; Number of bytes written USHORT Remaining; Reserved ULONG Reserved; USHORT ByteCount; Count of data bytes = 0 If the file specified by Fid has any portion of the range specified by Offset and MaxCount locked for shared or exclusive use by a client with a different connection or Pid, the request will fail with ERRlock. A ByteCount of 0 does not truncate the file. Rather a zero length write merely transfers zero bytes of information to the file. A request such as SMB_COM_WRITE must be used to truncate the file. If WriteMode has bit0 set in the request and Fid refers to a disk file, the response is not sent from the server until the data is on stable storage. If the negotiated dialect is NT LM 0.12 or later, the 14 word format of this SMB may be used to access portions of files requiring offsets expressed as 64 bits. Otherwise, the OffsetHigh field must be omitted from the request. If CAP_LARGE_WRITEX was indicated by the server in the negotiate protocol response, the request's DataLength field may exceed the negotiated buffer size if Fid refers to a disk file. The following are the valid AndXCommand values for this SMB: SMB_COM_READ SMB_COM_READ_ANDX SMB_COM_LOCK_AND_READ SMB_COM_WRITE_ANDX SMB_COM_CLOSE 4.2.5.1 ErrorsERRDOS/ERRnoaccess ERRDOS/ERRbadfid ERRDOS/ERRlock ERRDOS/ERRbadaccess ERRSRV/ERRinvid ERRSRV/ERRbaduid 4.2.6 LOCKING_ANDX: Lock or Unlock Byte RangesSMB_COM_LOCKING_ANDX allows both locking and/or unlocking of file range(s). A description of the fields of the client request, and explanations for several of the fields are provided below. Client Request Description =============== ============ UCHAR WordCount; Count of parameter words = 8 UCHAR AndXCommand; Secondary (X) command; 0xFF = none UCHAR AndXReserved; Reserved (must be 0) USHORT AndXOffset; Offset to next command WordCount USHORT Fid; File handle UCHAR LockType; See LockType table below UCHAR OplockLevel; The new oplock level ULONG Timeout; Milliseconds to wait for unlock USHORT NumberOfUnlocks; Number of unlock range structures that follow USHORT NumberOfLocks; Number of lock range structures that follow USHORT ByteCount; Count of data bytes LOCKING_ANDX_RANGE Unlocks[]; Unlock ranges LOCKING_ANDX_RANGE Locks[]; Lock ranges The LockType parameter can take on one of the values in the following table:
The format for LOCKING_ANDX_RANGE is: USHORT Pid; PID of process "owning" lock ULONG Offset; Offset to bytes to [un]lock ULONG Length; Number of bytes to [un]lock And, for a large file, it is: USHORT Pid; PID of process "owning" lock USHORT Pad; Pad to DWORD align (Must be zero) ULONG OffsetHigh; Offset to bytes to [un]lock (high) ULONG OffsetLow; Offset to bytes to [un]lock (low) ULONG LengthHigh; Number of bytes to [un]lock (high) ULONG LengthLow; Number of bytes to [un]lock (low) The server response is: Server Response Description ================ ============ UCHAR WordCount; Count of parameter words = 2 UCHAR AndXCommand; Secondary (X) command; 0xFF = none UCHAR AndXReserved; Reserved (must be 0) USHORT AndXOffset; Offset to next command WordCount USHORT ByteCount; Count of data bytes = 0 Locking is a simple mechanism for excluding other processes read/write access to regions of a file. The locked regions can be anywhere in the logical file. Locking beyond end-of-file is permitted. Lock conflicts (overlapping lock-requests) should cause the server to refuse the lock to the latter requestor . Any process using the Fid specified in this request's Fid has access to the locked bytes; other processes will be denied the locking of the same bytes. The proper method for using locks is not to rely on being denied read or write access on any of the read/write protocols but rather to attempt the locking protocol and proceed with the read/write only if the locks succeeded. Locking a range of bytes will fail if any subranges or overlapping ranges are locked, if the PID/UID of the requestor is not the same, and the locks are not compatible. In other words, if any of the specified bytes are already locked, the lock will fail. If NumberOfUnlocks is non-zero, the Unlocks vector contains NumberOfUnlocks elements. Each element requests that a lock at Offset of Length be released. If NumberOfLocks is nonzero, the Locks vector contains NumberOfLocks elements. Each element requests the acquisition of a lock at Offset of Length. Timeout is the maximum amount of time to wait for the byte range(s) specified to become unlocked. A timeout value of 0 indicates that the server should fail immediately if any lock range specified is locked. A timeout value of -1 indicates that the server should wait as long as it takes for each byte range specified to become unlocked so that it may be again locked by this protocol. Any other value of smb_timeout specifies the maximum number of milliseconds to wait for all lock range(s) specified to become available. If any of the lock ranges timeout because of the area to be locked is already locked (or the lock fails), the other ranges in the protocol request which were successfully locked as a result of this protocol will be unlocked (either all requested ranges will be locked when this protocol returns to the client or none). If LockType has the LOCKING_ANDX_SHARED_LOCK flag set, the lock is specified as a shared lock. Locks for both read and write (where LOCKING_ANDX_SHARED_LOCK is clear) should be prohibited , but other shared locks should be permitted. If shared locks can not be supported by a server, the server should map the lock to a lock for both read and write. Closing a file with locks still in force causes the locks to be released in no defined order. If LockType has the LOCKING_ANDX_LARGE_FILES flag set and if the negotiated protocol is NT LM 0.12 or later, then the Locks and Unlocks vectors are in the Large File LOCKING_ANDX_RANGE format. This allows specification of 64 bit offsets for very large files. If the one and only member of the Locks vector has the LOCKING_ANDX_CANCEL_LOCK flag set in the LockType field, the client is requesting the server to cancel a previously requested, but not yet responded to, lock. If LockType has the LOCKING_ANDX_CHANGE_LOCKTYPE flag set, the client is requesting that the server atomically change the lock type from a shared lock to an exclusive lock or vice versa. If the server can not do this in an atomic fashion, the server must reject this request. (Note: Windows NT and Windows 95 servers do not support this capability.) If the client sends an SMB_LOCKING_ANDX SMB with the LOCKING_ANDX_OPLOCK_RELEASE flag set and NumberOfLocks is zero, the server does not send a response. The entire message sent and received including the optional second protocol must fit in the negotiated maximum transfer size. The following are the only valid SMB commands for AndXCommand for SMB_COM_LOCKING_ANDX: SMB_COM_READ SMB_COM_READ_ANDX SMB_COM_WRITE SMB_COM_WRITE_ANDX SMB_COM_FLUSH 4.2.6.1 ErrorsERRDOS/ERRbadfile ERRDOS/ERRbadfid ERRDOS/ERRlock ERRDOS/ERRinvdevice ERRSRV/ERRinvid ERRSRV/ERRbaduid 4.2.7 SEEK: Seek in FileThe seek message is sent to set the current file pointer for Fid . Client Request Description =============== ================================= UCHAR WordCount; Count of parameter words = 4 USHORT Fid; File handle USHORT Mode; Seek mode: 0 = from start of file 1 = from current position 2 = from end of file LONG Offset; Relative offset USHORT ByteCount; Count of data bytes = 0 The "current position" reflects the offset plus data length specified in the previous read, write, or seek request; and the pointer set by this command will be replaced by the offset specified in the next read, write, or seek command. Server Response Description ================ ============ UCHAR WordCount; Count of parameter words = 2 ULONG Offset; Offset from start of file USHORT ByteCount; Count of data bytes = 0 The response returns the new file pointer in Offset , which is expressed as the offset from the start of the file, and may be beyond the current end of file. An attempt to seek to before the start of file sets the current file pointer to start of the file. This request should generally be issued only by clients wishing to find the size of a file, because all read and write requests include the read or write file position as part of the SMB. This request is inappropriate for very large files, as the offsets specified are only 32 bits. A seek that results in an Offset that cannot be expressed in 32 bits returns the least significant. 4.2.7.1 ErrorsERRDOS/ERRbadfid ERRDOS/ERRnoaccess ERRSRV/ERRinvdevice ERRSRV/ERRinvid ERRSRV/ERRbaduid 4.2.8 FLUSH: Flush FileThe flush SMB is sent to ensure all data and allocation information for the corresponding file has been written to stable storage. When the Fid has a value -1 (hex FFFF), the server performs a flush for all file handles associated with the client and Pid. The response is not sent until the writes are complete. Client Request Description =============== ================================= UCHAR WordCount; Count of parameter words = 1 USHORT Fid; File handle USHORT ByteCount; Count of data bytes = 0 This client request is probably expensive to perform at the server, since the server's operating system is generally scheduling disk writes is a way which is optimal for the system's read and write activity integrated over the entire population of clients. This message from a client "interferes" with the server's ability to optimally schedule the disk activity; clients are discouraged from overuse of this SMB request. Server Response Description ================ ============ UCHAR WordCount; Count of parameter words = 0 USHORT ByteCount; Count of data bytes = 0 4.2.8.1 ErrorsERRDOS/ERRbadfid ERRSRV/ERRinvid ERRSRV/ERRbaduid 4.2.9 CLOSE: Close FileThe close message is sent to invalidate a file handle for the requesting process. All locks or other resources held by the requesting process on the file should be released by the server. The requesting process can no longer use Fid for further file access requests. Client Request Description =============== ============ UCHAR WordCount; Count of parameter words = 3 USHORT Fid; File handle UTIME LastWriteTime; Time of last write USHORT ByteCount; Count of data bytes = 0 If LastWriteTime is 0, the server should allow its local operating system to set the file's times. Otherwise, the server should set the time to the values requested. Failure to set the times, even if requested by the client in the request message, should not result in an error response from the server. If Fid refers to a print spool file, the file should be spooled to the printer at this time. Server Response Description ================ ============ UCHAR WordCount; Count of parameter words = 0 USHORT ByteCount; Count of data bytes = 0 4.2.9.1 ErrorsERRDOS/ERRbadfid ERRSRV/ERRinvdevice ERRSRV/ERRinvid ERRSRV/ERRbaduid 4.2.10 CLOSE_AND_TREE_DISCONNECTClose the file and perform a tree disconnect. The close and tree disconnect message is sent to close a file and perform a tree disconnect. All locks or other resources held by the requesting process on the file should be released by the server. The requesting process can no longer use Fid for further file access requests. The server will perform a TREE_DISCONNECT after completing the close operation. The requesting process can no longer use Tid for further access requests. Client Request Description =============== ============ UCHAR WordCount; Count of parameter words = 3 USHORT Fid; File handle UTIME LastWriteTime; Time of last write USHORT ByteCount; Count of data bytes = 0 If LastWriteTime is 0, the server should allow its local operating system to set the file's times. Otherwise, the server should set the time to the values requested. Failure to set the times, even if requested by the client in the request message, should not result in an error response from the server. If Fid refers to a print spool file, the file should be spooled to the printer at this time. Server Response Description ================ ============ UCHAR WordCount; Count of parameter words = 0 USHORT ByteCount; Count of data bytes = 0 4.2.10.1 ErrorsERRDOS/ERRbadfid ERRSRV/ERRinvdevice ERRSRV/ERRinvid ERRSRV/ERRbaduid 4.2.11 DELETE: Delete FileThe delete file message is sent to delete a data file. The appropriate Tid and additional pathname are passed. Read only files may not be deleted, the read-only attribute must be reset prior to file deletion. Client Request Description =============== ============ UCHAR WordCount; Count of parameter words = 1 USHORT SearchAttributes; USHORT ByteCount; Count of data bytes; min = 2 UCHAR BufferFormat; 0x04 STRING FileName[]; File name Multiple files may be deleted in response to a single request as SMB_COM_DELETE supports wildcards. SearchAttributes indicates the attributes that the target file(s) must have. If the attribute is zero then only normal files are deleted. If the system file or hidden attributes are specified, then the delete is inclusive - both the specified type(s) of files and normal files are deleted. File attributes are described in the "Attribute Encoding" section (3.11) of this document. If bit0 of the Flags2 field of the SMB header is set, a pattern is passed in, and the file has a long name, then the passed pattern must match the long file name for the delete to succeed. If bit0 is clear, a pattern is passed in, and the file has a long name, then the passed pattern must match the file's short name for the deletion to succeed. Server Response Description ================ ============ UCHAR WordCount; Count of parameter words = 0 USHORT ByteCount; Count of data bytes = 0 4.2.11.1 ErrorsERRDOS/ERRbadpath ERRDOS/ERRbadfile ERRDOS/ERRnoaccess ERRHRD/ERRnowrite ERRSRV/ERRaccess ERRSRV/ERRinvdevice ERRSRV/ERRinvid ERRSRV/ERRbaduid 4.2.12 RENAME: Rename FileThe rename file message is sent to change the name of a file. Client Request Description =============== ============ UCHAR WordCount; Count of parameter words = 1 USHORT SearchAttributes; Target file attributes USHORT ByteCount; Count of data bytes; min = 4 UCHAR BufferFormat1; 0x04 STRING OldFileName[]; Old file name UCHAR BufferFormat2; 0x04 STRING NewFileName[]; New file name The file, OldFileName, must exist and NewFileName must not. Both pathnames must be relative to the Tid specified in the request. Open files may be renamed . Multiple files may be renamed in response to a single request as Rename File supports wildcards in the file name (last component of the pathname). SearchAttributes indicates the attributes that the target file(s) must have. If SearchAttributes is zero then only normal files are renamed. If the system file or hidden attributes are specified then the rename is inclusive - both the specified type(s) of files and normal files are renamed. The encoding of SearchAttributes is described in section 3.11 - File Attribute Encoding. Server Response Description ================ ============ UCHAR WordCount; Count of parameter words = 0 USHORT ByteCount; Count of data bytes = 0 4.2.12.1 ErrorsERRDOS/ERRbadpath ERRDOS/ERRbadfile ERRDOS/ERRnoaccess ERRDOS/ERRdiffdevice ERRHRD/ERRnowrite ERRSRV/ERRaccess ERRSRV/ERRinvdevice ERRSRV/ERRinvid ERRSRV/ERRbaduid 4.2.13 NT_RENAME:The rename file message is sent to change the name of a file. This version of RENAME supports NT link tracking info. Client Request Description =============== ============ UCHAR WordCount; Count of parameter words = 4 USHORT SearchAttributes; USHORT Information Level; ULONG ClusterCount; USHORT ByteCount; Count of data bytes; min = 4 UCHAR Buffer[1]; Buffer containing: UCHAR BufferFormat1 0x04 -- ASCII UCHAR OldFileName[] Old file name UCHAR BufferFormat2 0x04 -- ASCII UCHAR NewFileName[] New file name Server Response Description ================ ============ UCHAR WordCount; Count of parameter words = 0 USHORT ByteCount; Count of data bytes = 0 UCHAR Buffer[1]; empty Non-NT machines can ignore the extra parameters (InfoLevel, SearchAttributes, ClusterCount) and just perform a normal rename. 4.2.13.1 ErrorsERRDOS codes ------------ ERRbadfile ERRbadpath ERRnofids ERRnoaccess ERRnomem ERRfileexists ERRSRV codes ------------ ERRaccess ERRinvdevice ERRinvtid ERRbaduid 4.2.14 MOVE: Rename FileThe source file is copied to the destination and the source is subsequently deleted. Client Request Description =============== ============ UCHAR WordCount; Count of parameter words = 3 USHORT Tid2; Second (target) file id USHORT OpenFunction; What to do if target file exists USHORT Flags; Flags to control move operations: 0 - target must be a file 1 - target must be a directory 2 - reserved (must be 0) 3 - reserved (must be 0) 4 - verify all writes USHORT ByteCount; Count of data bytes; min = 2 UCHAR Format1; 0x04 STRING OldFileName[]; Old file name UCHAR FormatNew; 0x04 STRING NewFileName[]; New file name OldFileName is copied to NewFileName, then OldFileName is deleted. Both OldFileName and NewFileName must refer to paths on the same server. NewFileName can refer to either a file or a directory. All file components except the last must exist; directories will not be created. NewFileName can be required to be a file or a directory by the Flags field. The Tid in the header is associated with the source while Tid2 is associated with the destination. These fields may contain the same or differing valid values. Tid2 can be set to -1 indicating that this is to be the same Tid as in the SMB header. This allows use of the move protocol with SMB_TREE_CONNECT_ANDX. Server Response Description ================ ============ UCHAR WordCount; Count of parameter words = 1 USHORT Count; Number of files moved USHORT ByteCount; Count of data bytes; min = 0 UCHAR ErrorFileFormat; 0x04 (only if error) STRING ErrorFileName[]; Pathname of file where error Occurred The source path must refer to an existing file or files. Wildcards are permitted. Source files specified by wildcards are processed until an error is encountered. If an error is encountered , the expanded name of the file is returned in ErrorFileName. Wildcards are not permitted in NewFileName. OpenFunction controls what should happen if the destination file exists. If (OpenFunction & 0x30) == 0, the operation should fail if the destination exists. If (OpenFunction & 0x30) == 0x20, the destination file should be overwritten. 4.2.14.1 ErrorsERRDOS/ERRfilexists ERRDOS/ERRbadfile ERRDOS/ERRnoaccess ERRDOS/ERRnofiles ERRDOS/ERRbadshare ERRHRD/ERRnowrite ERRSRV/ERRnoaccess ERRSRV/ERRinvdevice ERRSRV/ERRinvid ERRSRV/ERRbaduid ERRSRV/ERRnosupport ERRSRV/ERRaccess 4.2.15 COPY: Copy FileThe source file is copied to the target. Client Request Description =============== ============ UCHAR WordCount; Count of parameter words = 3 USHORT Tid2; Second (target) path TID USHORT OpenFunction; What to do if target file exists USHORT Flags; Flags to control copy operation: bit 0 - target must be a file bit 1 - target must be a dir. bit 2 - copy target mode: 0 = binary, 1 = ASCII bit 3 - copy source mode: 0 = binary, 1 = ASCII bit 4 - verify all writes bit 5 - tree copy USHORT ByteCount; Count of data bytes; min = 2 UCHAR SourceFileNameFormat; 0x04 STRING SourceFileName; Pathname of source file UCHAR TargetFileNameFormat; 0x04 STRING TargetFileName; Pathname of target file The file at SourceName is copied to TargetFileName, both of which must refer to paths on the same server. The Tid in the header is associated with the source while Tid2 is associated with the destination. These fields may contain the same or differing valid values. Tid2 can be set to -1 indicating that this is to be the same Tid as in the SMB header. This allows use of the move protocol with SMB_TREE_CONNECT_ANDX. Server Response Description ================ ============ UCHAR WordCount; Count of parameter words = 1 USHORT Count; Number of files copied USHORT ByteCount; Count of data bytes; min = 0 UCHAR ErrorFileFormat; 0x04 (only if error) STRING ErrorFileName; The source path must refer to an existing file or files. Wildcards are permitted. Source files specified by wildcards are processed until an error is encountered. If an error is encountered, the expanded name of the file is returned in ErrorFileName. Wildcards are not permitted in TargetFileName. TargetFileName can refer to either a file or a directory. The destination can be required to be a file or a directory by the bits in Flags. If neither bit0 nor bit1 are set, the destination may be either a file or a directory. The Flags field also controls the copy mode. In a binary copy for the source, the copy stops the first time an EOF (control-Z) is encountered. In a binary copy for the target, the server must make sure that there is exactly one EOF in the target file and that it is the last character of the file. If the destination is a file and the source contains wildcards, the destination file will either be truncated or appended to at the start of the operation depending on bits in OpenFunction (see section 3.7). Subsequent files will then be appended to the file. If the negotiated dialect is LM1.2X002 or later, bit5 of Flags is used to specify a tree copy on the remote server. When this option is selected the destination must not be an existing file and the source mode must be binary. A request with bit5 set and either bit0 or bit3 set is therefore an error. When the tree copy mode is selected, the Count field in the server response is undefined. 4.2.15.1 ErrorsERRDOS/ERRfilexists ERRDOS/ERRshare ERRDOS/ERRnofids ERRDOS/ERRbadfile ERRDOS/ERRnoaccess ERRDOS/ERRnofiles ERRDOS/ERRbadshare ERRSRV/ERRnoaccess ERRSRV/ERRinvdevice ERRSRV/ERRinvid ERRSRV/ERRbaduid ERRSRV/ERRaccess 4.2.16 TRANS2_QUERY_PATH_INFORMATION: Get File Attributes Given PathThis request is used to get information about a specific file or subdirectory. Client Request Value =============== ====== WordCount 15 MaxSetupCount 0 SetupCount 1 Setup[0] TRANS2_QUERY_PATH_INFORMATION The request's parameter block uses the following format: Parameter Block Encoding Description ========================= ============ USHORT InformationLevel; Level of information requested ULONG Reserved; Must be zero STRING FileName; File or directory name InformationLevels are specified using these values:
The requested information is placed in the Data portion of the transaction response. For the information levels greater than 0x100, the transaction response has 1 parameter word which should be ignored by the client. The following sections describe the InformationLevel dependent encoding of the data part of the transaction response. 4.2.16.1 SMB_INFO_STANDARD & SMB_INFO_QUERY_EA_SIZEData Block Encoding Description ==================== ============ SMB_DATE CreationDate; Date when file was created SMB_TIME CreationTime; Time when file was created SMB_DATE LastAccessDate; Date of last file access SMB_TIME LastAccessTime; Time of last file access SMB_DATE LastWriteDate; Date of last write to the file SMB_TIME LastWriteTime; Time of last write to the file ULONG DataSize; File Size ULONG AllocationSize; Size of filesystem allocation unit USHORT Attributes; File Attributes ULONG EaSize; Size of file's EA information (SMB_INFO_QUERY_EA_SIZE) 4.2.16.2 SMB_INFO_QUERY_EAS_FROM_LIST & SMB_INFO_QUERY_ALL_EASResponse Field Value =============== ====== MaxDataCount Length of EAlist found (minimum value is 4) Parameter Block Encoding Description ================ ============ USHORT EaErrorOffset; Offset into EAList of EA error Data Block Encoding Description ==================== ============ ULONG ListLength; Length of the remaining data UCHAR EaList[]; The extended attributes list 4.2.16.3 SMB_INFO_IS_NAME_VALIDThis requests checks to see if the name of the file contained in the request's Data field has a valid path syntax. No parameters or data are returned on this information request. An error is returned if the syntax of the name is incorrect. Success indicates the server accepts the path syntax, but it does not ensure the file or directory actually exists. 4.2.16.4 SMB_QUERY_FILE_BASIC_INFOData Block Encoding Description ==================== ============ TIME CreationTime; Time when file was created TIME LastAccessTime; Time of last file access TIME LastWriteTime; Time of last write to the file TIME ChangeTime; Time when file was last changed ULONG Attributes; File Attributes ULONG Pad; Undefined The valid file attributes are:
4.2.16.5 SMB_QUERY_FILE_STANDARD_INFOData Block Encoding Description ==================== ============ LARGE_INTEGER AllocationSize; Allocated size of the file in number of bytes LARGE_INTEGER EndOfFile; Offset to the first free byte in the file ULONG NumberOfLinks; Number of hard links to the file BOOLEAN DeletePending; Indicates whether the file is marked for deletion BOOLEAN Directory; Indicates whether the file is a Directory 4.2.16.6 SMB_QUERY_FILE_EA_INFOData Block Encoding Description ==================== ============ ULONG EASize; Size of the file's extended attributes in number of bytes 4.2.16.7 SMB_QUERY_FILE_NAME_INFOData Block Encoding Description ==================== ============ ULONG FileNameLength; Length of the file name in number of bytes STRING FileName; Name of the file NOTE: Do not include the path to the file. 4.2.16.8 SMB_QUERY_FILE_ALL_INFOData Block Encoding Description ==================== ============ TIME CreationTime; Time when file was created TIME LastAccessTime; Time of last file access TIME LastWriteTime; Time of last write to the file TIME ChangeTime; Time when file was last changed USHORT Attributes; File Attributes LARGE_INTEGER AllocationSize; Allocated size of the file in number of bytes LARGE_INTEGER EndOfFile; Offset to the first free byte in the file ULONG NumberOfLinks; Number of hard links to the file BOOLEAN DeletePending; Indicates whether the file is marked for deletion BOOLEAN Directory; Indicates whether the file is a directory LARGE_INTEGER IndexNumber; A file system unique identifier ULONG EASize; Size of the file's extended attributes in number of bytes ULONG AccessFlags; Access that a caller has to the file; Possible values and meanings are specified below LARGE_INTEGER IndexNumber1; A file system unique identifier LARGE_INTEGER Current byte offset within the file CurrentByteOffset; ULONG Mode; Current Open mode of the file handle to the file; possible values and meanings are detailed below ULONG AlignmentRequirement; Buffer Alignment required by device; possible values detailed below ULONG FileNameLength; Length of the file name in number of bytes STRING FileName; Name of the file The AccessFlags specifies the access permissions a caller has to the file. It can have any suitable combination of the following values:
The Mode field specifies the mode in which the file is currently opened. The possible values may be a suitable and logical combination of the following:
The AlignmentRequirement field specifies buffer alignment required by the device and can have any one of the following values:
Extended attributes are used primarily by OS/2 Network Clients since OS/2 1.2a, but are an optional feature (I.e., filesystems and network servers are not required to support it). Extended attributes provided alternate data streams that are most commonly used by OS/2 client programs for the following purposes:
Supporting extended attributes is not mandatory in order to support OS/2 clients or to support the vast majority of OS/2 programs. Note that Windows NT Workstations can generate extended attribute request when requested by older programs (such as OS/2) and Windows NT servers do support requests to get or set extended attributes. Windows NT programs with needs to store "extended" attribute information, now largely use the capability to associate data streams with files that was introduced in NT 4. In both cases, the general concept is similar to the data fork concept introduced by the Macintosh filesystem. Extended Attributes have been used for Macintosh compatibility in the past (to emulate data forks). 4.2.16.9 SMB_QUERY_FILE_ALT_NAME_INFORetrieves the 8.3 form of the file name, given the long name specified in the data block encoding. Data Block Encoding Description ==================== ============ ULONG FileNameLength; Length of the file name in number of bytes STRING FileName; Name of the file 4.2.16.10 SMB_QUERY_FILE_STREAM_INFOData Block Encoding Description ==================== ============ ULONG NextEntryOffset; Offset to the next entry (in bytes) ULONG StreamNameLength; Length of the stream name in number of bytes LARGE_INTEGER StreamSize; Size of the stream in number of bytes LARGE_INTEGER Allocated size of the stream in StreamAllocationSize; number of bytes STRING FileName; Name of the stream NOTE: When more than one data block is returned, the NextEntryOffset is the offset to the next entry and is 0 for the last entry. STATUS_INVALID_PARAMETER is returned if file streams are not supported. 4.2.16.11 SMB_QUERY_FILE_COMPRESSION_INFOData Block Encoding Description ==================== ============ LARGE_INTEGER Size of the compressed file in CompressedFileSize; number of bytes USHORT CompressionFormat; A constant signifying the compression algorithm used. Possible values are: 0 - There is no compression 2- Compression Format is LZNT UCHAR CompressionUnitShift; UCHAR ChunkShift; Stored in log2 format (1 << ChunkShift = ChunkSizeInBytes) UCHAR ClusterShift; Indicates how much space must be saved to successfully compress a compression unit UCHAR Reserved[3]; 4.2.16.12 SMB_QUERY_FILE_UNIX_BASICUsed to retrieve UNIX specific file information Data Block Encoding Description ==================== ============ LARGE_INTEGER EndOfFile; File size LARGE_INTEGER NumOfBytes Number of file system bytes used to store file TIME LastStatusChange; Last time the status of the file was changed. This is in DCE time. TIME LastAccessTime; Time of last file access. This is DCE time. TIME LastModificationTime; Last modification time. This is DCE time. LARGE_INTEGER Uid; Numeric user id for the owner LARGE_INTEGER Gid; Numeric group id of owner ULONG Type; Enumeration specifying the file type. 0 -- File 1 -- Directory 2 -- Symbolic Link 3 -- Character device 4 -- Block device 5 -- FIFO 6 -- Socket LARGE_INTEGER DevMajor; Major device number if file type is device. LARGE_INTEGER DevMinor; Minor device number if file type is device. LARGE_INTEGER UniqueId; This is a server-assigned unique id for the file. The client will typically map this onto an inode number. The scope of uniqueness is the share. LARGE_INTEGER Permissions; Standard UNIX file permissions LARGE_INTEGER Nlinks; The number of directory entries that map to this entry or number of hard links. 4.2.16.13 SMB_QUERY_FILE_UNIX_LINKUsed to retrieve destination file of a symbolic link Data Block Encoding Description ==================== ============ STRING LinkDest; Destination for symbolic link 4.2.16.14 SMB_MAC_DT_GET_APPLThe Macintosh needs to be able to get an application name and its creator from a database. The Client sends a Trans2_Query_Path_Information call in which the name field is just ignored. The Client will send an info level that represents getting an application name with a structure that contains the File Creator and index. Where index has the following meaning.
4.2.16.15 SMB_MAC_DT_GET_ICONThe Macintosh needs to be able to get an icon from a database. The Client sends a Trans2_Query_Path_Information call in which the path name is ignored. The Client will send an info level that represents getting an icon with a structure that contains the Requested size of the icon, the Icon type, File Creator, and File Type. The Server returns with a structure that contains the actual size of the icon (must be less than requested length) and the icon bit map.
4.2.16.16 SMB_MAC_DT_GET_ICON_INFOThe Macintosh needs to be able to get an icon from a database. The Client sends a Trans2_Query_Path_Information call in which the path name is ignored. The Client will send an info level that represents getting an icon with a structure that contains the index and File Creator. The index allows the client to make repeated calls to the server gathering all icon stored by this file creator. The Server returns with a structure that contains the actual size of the icon (must be less than requested length) and the icon bit map, File Type, and Icon Type.
4.2.16.17 ErrorsERRDOS codes ------------ ERRbadfile ERRbadpath ERRnoaccess ERRnomem ERRSRV codes ------------ ERRaccess ERRinvdevice ERRinvtid ERRbaduid 4.2.17 TRANS2_QUERY_FILE_INFORMATION: Get File Attributes Given FIDThis request is used to get information about a specific file or subdirectory given a handle to it. Client Request Value =============== ====== WordCount 15 MaxSetupCount 0 SetupCount 1 Setup[0] TRANS2_QUERY_FILE_INFORMATION Parameter Block Encoding Description ========================= ============ USHORT Fid; Handle of file for request USHORT InformationLevel; Level of information requested The available information levels, as well as the format of the response are identical to TRANS2_QUERY_PATH_INFORMATION. 4.2.18 TRANS2_SET_PATH_INFORMATION: Set File Attributes given PathThis request is used to set information about a specific file or subdirectory. Client Request Value =============== ====== WordCount 15 MaxSetupCount 0 SetupCount 1 Setup[0] TRANS2_SET_PATH_INFORMATION Parameter Block Encoding Description ========================= ============ USHORT InformationLevel; Level of information to set ULONG Reserved; Must be zero STRING FileName; File or directory name The following Information Levels may be set:
The response formats are: 4.2.18.1 SMB_INFO_STANDARD & SMB_INFO_QUERY_EA_SIZEParameter Block Encoding Description ========================= ============ USHORT Reserved 0 Data Block Encoding Description ==================== ============ SMB_DATE CreationDate; Date when file was created SMB_TIME CreationTime; Time when file was created SMB_DATE LastAccessDate; Date of last file access SMB_TIME LastAccessTime; Time of last file access SMB_DATE LastWriteDate; Date of last write to the file SMB_TIME LastWriteTime; Time of last write to the file ULONG DataSize; File Size ULONG AllocationSize; Size of filesystem allocation unit USHORT Attributes; File Attributes ULONG EaSize; Size of file's EA information (SMB_INFO_QUERY_EA_SIZE) 4.2.18.2 SMB_INFO_QUERY_ALL_EASResponse Field Value =============== ====== MaxDataCount Length of FEAlist found (minimum value is 4) Parameter Block Encoding Description ========================= ============ USHORT EaErrorOffset; Offset into EAList of EA error Data Block Encoding Description ==================== ============ ULONG ListLength; Length of the remaining data UCHAR EaList[]; The extended attributes list 4.2.18.3 SMB_SET_FILE_UNIX_BASICUsed to set UNIX specific file attributes and create files Data Block Encoding Description ==================== ============ LARGE_INTEGER EndOfFile; File size LARGE_INTEGER NumOfBytes; Number of file system bytes used to store file TIME LastStatusChange; Last time the status of the file was changed. This is in DCE time. TIME LastAccessTime; Time of last file access. This is DCE time. TIME LastModificationTime; Last modification time. This is DCE time. LARGE_INTEGER Uid; Numeric user id for the owner LARGE_INTEGER Gid; Numeric group id of owner ULONG Type; Enumeration specifying the file type. 0 -- File 1 -- Directory 2 -- Symbolic Link 3 -- Character device 4 -- Block device 5 -- FIFO 6 -- Socket LARGE_INTEGER DevMajor; Major device number if file type is device LARGE_INTEGER DevMinor; Minor device number if file type is device LARGE_INTEGER UniqueId; This is a server-assigned unique id for the file. The client will typically map this onto an inode number. The scop of uniqueness is the share LARGE_INTEGER Permissions; Standard UNIX file permissions LARGE_INTEGER Nlinks; The number of directory entries that map to this entry or number of hard links 4.2.18.4 SMB_SET_FILE_UNIX_LINKUsed to create symbolic link file. Data Block Encoding Description ==================== ============ STRING LinkDest; Destination for symbolic link 4.2.18.5 SMB_SET_FILE_UNIX_HLINKUsed to create hard link file. Data Block Encoding Description ==================== ============ STRING LinkDest; Destination for hard link 4.2.18.6 SMB_MAC_SET_FINDER_INFO
Listed below are the types of actions that the client may request with this Information Level:
4.2.18.7 SMB_MAC_DT_ADD_APPLThe Macintosh needs to be able to store an application name and its creator in a database. The Client sends a Trans2_Set_Path_Information call with the full path of the application in the path field. The Client sends an info level that represents adding an application name and creator to the database. The Client will pass the File Creator in the data message. The Server should just respond with no error if it was successful or an error if the operation failed
4.2.18.8 SMB_MAC_DT_REMOVE_APPLThe Macintosh needs to be able to remove an application name and its creator from a database. The Client sends a Trans2_Set_Path_Information call with the full path of the application in the path field. The Client will send an info level that represents removing an application name and creator from the database. The Client will pass the File Creator in the data message. The Server should just respond with no error if it was successful or an error it the operation failed.
4.2.18.9 SMB_MAC_DT_ADD_ICONThe Macintosh needs to be able to add an icon to a database. The Client sends a Trans2_Set_Path_Information call in which the path name is ignored. The Client will send an info level that represents setting an icon with a structure that contains the icon data, icon size, icon type, the file type, and file creator. The Server returns only if the call was successful or not.
4.2.18.10 ErrorsERRDOS codes ------------ ERRbadfile ERRbadpath ERRnoaccess ERRnomem ERRbadaccess ERRbadshare ERRSRV codes ------------ ERRaccess ERRinvdevice ERRinvtid ERRbaduid 4.2.19 TRANS2_SET_FILE_INFORMATION: Set File Attributes Given FIDThis request is used to set information about a specific file or subdirectory given a handle to the file or subdirectory. Client Request Value =============== ====== WordCount 15 MaxSetupCount 0 SetupCount 1 Setup[0] TRANS2_SET_FILE_INFORMATION Parameter Block Encoding Description ========================= ============ USHORT Fid; Handle of file for request USHORT InformationLevel; Level of information requested USHORT Reserved; Ignored by the server The following InformationLevels may be set:
The two levels below 0x101 and the three levels 0x200, 0x201, and 0x202 are as described in the NT_SET_PATH_INFORMATION transaction. The requested information is placed in the Data portion of the transaction response. For the information levels greater than 0x100 and below 0x200, the transaction response has 1 parameter word, which should be ignored by the client. 4.2.19.1 SMB_FILE_BASIC_INFOData Block Encoding Description ==================== ============ TIME CreationTime; Time when file was created TIME LastAccessTime; Time of last file access TIME LastWriteTime; Time of last write to the file TIME ChangeTime; Time when file was last changed ULONG Attributes; File Attributes The valid file attributes are listed in section 4.2.16.4 SMB_QUERY_FILE_BASIC_INFO: 4.2.19.2 SMB_FILE_DISPOSITION_INFOResponse Field Value =============== ====== BOOLEAN A boolean which is TRUE if the file is marked FileIsDeleted; for deletion 4.2.19.3 SMB_FILE_ALLOCATION_INFOResponse Field Value =============== ====== LARGE_INTEGER File Allocation size in number of bytes 4.2.19.4 SMB_FILE_END_OF_FILE_INFOResponse Field Value =============== ====== LARGE_INTEGER The total number of bytes that need to be traversed from the beginning of the file in order to locate the end of the file 4.2.19.5 ErrorsERRDOS codes ------------ ERRbadfile ERRbadpath ERRnoaccess ERRnomem ERRbadaccess ERRbadshare ERRSRV codes ------------ ERRaccess ERRinvdevice ERRinvtid ERRbaduid 4.3 Directory Requests4.3.1 TRANS2_CREATE_DIRECTORY: Create Directory (with optional EAs)This requests the server to create a directory relative to Tid in the SMB header, optionally assigning extended attributes to it. Client Request Value =============== ====== WordCount 15 MaxSetupCount 0 SetupCount 1 Setup[0] TRANS2_CREATE_DIRECTORY Parameter Block Encoding Description ========================= ============ ULONG Reserved; Reserved--must be zero STRING Name[]; Directory name to create UCHAR Data[]; Optional FEAList for the new directory Response Parameter Block Description ========================= ============ USHORT EaErrorOffset Offset into FEAList of first error which occurred while setting Eas 4.3.1.1 ErrorsERRDOS codes ------------ ERRbadfile ERRbadpath ERRnoaccess ERRnomem ERRbadaccess ERRfileexists ERRquota ERRSRV codes ------------ ERRaccess ERRinvdevice ERRinvtid ERRbaduid 4.3.2 DELETE_DIRECTORY: Delete DirectoryThe delete directory message is sent to delete an empty directory. The appropriate Tid and additional pathname are passed. The directory must be empty for it to be deleted. Client Request Description =============== ============ UCHAR WordCount; Count of parameter words = 0 USHORT ByteCount; Count of data bytes; min = 2 UCHAR BufferFormat; 0x04 STRING DirectoryName[]; Directory name The directory to be deleted cannot be the root of the share specified by Tid. Server Response Description ================ ============ UCHAR WordCount; Count of parameter words = 0 USHORT ByteCount; Count of data bytes = 0 4.3.2.1 ErrorsERRDOS codes ------------ ERRbadfile ERRbadpath ERRnoaccess ERRnomem ERRbadaccess ERRfileexists ERRSRV codes ------------ ERRaccess ERRinvdevice ERRinvtid ERRbaduid 4.3.3 CHECK_DIRECTORY: Check DirectoryThis SMB is used to verify that a path exists and is a directory. No error is returned if the given path exists and the client has read access to it. When the path turns out to specify a file (nondirectory) then STATUS_NOT_A_DIRECTORY is returned. Client machines which maintain a concept of a "working directory" will find this useful to verify the validity of a "change working directory" command. Note that the servers do NOT have a concept of working directory for a particular client. The client must always supply full pathnames relative to the Tid in the SMB header. Client Request Description =============== ============ UCHAR WordCount; Count of parameter words = 0 USHORT ByteCount; Count of data bytes; min = 2 UCHAR BufferFormat; 0x04 STRING DirectoryPath[]; Directory path Server Response Description ================ ============ UCHAR WordCount; Count of parameter words = 0 USHORT ByteCount; Count of data bytes = 0 DOS clients, in particular, depend on the SMB_ERR_BAD_PATH return code if the directory is not found. 4.3.3.1 ErrorsERRDOS/ERRbadfile ERRDOS/ERRbadpath ERRDOS/ERRnoaccess ERRHRD/ERRdata ERRSRV/ERRinvid ERRSRV/ERRbaduid ERRSRV/ERRaccess 4.3.4 TRANS2_FIND_FIRST2: Search Directory using WildcardsClient Request Value =============== ====== WordCount 15 TotalDataCount Total size of extended attribute list SetupCount 1 Setup[0] TRANS2_FIND_FIRST2 Parameter Block Encoding Description ========================= ============ USHORT SearchAttributes; USHORT SearchCount; Maximum number of entries to return USHORT Flags; Additional information: Bit 0 - close search after this request Bit 1 - close search if end of search reached Bit 2 - return resume keys for each entry found Bit 3 - continue search from previous ending place Bit 4 - find with backup intent USHORT InformationLevel; See below ULONG SearchStorageType; STRING FileName; Pattern for the search UCHAR Data[TotalDataCount]; FEAList if InformationLevel is QUERY_EAS_FROM_LIST Response Parameter Block Description ========================= ============ USHORT Sid; Search handle USHORT SearchCount; Number of entries returned USHORT EndOfSearch; Was last entry returned? USHORT EaErrorOffset; Offset into EA list if EA error USHORT LastNameOffset; Offset into Data[] holding the file name of the last entry, if server needs it to resume search; else 0 UCHAR Data[TotalDataCount]; Level dependent info about the matches found in the search This request allows the client to search for the file(s) which match the file specification. The search can be continued if necessary with TRANS2_FIND_NEXT2. There are numerous levels of information which may be obtained for the returned files, the desired level is specified in the InformationLevel field of the request. The following values can be specified for InformationLevel:
The following sections detail the data returned for each InformationLevel. The requested information is placed in the Data portion of the transaction response. Note: a client which does not support long names can only request SMB_INFO_STANDARD. The search Id is the Search Handle returned back from the server on the FindFirst response which can be used on the FindNext request so that the full path can be avoided. Search Handle is session wide. The server doesn't care what process uses it on the client. A four-byte resume key precedes each data item (described below). The return of resume keys is dependent upon setting the flag SMB_FIND_RETURN_RESUME_KEYS in the FLAGS of the REQ_FIND_NEXT2 packet. The resume key tells the server where to resume the operation on the FindNext request in order to avoid duplicate entries. The contents of the resume key are opaque to the client. If the search doesn't find any names, the server should return either STATUS_NO_SUCH_FILE or the corresponding error code ERROR_FILE_NOT_FOUND . 4.3.4.1 SMB_INFO_STANDARDResponse Field Description =============== ============ SMB_DATE CreationDate; Date when file was created SMB_TIME CreationTime; Time when file was created SMB_DATE LastAccessDate; Date of last file access SMB_TIME LastAccessTime; Time of last file access SMB_DATE LastWriteDate; Date of last write to the file SMB_TIME LastWriteTime; Time of last write to the file ULONG DataSize; File Size ULONG AllocationSize; Size of filesystem allocation unit USHORT Attributes; File Attributes UCHAR FileNameLength; Length of filename in bytes STRING FileName; Name of found file 4.3.4.2 SMB_INFO_QUERY_EA_SIZEResponse Field Description =============== ============ SMB_DATE CreationDate; Date when file was created SMB_TIME CreationTime; Time when file was created SMB_DATE LastAccessDate; Date of last file access SMB_TIME LastAccessTime; Time of last file access SMB_DATE LastWriteDate; Date of last write to the file SMB_TIME LastWriteTime; Time of last write to the file ULONG DataSize; File Size ULONG AllocationSize; Size of filesystem allocation unit USHORT Attributes; File Attributes ULONG EaSize; Size of file's EA information UCHAR FileNameLength; Length of filename in bytes STRING FileName; Name of found file 4.3.4.3 SMB_INFO_QUERY_EAS_FROM_LISTThis request returns the same information as SMB_INFO_QUERY_EA_SIZE, but only for files which have an EA list which match the EA information in the Data part of the request. 4.3.4.4 SMB_FIND_FILE_DIRECTORY_INFOResponse Field Description =============== ================================== ULONG NextEntryOffset; Offset from this structure to the beginning of the next one ULONG FileIndex; TIME CreationTime; File creation time TIME LastAccessTime; Last access time for the file TIME LastWriteTime; Last write time for the file TIME ChangeTime; Last attribute change time for the file LARGE_INTEGER EndOfFile; File size LARGE_INTEGER AllocationSize; Size of filesystem allocation information ULONG ExtFileAttributes; Extended file attributes (see Section 3.12) ULONG FileNameLength; Length of filename in bytes STRING FileName; Name of the file 4.3.4.5 SMB_FIND_FILE_FULL_DIRECTORY_INFOResponse Field Description =============== ============ ULONG NextEntryOffset; Offset from this structure to the beginning of the next one ULONG FileIndex; TIME CreationTime; File creation time TIME LastAccessTime; Last access time for the file TIME LastWriteTime; Last write time for the file TIME ChangeTime; Last attribute change time for the file LARGE_INTEGER EndOfFile; File size LARGE_INTEGER AllocationSize; Size of filesystem allocation information ULONG ExtFileAttributes; Extended file attributes (see Section 3.12) ULONG FileNameLength; Length of filename in bytes ULONG EaSize; Size of file's extended attributes STRING FileName; Name of the file 4.3.4.6 SMB_FIND_FILE_BOTH_DIRECTORY_INFOResponse Field Description =============== ============ ULONG NextEntryOffset; Offset from this structure to the beginning of the next one ULONG FileIndex; TIME CreationTime; File creation time TIME LastAccessTime; Last access time for the file TIME LastWriteTime; Last write time for the file TIME ChangeTime; Last attribute change time for the file LARGE_INTEGER EndOfFile; File size LARGE_INTEGER AllocationSize; Size of filesystem allocation information ULONG ExtFileAttributes; Extended file attributes (see Section 3.12) ULONG FileNameLength; Length of FileName in bytes ULONG EaSize; Size of file's extended attributes UCHAR ShortNameLength; Length of file's short name in bytes UCHAR Reserved; WCHAR ShortName[12]; File's 8.3 conformant name in Unicode STRING FileName; File's full length name 4.3.4.7 SMB_FIND_FILE_NAMES_INFOResponse Field Description =============== ============ ULONG NextEntryOffset; Offset from this structure to the beginning of the next one ULONG FileIndex; ULONG FileNameLength; Length of FileName in bytes STRING FileName; File's full length name 4.3.4.8 SMB_FIND_FILE_UNIXUsed to return UNIX attribute information in a file search response Data Block Encoding Description ==================== ============ ULONG NextEntryOffset; Offset from this structure to the beginning of the next one ULONG ResumeKey; Used for continuing search LARGE_INTEGER EndOfFile; File size LARGE_INTEGER NumOfBytes Number of file system bytes used to store file TIME LastStatusChange; Last time the status of the file was changed. This is in DCE time. TIME LastAccessTime; Time of last file access. This is DCE time. TIME LastModificationTime; Last modification time. This is DCE time. LARGE_INTEGER Uid; Numeric user id for the owner LARGE_INTEGER Gid; Numeric group id of owner ULONG Type; Enumeration specifying the file type. 0 -- File 1 -- Directory 2 -- Symbolic Link 3 -- Character device 4 -- Block device 5 -- FIFO 6 -- Socket LARGE_INTEGER DevMajor; Major device number if file type is device LARGE_INTEGER DevMinor; Minor device number if file type is device LARGE_INTEGER UniqueId; This is a server-assigned unique id for the file. The client will typically map this onto an inode number. The scop of uniqueness is the share LARGE_INTEGER Permissions; Standard UNIX file permissions LARGE_INTEGER Nlinks; The number of directory entries that map to this entry or number of hard links STRING Name; Case-preserved alternative filename 4.3.4.9 SMB_FINDBOTH_MAC_HFS_INFO [View full width]
4.3.4.10 ErrorsERRDOS codes ------------ ERRbadpath ERRnoaccess ERRnomem ERRSRV codes ------------ ERRaccess ERRinvdevice ERRinvtid ERRbaduid 4.3.5 TRANS2_FIND_NEXT2: Resume Directory Search Using WildcardsThis request resumes a search which was begun with a previous TRANS2_FIND_FIRST2 request. Client Request Value =============== ====== WordCount 15 SetupCount 1 Setup[0] TRANS2_FIND_NEXT2 Parameter Block Encoding Description ========================= ============ USHORT Sid; Search handle USHORT SearchCount; Maximum number of entries to return USHORT InformationLevel; Levels described in TRANS2_FIND_FIRST2 request ULONG ResumeKey; Value returned by previous find2 call USHORT Flags; Additional information: bit set- 0 - close search after this request 1 - close search if end of search reached 2 - return resume keys for each entry found 3 - resume/continue from previous ending place 4 - find with backup intent STRING FileName; Resume file name Sid is the value returned by a previous successful TRANS2_FIND_FIRST2 call. If Bit3 of Flags is set, then FileName may be the NULL string, since the search is continued from the previous TRANS2_FIND request. Otherwise, FileName must not be more than 256 characters long. Response Field Description =============== ============ USHORT SearchCount; Number of entries returned USHORT EndOfSearch; Was last entry returned? USHORT EaErrorOffset; Offset into EA list if EA error USHORT LastNameOffset; Offset into Data[] holding the file name of the last entry, if server needs it to resume search; else 0 UCHAR Data[TotalDataCount]; Level dependent info about the matches found in the search 4.3.5.1 ErrorsERRDOS codes ------------ ERRnomem ERRSRV codes ------------ ERRinvtid ERRbaduid 4.3.6 FIND_CLOSE2: Close Directory SearchThis SMB closes a search started by the TRANS2_FIND_FIRST2 transaction request. Client Request Description =============== ============ UCHAR WordCount; Count of parameter words = 1 USHORT Sid; Find handle USHORT ByteCount; Count of data bytes = 0 Server Response Description ================ ============ UCHAR WordCount; Count of parameter words = 0 USHORT ByteCount; Count of data bytes = 0 4.3.6.1 ErrorsERRDOS/ERRbadfid ERRSRV/ERRinvid ERRSRV/ERRaccess 4.3.7 NT_TRANSACT_NOTIFY_CHANGE: Request Change NotificationClient Setup Words Description =================== ============ ULONG CompletionFilter; Specifies operation to monitor USHORT Fid; Fid of directory to monitor BOOLEAN WatchTree; TRUE = Watch all subdirectories too UCHAR Reserved; MUST BE ZERO This command notifies the client when the directory specified by Fid is modified. It also returns the name(s) of the file(s) that changed. The command completes once the directory has been modified based on the supplied CompletionFilter. The command is a "single shot" and therefore needs to be reissued to watch for more directory changes. A directory file must be opened before this command may be used. Once the directory is open, this command may be used to begin watching files and subdirectories in the specified directory for changes. The first time the command is issued, the MaxParameterCount field in the transact header determines the size of the buffer that will be used at the server to buffer directory change information between issuances of the notify change commands. When a change that is in the CompletionFilter is made to the directory, the command completes. The names of the files that have changed since the last time the command was issued are returned to the client. The ParameterCount field of the response indicates the number of bytes that are being returned. If too many files have changed since the last time the command was issued, then zero bytes are returned and the NTSTATUS code STATUS_NOTIFY_ENUM_DIR (0x0000010C) is returned in the Status field of the response. The CompletionFilter is a mask created as the sum of any of the following flags: FILE_NOTIFY_CHANGE_FILE_NAME 0x00000001 FILE_NOTIFY_CHANGE_DIR_NAME 0x00000002 FILE_NOTIFY_CHANGE_NAME 0x00000003 FILE_NOTIFY_CHANGE_ATTRIBUTES 0x00000004 FILE_NOTIFY_CHANGE_SIZE 0x00000008 FILE_NOTIFY_CHANGE_LAST_WRITE 0x00000010 FILE_NOTIFY_CHANGE_LAST_ACCESS 0x00000020 FILE_NOTIFY_CHANGE_CREATION 0x00000040 FILE_NOTIFY_CHANGE_EA 0x00000080 FILE_NOTIFY_CHANGE_SECURITY 0x00000100 FILE_NOTIFY_CHANGE_STREAM_NAME 0x00000200 FILE_NOTIFY_CHANGE_STREAM_SIZE 0x00000400 FILE_NOTIFY_CHANGE_STREAM_WRITE 0x00000800 Server Response Description ================ ============ ParameterCount # of bytes of change data Parameters[ParameterCount ] FILE_NOTIFY_INFORMATION Structures The response contains FILE_NOTIFY_INFORMATION structures, as defined below. The NextEntryOffset field of the structure specifies the offset, in bytes, from the start of the current entry to the next entry in the list. If this is the last entry in the list, this field is zero. Each entry in the list must be longword aligned, so NextEntryOffset must be a multiple of four. typedef struct { ULONG NextEntryOffset; ULONG Action; ULONG FileNameLength; WCHAR FileName[1]; } FILE_NOTIFY_INFORMATION; Where Action describes what happened to the file named FileName: FILE_ACTION_ADDED 0x00000001 FILE_ACTION_REMOVED 0x00000002 FILE_ACTION_MODIFIED 0x00000003 FILE_ACTION_RENAMED_OLD_NAME 0x00000004 FILE_ACTION_RENAMED_NEW_NAME 0x00000005 FILE_ACTION_ADDED_STREAM 0x00000006 FILE_ACTION_REMOVED_STREAM 0x00000007 FILE_ACTION_MODIFIED_STREAM 0x00000008 The client waits on the response after it sends the notify change request. If the client wants to discard the request, it can send NT_CANCEL to the server which should return STATUS_CANCELED. The server can reject the request with STATUS_NOT_IMPLEMENTED. 4.3.7.1 ErrorsERRDOS codes ------------ ERRbadpath ERRnoaccess ERRnomem ERRSRV codes ------------ ERRaccess ERRinvdevice ERRinvtid ERRbaduid ERRSRV/ERROR_NOTIFY_ENUM_DIR 4.4 DFS Operations4.4.1 TRANS2_GET_DFS_REFERRAL: Retrieve Distributed Filesystem ReferralThe client sends this request to ask the server to convert RequestFilename into an alternate name for this file. This request can be sent to the server if the server response to the NEGOTIATE SMB included the CAP_DFS capability. The TID of the request must be IPC$. Bit15 of Flags2 in the SMB header must be set, indicating this is a UNICODE request. Client Request Description =============== ============ WordCount 15 TotalDataCount 0 SetupCount 1 Setup[0] TRANS2_GET_DFS_REFERRAL Parameter Block Encoding Description ========================= ============ USHORT MaxReferralLevel; Latest referral version number understood WCHAR RequestFileName[]; DFS name of file for which referral is sought Response Data Block Description ==================== ============ USHORT PathConsumed; Number of RequestFilename bytes consumed by the server USHORT NumberOfReferrals; Number of referrals contained in this response USHORT Flags; Bit0 - The servers in Referrals are capable of fielding TRANS2_GET_DFS_REFERRAL. Bit1 - The servers in Referrals should hold the storage for the requested file REFERRAL_LIST Referrals[]; Set of referrals for this file UNICODESTRING Strings; Used to hold the strings pointed to by Version 2 Referrals in REFERRALS The server response is a list of Referrals which inform the client where it should resubmit the request to obtain access to the file. PathConsumed in the response indicates to the client how many characters of RequestFilename have been consumed by the server. When the client chooses one of the referrals to use for file access, the client may need to strip the leading PathConsumed characters from the front of RequestFileName before submitting the name to the target server. Whether or not the pathname should be trimmed is indicated by the individual referral as detailed below. Flags indicates how this referral should be treated. If bit0 is clear, any entity in the Referrals list holds the storage for RequestFileName. If bit0 is set, any entity in the Referrals list has further referral information for RequestFilename - a TRANS2_GET_DFS_REFERRAL request should be sent to an entity in the Referrals list for further resolution. The format of an individual referral contains version and length information allowing the client to skip referrals it does not understand. MaxReferralLevel indicates to the server the latest version of referral which the client can digest. Since each referral has a uniform element, MaxReferralLevel is advisory only. Each element in Referrals has this envelope: REFERRAL_LIST Element ====================== USHORT VersionNumber; Version of this referral element USHORT ReferralSize; Size of this referral element The following referral element versions are defined: Version 1 Referral Element Format ================================== USHORT ServerType; Type of Node handling referral: 0 - Don't know 1 - SMB Server 2 - Netware Server 3 - Domain USHORT ReferralFlags; Flags which describe this referral: 01 - Strip off PathConsumed characters before submitting RequestFileName to Node UNICODESTRING Node; Name of entity to visit next Version 2 Referral Element Format ================================== USHORT ServerType; Type of Node handling referral: 0 - Don't know 1 - SMB Server 2 - Netware Server 3 - Domain USHORT ReferralFlags; Flags which describe this referral: 01 - Strip off PathConsumed characters before submitting RequestFileName to Node ULONG Proximity; A hint describing the proximity of this server to the client. 0 indicates the closest, higher numbers indicate increasingly "distant" servers. The number is only relevant within the context of the servers listed in this particular SMB. ULONG TimeToLive; Number of seconds for which the client can cache this referral. USHORT DfsPathOffset; Offset, in bytes from the beginning of this referral, of the DFS Path that matched Pat hConsumed bytes of the RequestFileName. USHORT DfsAlternatePathOffset; Offset, in bytes from the beginning of this referral, of an alternate name (8.3 form at) of the DFS Path that matched PathConsumed bytes of the RequestFileName. USHORT NetworkAddressOffset; Offset, in bytes from the beginning of this referral, of the entity to visit next. The CIFS protocol imposes no referral selection policy. 4.4.1.1 ErrorsERRDOS codes ------------ ERRnoaccess ERRnomem ERRSRV codes ------------ ERRaccess ERRinvdevice ERRinvtid ERRbaduid 4.4.2 TRANS2_REPORT_DFS_INCONSISTENCY: Inform a server about DFS ErrorAs part of the Distributed Name Resolution algorithm, a DFS client may discover a knowledge inconsistency between the referral server (i.e., the server that handed out a referral), and the storage server (i.e., the server to which the client was redirected by the referral server). When such an inconsistency is discovered , the DFS client optionally sends this SMB to the referral server, allowing the referral server to take corrective action. Client Request Description =============== ============ WordCount 15 MaxParameterCount 0 SetupCount 1 Setup[0] TRANS2_REPORT_DFS_INCONSISTENCY Parameter Block Encoding Description ========================= ============ UNICODESTRING RequestFileName; DFS Name of file for which referral is sought The data part of this request contains the referral element (Version 1 format only) believed to be in error. These are encoded as described in the TRANS2_GET_DFS_REFERRAL response. If the server returns success, the client can resubmit the TRANS2_GET_DFS_REFERRAL request to this server to get a new referral. It is not mandatory for the DFS knowledge to be automatically repaired - the client must be prepared to receive further errant referrals and must not wind up looping between this request and the TRANS2_GET_DFS_REFERRAL request. Bit15 of Flags2 in the SMB header must be set, indicating this is a UNICODE request. 4.4.2.1 ErrorsERRDOS codes ------------ ERRnoaccess ERRnomem ERRSRV codes ------------ ERRaccess ERRinvdevice ERRinvtid ERRbaduid 4.5 Miscellaneous Operations4.5.1 NT_TRANSACT_IOCTLThis command allows device and file system control functions to be transferred transparently from client to server. Setup Words Encoding Description ===================== ============ ULONG FunctionCode; NT device or file system control code USHORT Fid; Handle for i/o or file system control, unless BIT0 of ISFLAGS is set BOOLEAN IsFsctl; Indicates whether the command is for device (FALSE) or a file system control (TRUE) UCHAR IsFlags; BIT0 - command is to be applied to share root handle. Share must be a DFS share. Data Block Encoding Description ==================== ============ UCHAR Data[ Passed to the Fsctl or Ioctl TotalDataCount]; Server Response Description ================ ============ SetupCount 1 Setup[0] Length of information returned by i/o or file system control DataCount Length of information returned by i/o or file system control Data[DataCount] The results of the i/o or file system control 4.5.1.1 ErrorsERRDOS codes ------------ ERRnoaccess ERRnomem ERRSRV codes ------------ ERRaccess ERRinvdevice ERRinvtid ERRbaduid 4.5.2 NT_TRANSACT_QUERY_SECURITY_DESCThis command allows the client to retrieve the security descriptor on a file. Client Parameter Block Description ======================= ============ USHORT Fid; FID of target USHORT Reserved; MUST BE ZERO ULONG SecurityInformation; Fields of descriptor to get NtQuerySecurityObject() is called, requesting SecurityInformation. The result of the call is returned to the client in the Data part of the transaction response. 4.5.2.1 ErrorsERRDOS codes ------------ ERRnoaccess ERRnomem ERRbadaccess ERRSRV codes ------------ ERRaccess ERRinvdevice ERRinvtid ERRbaduid 4.5.3 NT_TRANSACT_SET_SECURITY_DESCThis command allows the client to change the security descriptor on a file. Client Parameter Block Encoding Description ================================ ============ USHORT Fid; FID of target USHORT Reserved; MUST BE ZERO ULONG SecurityInformation; Fields of Security Descriptor to set Data Block Encoding Description ==================== ============ Data[TotalDataCount] Security Descriptor information Data is passed directly to NtSetSecurityObject(), with SecurityInformation describing which information to set. The transaction response contains no parameters or data. 4.5.3.1 ErrorsERRDOS codes ------------ ERRnoaccess ERRnomem ERRbadaccess ERRbadshare ERRSRV codes ------------ ERRaccess ERRinvdevice ERRinvtid ERRbaduid |