Enhanced File System NCPs

File System NCPs enable developers to perform many tasks all of which fall into two broad categories. First, developers can obtain information about files, volumes and directories. For example, developers can get a file's size, get file or subdirectory information, get directory rights, get name space information, get a volume name or number, and so on and so on.

Second, File System NCPs enable developers to manipulate files and directories. For example, using File NCPs, developers can create, open, read, write, close, delete, and rename files. They can also manipulate extended file attributes, restore erased files, purge deleted files, set and scan file information, and copy files between directories on the same file server. Using Directory NCPs developers can create, rename, and delete directories. They can also modify a directory's maximum rights mask, add and delete directory trustees, allocate and deallocate directory handles, and so on and so on. This introduction is divided into the following sections:

• File Security
• File Names
• Directory Access Rights
• Directory Handle Table
• WorkStation Tables
• Directory Table
• Volume Table
• Information About NetWare v3.1 and Above NCPs

File Security

The server strictly enforces file access security to ensure that clients are allowed access only to files for which they have been granted rights. In addition, the server coordinates file access among clients so that file data integrity can be maintained in the distributed multiuser environment created by multiple clients contending for the same information.

A client's access to files in a directory area is controlled by the effective rights the client has in the directory. These rights are specified later in this Introduction in section 5.3 Directory Access Rights. In addition, each file has four file attribute bytes (bytes 0-3) that control access to the file. The bits of each of the four file attribute bytes are defined as follows:

Bit	Name	Bit Description
0	Read Only	File can be read but not written to.
1	Hidden	File will not be shown in a normal directory listing.
2	System	File will not be shown in a normal directory listing.
3	Execute Only	File can be loaded for execution only; once this Bit has been set, it cannot be cleared.
4	Subdirectory	Entry is a subdirectory, not a file.
5	Archive	Bit is set if the file has been changed since it was last backed up.
6	Execute Confirm
7	Shareable	Bit is set if file can be simultaneously accessed by more than one user.

Bit	Name	Bit Description
8-10	Search Mode	The Search Mode, which is comprised of the first three bits, is only valid with NetWare v2.0a and above. The possible values of the Search Mode are listed in the following table.
11	Indexed	If set, the OS will index the file's sectors in the File Allocation Tables (FATs) thereby reducing the time it takes to access the file.
12	Transactional	If set, the Transaction Tracking System (TTS) will track all writes to the file during a transaction. A transaction file cannot be deleted or renamed. (See the chapter on the Transaction Tracking System.)
13	Reserved
14	Read Audit	Set only by users with supervisor security equivalence.
15	Write Audit	Bit Set only by users with supervisor security equivalence.

Clients can access files by name when files are being created, deleted, renamed, searched for, and opened. When a file is opened, the server gives the client a 6-byte file handle that the client must supply to the server when the client accesses the file for reading, writing, or closing. To a client, a file is a logical byte stream. The client can read or write "records" of varying sizes starting at any byte offset within the file.

A client must specify the search attributes when making requests to open a file, rename a file, erase a file, search for a file, set a file's attribute byte, or get or set a file's extended attribute byte. The bits of the search attributes byte correspond to the bits in the file attributes byte. However, the only bits that are significant in the search attribute byte are the "hidden" and "system" bits. A normal file is a file whose system and hidden bits are clear in its file attributes byte.

A system file is a file whose system bit is set; a hidden file is a file whose hidden bit is set. For functions that require the search attributes, the following table applies:

Byte 2

Byte 2 Bit Definition
23	22	21	20	19	18	17	16	Definition
x								Inhibit Data Migration Bit
	x							Data Migrated Bit
		x						reserved
			x					File Auditing Bit
				x				Copy Inhibit Bit
					x			Delete Inhibit Bit
						x		Rename Inhibit Bit
							x	Immediate Purge Bit

Byte 3

Byte 3 Bit Definition
31	30	29	28	27	26	25	24	Definition
x								reserved
	x							Attributes Archive Bit
		x						Can't Compress Data Bit
			x					reserved
				x				Compression Inhibit Bit
					x			Data Stream Compressed Bit
						x		Compress Immediate Bit
							x	Data Migration Save Key Bit

File Names

Filenames can be up to 14 characters long. Filenames can contain any characters greater than 0x20 (ASCII space), except the following:

• Double quote "
• Plus sign +
• Comma ,
• Slash /
• Colon :
• Semicolon ;
• Less than sign <
• Egual sign =
• Greater than sign >
• Question mark ?
• Left brace [
• Backslash \
• Right brace ]
• Vertical bar |

Periods are legal characters in a filename and are treated like any other character.

Directory Access Rights

Several protocols have an Access Rights Mask field, which is used for either retrieving or setting security information about directories. This section discusses such fields.

Disk space on a file server is divided into one or more named logical volumes, with each volume having its own separate hierarchical directory structure. Each directory has a list of trustees and trustee access rights; a trustee in the trustee list is represented by the object ID of some object (user or group) that is given certain access privileges to the directory. Trustee access privileges are represented by a 1-byte mask, with the bits yielding the following function:

The access rights granted to an object in a directory within a directory tree are inherited by that object in all subdirectories below that directory. The inherited rights are effective only down to a subdirectory in which other access rights have been granted.

In addition to the rights granted to each trustee individually, each directory has associated with it a maximum access rights mask, that indicates which access actions can occur in the directory. A trustee is allowed only the rights that appear in both the trustee's access rights mask and the directory's maximum access rights mask (logical AND of the trustee's access rights mask and the directory's maximum access rights mask).

The NetWare implementation of the file service protocols allows a client to claim security equivalence to as many as 33 trustees (user or group objects) at once. If object A is made "security equivalent" to object B, object B's object ID is added to the SECURITY_EQUALS property of object A. An object that is security equivalent to another object has the access rights of both objects combined. For example, object JOE (a user object) might be security equivalent to one or more other user or group objects (no more than 33). If JOE is a trustee in a directory and JOE is given Read, Open, and Search access rights in that directory, JOE can search for, open, and read files in that directory and all its subdirectories if the maximum access rights of the directory and subdirectories include Read, Open, and Search rights. Later, JOE is made security equivalent to the SUPERVISOR object. JOE now has all rights of JOE as a trustee and JOE as a security equivalent of SUPERVISOR. Therefore, JOE can do anything that the object JOE is granted as a trustee of the directory, and JOE can do anything that the SUPERVISOR object can do in the directory. In other words, JOE's actual access rights in a given directory are computed by combining (logically ORing) JOE's access rights with the rights of the other trustees to which JOE is security equivalent and then logically ANDing these rights with the directory's maximum access rights mask.

NOTE: A client's trustee number (also known as the Object ID) is determined when the client calls Login Object (function 23, subfunction 20).

Directory Handle Table

The following sections discuss the NetWare implementation of the workstation shell and the file server operating system. Both the NetWare file server and the workstation maintain several tables used for directory services. A particular implementation must comply with the following design if it is to remain compatible with NetWare v2.x.

Each workstation attached to a given file server can allocate up to 256 directory handles on that file server. A directory handle is a number (00h to FFh) that points to a volume or a directory path. A file server maintains a Directory Handle Table for each attached workstation. A Directory Handle Table consists of 256 slots. Each slot represents a directory handle. For example, the first slot represents directory handle 1, the second slot represents directory handle 2, and so on. Each slot contains a volume name or a directory path. For example, slot 5 represents directory handle 05h, which points to the volume or directory path contained in slot 5.

A developer can use Directory Services system calls to access up to 256 directory handles for the workstation on which an application is running. Once a directory handle is set, the directory handle can be used to specify a volume or a directory path on a file server.

Frequently, when making a Directory Services system call, a programmer must target a particular directory in the request buffer using one of the following three methods:

• Allocate a directory handle to point to the target directory and then specify the allocated directory handle in the request buffer.
• Specify both a directory handle and a complementary directory path in the request buffer. The directory handle must lead part of the way to the target directory, and the directory path must lead the rest of the way.
• Specify the entire directory path in the request buffer.

Directory Services system calls do not specify the file server. (Volume names and directory paths do not include file server names.) Before a Directory Services system call is made, the target file server should be the current file server.

Workstation Tables

A workstation maintains three tables that correspond to each other and relate to the file server's Directory Handle Table: a Drive Handle Table, a Drive Flag Table, and a Drive Connection ID Table. Each table consists of 32 1-byte entries. The first 26 slots of each table represent the permanent drive letters A to Z. The last 6 slots represent the temporary drive letters in the order listed below:

• [ (Left Bracket)
• \ (Slash)
• ] (Right bracket)
• ^ (Caret)
• _ (Underscore)
• ' (Single quote)

Each slot in the Drive Handle Table contains a directory handle number. For example, if slot 6 in the table contains the value 02h, then drive letter F (the sixth letter in the alphabet) points to the volume or directory path contained in slot 2 of the file server's corresponding Directory Handle Table.

Each slot in the Drive Flag Table contains one of the following values:

Each slot in the Drive Connection ID Table contains a value (00h to 08h) identifying the server to which the drive letter is mapped. The value represents the position (slot 1 to slot 8) of the file server in the workstation's Server Name Table and Connection ID Table. (For more information about the Server Name Table and the Connection ID Table see Introduction to Connection Services.)

An application can only allocate the first 26 drive letters (A to Z) as permanent network drives. An application can allocate any of the 32 drive letters as temporary drives. A temporary drive remains allocated only as long as the application remains active.

Directory Services system calls that allocate and deallocate directory handles map (or assign) workstation drives to directory handles by accessing these three workstation tables.

Directory Table

To record information about directories, a file server maintains a Directory Table. The Directory Table consists of several kinds of 32-byte entries, including directory nodes, file nodes, and trustee nodes.

A directory node includes the following information about a directory: directory name, attribute byte, maximum rights mask, creation date, creator's object ID, a link to the parent directory, and a link to a trustee node (if one exists).

A file node includes the following information about a file: file name, attribute byte, extended attribute byte, file size, creation date, last-accessed date, last-updated date and time, and a link to a directory.

A trustee node includes the following information: the object IDs of one to five trustees of a directory linked to the trustee node, one to five corresponding trustee rights masks, a link to a directory, and a link to the next trustee node (if one exists).

Directory Services system calls that return directory information and manipulate rights access the Directory Table.

Volume Table

To record information about volumes, a file server maintains a Volume Table that includes the number of volumes mounted in the file server, the names and sizes of each volume, and other information pertaining to each volume. System calls that return information about volumes access the Volume Table.

NOTE: Scanning directories is accomplished with File Search Initialize (NCP 87 2) and File Search Continue (NCP 87 3). These calls are found in the Enhanced File Services section.

Information About NetWare v3.1 and Above NCPs

This section illustrates and explains the bit masks and structures that enable client-server communication using NetWare v3.1 and above NCPs. These NCPs are provided to allow the NetWare v3.1 and above operating system to become independent of the client workstation, no matter which operating system the workstation is using. Name Space modules will still be required, but internal hooks for each client will not be required in the network operating system.

Typically, clients request information from the server by setting selected bits or by filling fields of a particular structure with information. The server responds by returning information in the fields of a particular structure.

The bit masks and structures explained in this section are referenced by fields in the Request and Reply Formats of the NCP calls. As developers use the NCP calls, they can refer back to this section as needed for further information about particular fields. The following structures and bit masks are explained:

• NetWareInformationStructure Definition
• Enhanced Netware File Name Structure Definition
• Enhanced NetWare Handle and Path Structure Definition
• NetWare Trustee Structure Definition
• Name Space Information Bit Mask
• Search Attributes Definition
• Attributes Definition
• InHerited Rights Mask Definition
• Modify File or SubDirectory DOS Info Structure Definition

NetWareInformationStructure Definition

The NetWareInformationStructure encompasses both the way a client requests information from a server and the way a server responds to a client's request. The client-request and server-response process works as follows.

When, in a client's request packet, a particular bit in the ReturnInfoMask field (LONG) is set, the server uses the corresponding structure in the NetWareInformationStructure to return the requested information in a reply packet. For example, if the Rights Information bit of the ReturnInfoMask field is set, the server uses the RightsInfoStruct field of the NetWareInformationStructure to return information about a specified file's rights.

Note: The server always returns a full NetWareInformationStructure regardless of the bit or bits a client sets; however, the NetWareInformationStructure contains valid information ONLY for those field or fields that have been set, and only upon successful completion of the NCP call.

This discussion of the NetWareInformationStructure is divided into the following parts:

• ReturnInfoMask Field
• EnhNetWareInformationStructure

ReturnInfoMask Field

To request information from a server, a client sets the appropriate bit or bits of the ReturnInfoMask field and sends a request packet to the server. To return information when a particular bit in the ReturnInfoMask field is set, the server uses the particular structure in the NetWareInformationStructure that corresponds to the bit or bits that have been set. More information on the bits in the ReturnInfoMask field are given in the discussion of the NetWareInformationStructure.

Note the Include File Name Structure bit in the ReturnInfoMask. When this bit is set, the server returns a file name and a file name length in a EnhNetWareFileNameStruct structure. Since this structure is not a field of the NetWareInformationStructure, it is discussed under the heading "EnhNetWareFileNameStruct Definition." The ReturnInfoMask is defined below. (Note that only bits 0-11 are defined in v3.11, while all other bits are defined in v4.x. Also, the NetWare Compress Information Flag bit must be set to get this 4.x information.)

NetWare Info Structure Additions for NetWare 4.10 and NetWare 4.11

Several new pieces of information are available in the NetWareInfoStruct in v4.10 or greater, that are not available in previous version of NetWare. First, to better facilitate the space usage in a reply packet the following bit was in the ReturnInfoMask field, so that only the information requested by the caller will be returned instead of the complete structure as in previous version of NetWare:

#define RNewStyle 0x80000000

The new information bits available to the caller (only when the RNewStyle bit is set) are shown below, followed by explanations.

• RReferenceID
• RNSAttribute
• RDataStreamActual
• RDataStreamLogical
• RLastUpdatedInSeconds
• RDOSName
• RFlushTime
• RParentBaseID
• RMACFinderInfo
• RSiblingCount
• REffectiveRights
• RMACDateAndTime
• RLastAccessedTime
• R64BitFileSize

Extended Return Info Mask Bit Definitions
31	30	29	28	27	26	25	24	23	22	21	20	19	18	17	16	15	14	13	12	Definition
x																				New Style (Compress Reply Info)
	0																			Reserved
		0																		Reserved
			0																	Reserved
				0																Reserved
					x															64 bit file sizes(NW v6.sp2 or greater )
						0														Reserved
							x													Last Accessed Time(NW v5.00 or greater )
								x												MAC Date & Time ( NW v4.11 or greater )
									x											Effective Rights ( NW v4.11 or greater )
										x										Sibling Count ( NW v4.11 or greater )
											x									MAC Finder Info ( NW v4.11 or greater )
												x								Parent Base ID ( NW v4.11 or greater )
													x							Flush Time ( NW v4.11 or greater )
														x						DOS Name ( NW v4.11 or greater )
															x					Last Updated In Seconds ( NW v4.11 or greater )
																x				Data Stream Logical
																	x			Data Stream Actual
																		x		Name Space Attribute
																			x	Reference ID

RReferenceID bit is used to get the change count on a file, directory, or the volume. This can be used to tell if something has changed. The following structure is returned when this bit is enabled:

	typedef struct 
	{
		WORD CurrentReferenceID;
	} ReferenceIDStruct;

RNSAttribute bit is used to get the file attribute value of the entry requested, the following structure is returned when this information is requested:

	typedef struct
	{
		LONG FileAttributes;
	} NSAttributeStruct;

RDataStreamActual bit is used to get a list of data streams and the number of FAT blocks associated on a file, the following structure is returned when this information is requested:

	typedef struct
	{
		LONG DataStreamNumber;
		LONG DataStreamFATBlockSize;
	} DataStreamFATInfo;

	typedef struct
	{
		LONG NumberOfDataStreams;
		DataStreamFATInfo ds[NumberOfDataStreams];
	} DStreamActual;

RDataStreamLogical bit is used to get a list of data streams and their sizes on a file, the following structure is returned when this information is requested:

	typedef struct
	{
		LONG DataStreamNumber;
		LONG DataStreamSize;
	} DataStreamSizeInfo;

	typedef struct
	{
		LONG NumberOfDataStreams;
		DataStreamSizeInfo ds[NumberOfDataStreams];
	} DStreamLogical;

RLastUpdatedInSeconds bit is used to get the last time a file or directory was updated in the Number of Seconds relative to the year 2000, the following structure is returned when this information is requested:

	typedef struct
	{
		LONG SecondsRelativeToTheYear2000;
	} LastUpdatedInSecondsStruct;

RDOSName bit is used to return the DOS name of a file or directory independent of the caller specified name space value, the following structure will be returned when this information is requested:

	NOTE: Depending on which data type is specified in the request, one of the following data structures will be used:
	(ASCII data type)
	typedef struct
	{
		BYTE DOSNameLength;
		BYTE DOSName[DOSNameLength];
	} DOSNameStruct;

	(UTF8 data type)
	typedef struct
	{
		WORD DOSNameLength;  (Lo-Hi)
		BYTE DOSName[DOSNameLength];
	} DOSNameStruct;

RFlushTime bit is used to return the flush time on a file, the following structure will be returned when this information is requested:

	typedef struct
	{
		LONG FlushTime;
	} FlushTimeStruct;

RParentBaseID bit is used to return the Parent (father) Directory Base number on a file or subdirectory, the following structure will be returned when this information is requested:

	typedef struct
	(
		LONG ParentBaseID;
	} ParentBaseIDStruct;

RMACFinderInfo bit is used to return the Macintosh Finder information on a file or subdirectory (this is only valid information when the MAC Name Space is loaded on the specified volume), the following structure will be returned when this information is requested:

	typedef struct
	(
		BYTE MacFinderInformatio[32];
	} MacFinderInfoStruct;

RSiblingCount bit is used to return the number of siblings (children) in a subdirectory (only subdirectories can have siblings), the following structure will be returned when this information is requested:

	typedef struct
	(
		LONG SiblingCount;
	} SiblingCountStruct;

NOTE: The SiblingCount (mask 0x20000000) is always zero for a subdirectory.

REffectiveRights bit is used to return the Effective Rights of a specified path, the following structure will be returned when this information is requested:

	typedef struct
	(
		LONG EffectiveRights;
	} EffectiveRightsStruct;

RMACDateAndTime bit is used to return the Macintosh Date & Time fields (this is only valid information when the MAC Name Space is loaded on the specified volume), the following structure will be returned when this information is requested:

	typedef struct
	(
		int	MACCreateTime;
		int	MACBackupTime;
	} MacTimeStruct;

The MACCreateTime field specifies the time the Macintosh entry was created.

The MACBackupTime field specifies the time that the Macintosh entry was last backed up.

RLastAccessedTime bit is used to get from a file the last time it was accessed. The Time format is the same as the DOS Time field. The following structure is returned when this bit is enabled:

	typedef struct 
	{
		WORD LastAccessedTime;
	} LastAccessedTimeStruct;

The LastAccessedTime field specifies the last time a file was accessed, which includes being opened, written to, or having it's time/date stamp changed.

R64BitFileSize bit is used to get the 64 bit file size of a file on an NSS Volume. If the request is made on a traditional volume, then a 32 bit file size is returned with the upper 4 bytes zeroed:

	typedef struct 
	{
		UINT64 FileSize;
	} 64BitFileSizeStruct;

NetWareInformationStructure

The NetWareInformationStructure is a composite structure comprised of many small structures of information. Each small structure corresponds to a particular bit of the ReturnInfoMask field. Hence, the server returns valid information in a particular structure only when the client specifically requests that information by setting the appropriate bit of the ReturnInfoMask field, and only when the server returns a SUCCESSFUL completion code.

Note: The server always returns a full NetWareInformationStructure regardless of the bit or bits a client sets; however, the NetWareInformationStructure contains valid information ONLY for those field or fields that have been set, and only upon successful completion of the NCP call.

When the server gathers information for the NetWareInformationStructure, naturally the more information a client has requested the longer the reply takes. Because of this, the client should request only information needed.

Furthermore, the server requires extremely large amounts of time to collect information for some pieces than from others. For example, the server requires an unusually longer time to collect the DataStreamSpaceAllocatedInformation piece.

The layout of the NetWareInformationStructure and the smaller structures of which it is composed follows. Each field in the structure is a smaller structure that corresponds to a bit of the ReturnInfoMask field.

Offset	Content	Type
0	DSSpaceAllocateStruct (Data Stream Alloc Bit)	STRUCTURE
+	AttributesStruct (Attributes Bit)	STRUCTURE
+	DataStreamSizeStruct (Data Stream Size Bit)	STRUCTURE
+	TotalStreamSizeStruct (Total Stream Size Bit)	STRUCTURE
+	CreationInfoStruct (Creation Bit)	STRUCTURE
+	ModifyInfoStruct (Modify Bit)	STRUCTURE
+	ArchiveInfoStruct (Archive Bit)	STRUCTURE
+	RightsInfoStruct (Rights Bit)	STRUCTURE
+	DirEntryStruct (Directory Entry Bit)	STRUCTURE
+	EAInfoStruct (Extended Attribute Bit)	STRUCTURE
+	NSInfoStruct (Name Space Bit)	STRUCTURE

Data Stream Space Allocated Information Structure

	Offset	Content					Type
	0	DataStreamSpaceAlloc	(variable) 	LONG (Lo-Hi)

Attributes Information Structure

	Offset	Content				Type
	0	Attributes	(variable)	LONG (Lo-Hi)
	4	Flags		(variable)	WORD (Lo-Hi)

Data Stream Size Information Structure

	Offset	Content				Type
	0	DataStreamSize	(variable)	LONG (Lo-Hi)

(The DataStreamSizeStruct field is synonymous to file size in the DOS name space.)

Total Streams Data Size Information Structure

	Offset	Content					Type
	0	TtlDSDskSpaceAlloc	(variable)	LONG (Lo-Hi)
	4	NumberOfDataStreams	(variable)	WORD (Lo-Hi)

(The TtlDSDskSpaceAlloc field is the number of 4K blocks that the given file is using.)

Extended Attributes Information Structure

	Offset	Content				Type
	0	ExtAttrDataSize	(variable)	LONG (Lo-Hi)
	4	ExtAttrCount	(variable)	LONG (Lo-Hi)
	8	ExtAttrKeySize	(variable)	LONG (Lo-Hi)

Archive Information Structure

	Offset	Content				Type
	0	ArchivedTime	(variable)	WORD (Lo-Hi)
	2	ArchivedDate	(variable)	WORD (Lo-Hi)
	4	ArchiverID	(variable)	LONG (Hi-Lo)

Modify Information Structure

	Offset	Content				Type
	0	ModifiedTime	(variable)	WORD (Lo-Hi)
	2	ModifiedDate	(variable)	WORD (Lo-Hi)
	4	ModifierID	(variable)	LONG (Hi-Lo)
	8	LastAccessDate	(variable)	WORD (Lo-Hi)

Creation Information Structure

	Offset	Content				Type
	0	CreationTime	(variable)	WORD (Lo-Hi)
	2	CreationDate	(variable)	WORD (Lo-Hi)
	4	CreatorID	(variable)	LONG (Hi-Lo)

Name Space Information Structure

	Offset	Content				Type
	0	CreatorNameSpaceNumber		LONG (Lo-Hi)

Dir Entry Information Structure

	Offset	Content				Type
	0	DirectoryEntryNumber		LONG (Lo-Hi)
	4	DOSDirectoryEntryNumber		LONG (Lo-Hi)
	8	VolumeNumber			LONG (Lo-Hi)

Rights Information Structure

	Offset	Content					Type
	0	InheritedRightsMask	(variable)	WORD (Lo-Hi)

EnhNetwareFileNameStruct Definition

The EnhNetWareFileNameStruct structure is used to pass a filename back to the client. It consists of a length field and a filename field. The filename is limited to a maximum of 768 bytes in UTF8 format and 255 bytes in ASCII format. These maximums are provided so that a UTF8 string can be represented given a worst case scenario where a character's UTF8 representation takes 3 bytes.

Note: The server always returns the EnhNetWareFileNameStruct for the following NCP: Search For File or Subdirectory (0x2222 89 03). For all other NCPs, the EnhNetWareFileNameStruct is returned to the client only when the IncludeFileNameStructure bit is set in the ReturnInfoMask field.

Note: The length field in the Enhanced File Name Information Structure is determined by the data type flag that is passed in in the NCP request. If the data type flag in the request indicates ASCII, then the length field will be 1 byte (as it has previously been). If the data type flag in the request indicates UTF8, then the length field will be 2 bytes (WORD). Refer to the Data Type Flag definitions below.

Enhanced File Name Information Structure (ASCII data type)

	Offset	Content				Type 
	0	FileNameLength	(variable)	BYTE
	1	FileName[]	(variable)	BYTE

Enhanced File Name Information Structure (UTF8 data type)

	Offset	Content				Type 
	0	FileNameLength	(variable)	WORD (Lo-Hi)
	1	FileName[]	(variable)	BYTE

NetWare Handle and Path Structure Definition

The EnhNetWareHandlePathStruct is a multi-definition structure that clients can use to pass a Handle or Path to the server. The client can pass a handle or path by using the Volume Number field, the Dirctory Base field, or the Directory Handle field.

The first part of the Handle\Path structure is used to pass to the server either a 1-byte Directory Handle (v2.15 Style Short Directory Handle) or a 4-Byte Directory Base (v3.1 Style). The layout of the handle portion of the structure is as follows:

	LONG	Directory Base or Short Directory Handle; (Lo-Hi)
	BYTE	Volume Number;
	BYTE	Handle Flag;
	BYTE	Data Type Flag;
	BYTE	Reserved[5];
	BYTE	Path Component Count;    /* Count for each directory and subdirectory. For
						example, SYS:TEST\NLM_TEST would be a path
						component count of 3. */

The client can pass a Short Directory Handle (with or without a path) a Directory Base (with or without a path), or a fully qualified path.

The server always checks the Handle Flag field to see if the handle is a Short Directory Handle (0), a Directory Base (1), or No Handle Present (FF). It performs the appropriate action based on the Handle Flag.

If the server checks the Handle Flag and finds that the client has passed a Short Directory Handle or a Directory Base, the server can use the Path Component.

If the server checks the Handle Flag and finds that the client has passed no handle, the server expects the first path component to contain the Volume Name. If there are additional components, the server handles them after generating a Volume Number.

The Data Type Flag indicates what format the path string will be in. There are currently 2 supported formats. Ascii and UTF8.

DataTypeFlag

	#define ASCII_DATA_TYPE	0x00
	#define UTF8_DATA_TYPE	0x01

The second portion of the Handle\Path structure is used to pass a qualified NetWare Path (Len, String) in component form (Path Component Count is used for the number of Components). Note: The length field is determined by the data type flag that is passed in in the NCP request. If the data type flag in the request indicates ASCII, then the length field will be 1 byte (as it has previously been). If the data type flag in the request indicates UTF8, then the length field will be 2 bytes (WORD). The layout of the path portion of the structure (one structure for each directory on the tree) is as follows:

		(ASCII data type)
		struct
		{
			BYTE PathNameLen;
			BYTE PathName[];
		} Pcomponent[];

		(UTF8 data type)
		struct
		{
			WORD PathNameLen; (Lo-Hi)
			BYTE PathName[];
		} Pcomponent[];

The following structure is a complete definition of the Handle/Path structure. Following it is a pseudo code definition:

	LONG	DirectoryBaseOrShortHandle; (Lo-Hi)
	BYTE	VolumeNumber;
	BYTE	HandleFlag;
	BYTE	Data Type Flag;
	BYTE	Reserved[5];
	BYTE	PathComponentCount;
	STRUCT	Pcomponent [PathComponentCount];

The Handle/Path structure can total as much as 913 bytes.

HandleFlag

	#define ShortDirectoryHandle	0x00
	#define DirectoryBase	0x01
	#define NoHandlePresent	0xFF

DataTypeFlag

	#define ASCII_DATA_TYPE	0x00
	#define UTF8_DATA_TYPE	0x01

	if (Handle Flag == Directory Base)
	{
		/* Client passed in Volume Number and Directory Base */
		/* Set Path Base from Directory Base */
	}
	else
	{
		if (Handle Flag == No Handle Present)
		{
		     /* Generate Volume Number from the first Path Component */
		     /* Set path base to 0, & subtract 1 from Path Count */
		}
		if (Handle Flag == Short Directory Handle)
		{
		     /* Get path base from allocated short directory handle */
                 /* Get Volume Number from Directory Handle table entry */
		}
		/* check to see if more components present */
		if ( Path Count > 1)
		{
		     /* find last component */
		     /* Map path to last component */
		     /* Set the Path Base */
		}
	}
	/* return updated Volume Number, Path Base */

NOTE: The Rename File/SubDir NCP uses a slightly modified EnhNetWareHandlePathStruct.

NetWare Trustee Structure Definition

The Trustee structure is only applicable to the following v3.1 NCPs:

	Add Trustee Set To File or SubDirectory
	Delete Trustee Set From File or SubDirectory
	Scan File or SubDirectory For Trustees

The trustee structure is shown below, the structure consists of a Object ID and the Trustee Rights. The number of structure items is determined by the value of the ObjectIDCount field in the packet.

	LONG	ObjectID; (Hi-Lo)
	WORD	TrusteeRights; (Lo-Hi)

Name Space Information Bit Mask

The NSInfoBitMask is used to get Name Space information from or set Name Space information to a requested Name Space module. The client determines which bits of the NSInfoBitMask are valid by calling the Query NS Information Format NCP (0x2222 87 23) and passing in a requested volume and name space. The NCP returns information from the following set of bit masks to indicate the size and arrangement of name space specific information:

	Offset	Field								Type
	0	FixedBitMask (fixed length--sized)				long
	4	VariableBitMask (variable length--byte length preceded string)	long
	8	HugeBitMask (huge length--word length preceded string)		long
	12	FixedBitsDefined (number of fixed bits defined)			word
	14	VariableBitsDefined (number of variable bits defined)		word
	16	HugeBitsDefined (number of huge bits defined)			word
	18	NSFieldsLengthTable (length of name space fields)		long[32]

As listed above, this NCP returns bits defined in the three masks: FixedBitMask, VariableBitMask, and HugeBitMask. However, as the NCP examines each bit position, although there are three masks, only one mask can have that bit position set. Also shown above, this NCP returns a count of how many bits are set for each bit mask. The NSFieldsLengthTable contains the length of the information relative to any of the tree masks. As shown below, the name space information bit mask is produced by combining information from the three masks.

	Fixed Bit Mask
	       
	    x  x  x  x  x  x  x   ...   x  x  x  x  x  x  x  >
	           
	                                                                         

	Variable Bit Mask                                                        
	           
	    x  x  x  x  x  x  x   ...   x  x  x  x  x  x  x  >
	           
	                                                                         

	Huge Bit Mask                                                            
	           
	    x  x  x  x  x  x  x   ...   x  x  x  x  x  x  x  >
	           
	                                                                          

	NSInfoBitMask                                                            
	.OR.                                                                     
	            
	    x  x  x  x  x  x  x   ...   x  x  x  x  x  x  x  <
	      

By using the NSInfoBitMask, the client can request the information needed by setting the appropriate bit to a 1. If the information is not needed, the bit is set to 0.

Note also that the bit position zero is defined to be a fixed length field containing the File Name (byte length preceded). This is true for all name spaces, the fixed length width will change between names space.

Example of NSInfoBitMask retrieving DOS information

The following is an example of information from the server returned in the QueryNSInformationFormat for the DOS name space.

DOS Name Space FieldsLengthTable Definition (BYTES[ ])
12,4,2,2,4,2,2,4,2,2,4,2,4,4,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0

Definition of the DOS Name Space NSInfoBitMask (Know only by Client & Name Space Module):

By passing this NSInfoBitMask, a client can get information about a DOS Name space entry or set the information via the appropriate NCP.

Example of GetNSInformation Reply Packet

		.
		. Reply Control
		.
                   BYTE FileName&LengthByte[13];
                   LONG FileAttributes; (Lo-Hi)
                   WORD CreateDate; (Lo-Hi)
                   WORD CreateTime; (Lo-Hi)
                   LONG OwnerID; (Hi-Lo)
                   WORD ArchiveDate; (Lo-Hi)
                   WORD ArchiveTime; (Lo-Hi)
                   LONG ArchiveID; (Hi-Lo)
                   WORD ModifyDate; (Lo-Hi)
                   WORD ModifyTime; (Lo-Hi)
                   LONG ModifyID; (Hi-Lo)
                   WORD LastAccessDate; (Lo-Hi)
                   LONG InheritanceRightsMask; (Lo-Hi)
                   LONG MaximumSpace; (Lo-Hi)

Modifying DOS Files or SubDirectories

This section illustrates the ModifyDOSInfoMask and the ModifyDOSInfoStructure. The ModifyDOSInfoMask tells the server what information in the ModifyDOSInfoStructure is valid. The ModifyDOSInfoStructure structure is used to set DOS specific information in files or subdirectories when the default Name Space is not DOS.

ModifyDOSInfoStructure

	struct	{
		WORD FileAttributes; (Lo-Hi)
		BYTE FileMode;
		BYTE FileXAttributes;
		WORD CreationDate; (Lo-Hi)
		WORD CreationTime; (Lo-Hi)
		LONG CreatorsID; (Hi-Lo)
		WORD ModifiedDate; (Lo-Hi)
		WORD ModifiedTime; (Lo-Hi)
		LONG ModifiersID; (Hi-Lo)
		WORD ArchivedDate; (Lo-Hi)
		WORD ArchivedTime; (Lo-Hi)
		LONG ArchiversID; (Hi-Lo)
		WORD LastAcessDate; (Lo-Hi)
		WORD InheritanceGrantMask; (Lo-Hi)
		WORD InheritanceRevokeMask; (Lo-Hi)
		LONG MaximumSpace; (Lo-Hi)
	};

Remarks

MaximumSpace: This field specifies the user disk space restriction that may have been enabled by an administrator and might be in place for a given user.

v2.x	v3.x	v4.x	v5.x	v65.sp2 and newer
				•

Request Format

	Offset	Content				Type
	(request header)
	6	FunctionCode	(89)		byte
	7	SubFunction	(10)		byte
	8	NameSpace			byte
	9	reserved	(0)		byte
	10	SearchAttributes		word (Lo-Hi)
	12	TrusteeRightsMask (See below)	word (Lo-Hi)
	14	ObjectIDCount			word (Lo-Hi)
	16	TrusteeStruct[]			structure (see definition below)
	xx	EnhNWHandlePathStruct		structure

Reply Format

	Offset	Content				Type
	(reply header)

Completion Code

	0	SUCCESSFUL

Remarks

The SearchAttributes field is explained in more detail in the Introduction to Enhanced File System NCPs.

If the TrusteeRightsMask field is set to -1, the individual TrusteeRights should be set to the appropriate rights for each entry in the Trustee Structure.

The TrusteeStruct structure is a variable length structure whose entries are 6 bytes each. The number of TrusteeStruct entries is input in the ObjectIDCount field. The EnhNWHandlePathStruct structure will begin directly after the last entry in the TrusteeStruct. This can be determined by multiplying the number in the ObjectIDCount field by the sizeof TrusteeStruct (6 bytes). Care should be taken to balance the number of input TrusteeStruct entries with the length of the path components in the EnhNWHandlePathStruct. If the path components don't take up much space, more TrusteeStruct entries can be passed. If the length of the path components take up a large amount of buffer space, then the number of TrusteeStruct entries should be reduced. The TrusteeStruct structure is as follows:

	typedef	struct
	{
		LONG	ObjectID; (Hi-Lo)
		WORD	TrusteeRights; (Lo-Hi)
	}TrusteeStruct;

Note that the EnhNWHandlePathStruct parameter is of type EnhNetWareHandlePathStruct; therefore, when you search for information on this parameter in the Introduction to Enhanced File System NCPs, you must search for the EnhNetWareHandlePathStruct. See the "NetWare Handle and Path Structure Definition" explanation in the Enhanced File System NCPs" section.

v2.x	v3.x	v4.x	v5.x	v65.sp2 and newer
				•

Request Format

	Offset	Content				Type
	(request header)
	6	FunctionCode	(89)		byte
	7	SubFunction	(12)		byte
	8	NameSpace			byte
	9	DstNameSpace			byte
	10	AllocateMode			word (Lo-Hi)
	12	EnhNWHandlePathStruct		structure

Reply Format

	Offset	Content				Type
	(reply header)
	8	DirectoryHandle			byte
	9	VolumeNumber			byte
	10	reserved[4]	(0)		byte

Completion Code

0 SUCCESSFUL

Remarks

The DstNameSpace parameter is ignored unless the high bit in the AllocateMode field is set (0x8000). If the DstNameSpace field is ignored, then the NameSpace field indicates what name space the allocation will take place in. The DstNameSpace parameter allows calling this NCP in one name space and doing the actual allocation in another.

The AllocateMode field can be set as shown below:

AllocateMode bits may have the following values:

	Offset	Content				Type
	(reply header)
	8	Volume			long
	12	DirectoryBase		long
	16	DOSDirectoryBase	long
	20	NameSpace		long
	24	DirectoryHandle		byte

	Offset	Content			Type
	(request header)
	6	FunctionCode	(89)	byte
	7	SubFunction	(08)	byte
	8	NameSpace		byte
	9	reserved	(0)	byte
	10	SearchAttributes 	word (Lo-Hi)
	12	EnhNWHandlePathStruct	structure

	Offset	Content			Type
	(reply header)

	0	SUCCESSFUL

	Offset	Content			Type
	(request header)
	6	FunctionCode	(89)	byte
	7	SubFunction	(11)	byte
	8	NameSpace		byte
	9	reserved	(0)	byte
	10	ObjectIDCount	 	word (Lo-Hi)
	12	TrusteeStruct		structure (see definition below)
	xx	EnhNWHandlePathStruct	structure

	Offset	Content			Type
	(reply header)

	0	SUCCESSFUL

	typedef	struct
	{
		LONG	ObjectID; (Hi-Lo)
		WORD	TrusteeRights; (Lo-Hi)
	}TrusteeStruct;

	Offset	Content			Type
	(request header)
	6	FunctionCode	(89)	byte
	7	SubFunction	(22)	byte
	8	srcNameSpace		byte
	9	dstNameSpace	(0)	byte
	10	dstNSIndicator		word
	12	EnhNWHandlePathStruct	structure

	Offset	Content			Type
	(reply header)
	8	NSDirectoryBase		long (Lo-Hi)
	12	DOSDirectoryBase	long (Lo-Hi)
	16	VolumeNumber		byte

	0	SUCCESSFUL

	Offset	Content			Type
	(request header)
	6	FunctionCode	(89)	byte
	7	SubFunction	(29)	byte
	8	NameSpace		byte
	9	DestNameSpace		byte
	10	SearchAttributes 	word (Lo-Hi)
	12	ReturnInfoMask	  	long (Lo-Hi)
	16	EnhNWHandlePathStruct	structure

	Offset	Content			Type
	(reply header)
	8	MyEffectiveRights	word (Lo-Hi)
	10	NetWareInfoStruct	structure
	xx	EnhNetWareFileNameStruct	structure

	0	SUCCESSFUL

	Offset	Content			Type
	(request header)
	6	FunctionCode	(89)	byte
	7	SubFunction	(28)	byte
	8	SrcNameSpace		byte
	9	DstNameSpace		byte
	10	PathCookie (See below)	structure
	20	EnhNWHandlePathStruct	structure

	Offset	Content			Type
	(reply header)
	8	PathCookie		structure
	18	PathComponentSize	word (Lo-Hi)
	20	PathComponentCount (See below)	word (Lo-Hi)
	22	PathComponents[] (See below)	structure

	0	SUCCESSFUL

	struct PathCookie
	{
	       word Flags;  (Lo-Hi)
	       long Cookie1; (Lo-Hi)
	       long Cookie2; (Lo-Hi)
	};

		(ASCII data type)
		struct PathComponent
		{
		       BYTE  pathLength;
		       byte  string[];
		};

		(UTF8 data type)
		struct PathComponent
		{
		       WORD  pathLength;
		       byte  string[];
		};

	Offset	Content			Type
	(request header)
	6	FunctionCode	(89)	byte
	7	SubFunction	(19)	byte
	8	SrcNameSpace		byte
	9	DstNameSpace		byte
	10	DataTypeFlag		byte
	11	VolumeNumber		byte
	12	DirectoryBase 		long (Lo-Hi)
	16	NSInfoBitMask (See Intro) long (Lo-Hi)

	Offset	Content				Type
	(reply header)
	8	NSSpecificInfo[1024] (See Intro)	byte

	0	SUCCESSFUL

	Offset	Content			Type
	(request header)
	6	FunctionCode	(89)	byte
	7	SubFunction	(02)	byte
	8	NameSpace		byte
	9	reserved	(0)	byte
	10	EnhNWHandlePathStruct 	structure

	Offset	Content	 		Type
	(reply header)
	8	VolumeNumber		byte
	9	DirectoryNumber		long (Lo-Hi)
	13	EntryNumber		long (Lo-Hi)

	0	SUCCESSFUL

	Offset	Content			Type
	(request header)
	 6	FunctionCode	(89)	byte
	 7	SubFunctionCode	(35)	byte
	 8	NameSpace		byte
	 9	Flags			byte
	10	SearchAttributes	word (Lo-Hi)
	12	AttributeMask		long (Lo-Hi)
	16	Attributes		long (Lo-Hi)
	20	EnhNWHandlePathStruct	structure

	Offset	Content			Type
	(reply header)
	8	ItemsChecked		long (Lo-Hi)
	12	ItemsChanged		long (Lo-Hi)
	16	AttributeValidFlag	long (Lo-Hi)
	20	NewAttributes		long (Lo-Hi)

	0	0x00	Successful

	Offset	Content				Type
	(request header)
	6	FunctionCode	(89)		byte
	7	SubFunction	(07)		byte
	8	NameSpace			byte
	9	reserved	(0)		byte
	10	SearchAttributes (See Intro)	word (Lo-Hi)
	12	ModifyDOSInfoMask (See Intro)	long (Lo-Hi)
	16	ModifyDOSInfoStruct (See Intro)	structure
	54	EnhNWHandlePathStruct (See Intro)	structure

	Offset	Content				Type
	(reply header)

	0	SUCCESSFUL

	Offset	Content			Type
	(request header)
	6	FunctionCode	(89)	byte
	7	SubFunction	(06)	byte
	8	NameSpace		byte
	9	DestNameSpace		byte
	10	SearchAttributes	word (Lo-Hi)
	12	ReturnInfoMask		long (Lo-Hi)
	16	EnhNWHandlePathStruct	structure

	Offset	Content			Type
	(reply header)
	8	NetWareInfoStruct	structure
	xx	EnhNetWareFileNameStruct	structure

	0	SUCCESSFUL

	Offset	Content				Type
	(request header)
	6	FunctionCode	(89)		byte
	7	SubFunction	(01)		byte
	8	NameSpace			byte
	9	OpenCreateMode (See below)	byte
	10	SearchAttributes		word (Lo-Hi)
	12	ReturnInfoMask			long (Lo-Hi)
	16	CreateAttributes		long (Lo-Hi)
	20	DesiredAccessRights (See below)	word (Lo-Hi)
	22	EnhNWHandlePathStruct  		structure

	Offset	Content				Type
	(reply header)
	8	FileHandle			long (Hi-Lo)
	12	OpenCreateAction (See below)	byte
	13	Reserved			byte
	14	NetWareInfoStruct		structure
	xx	EnhNetWareFileNameStruct		structure

	0	SUCCESSFUL

The SearchAttributes field allows you to designate the following create/open options:

• you are creating/opening a hidden or system file
• you are creating only a subdirectory
• you are creating a subdirectory or creating/opening any normal file

The ReturnInfoMask allows you to request from the server specific information about a file/subdirectory. Information such as creation date/time, attributes, inherited rights, name space, etc. is returned in the NetWareInfoStruct structure. The file/subdirectory name and length are returned in the EnhNetWareFileNameStruct structure. More information on the ReturnInfoMask (request parameter), NetWareInfoStruct (reply parameter), and the EnhNetWareFileNameStruct (reply parameter) are given in the Introduction to Enhanced File System NCPs.

The CreateAttributes field is used to set the attributes in the DOS name space.

The DesiredAccessRights parameter, as shown below, allows you to designate the access rights of the file being created. Beginning with NetWare 4.10, a file can be opened as a temporary file that will be deleted when the file is closed.
IMPORTANT NOTE: If the item being created is a subdirectory, then the DesiredAccessRights parameter is used as an Inherited Rights Filter. See Inherited Rights Mask definition below. Typically you would want all rights in the Inherited Rights Mask Definition and would pass a 0xFF.

To create a temporary file, the caller must set the DELETE_FILE_CLOSE_BIT (0x0400), the DENY_READ_BIT, and the DENY_WRITE_BIT in the desired access rights field. Temporary files by definition do not allow shared I/O access. This file will exist until the caller closes the file, which will cause the file to be deleted.

The OS will create temporary files with the HIDDEN_BIT set, so that they will not be visible. Also the IMMEDIATE_COMPRESS_BIT is masked off from the created attributes supplied by the caller.