Novell Doc: NDK: Libraries for C (LibC), Volume 2

30.8.1 Event Hooks for NSS Volumes

On NSS volumes, you can register to be notified when an event starts or after the event has completed. The fs_register and fs_unregister functions use the following flags for this notification process.

Event: Description	Value	Return Structure
FSHOOK_TYPE_DELETE_WARN: Notifies when someone requests to delete a file system object.	0	del_warn_t
FSHOOK_TYPE_DELETE_REPORT: Notifies when someone has successfully deleted a file system object.	1	del_report_t
FSHOOK_TYPE_CREATE_WARN: Notifies when someone requests to create a file system object.	2	create_warn_t
FSHOOK_TYPE_CREATE_REPORT: Notifies when someone has successfully created a file system object.	3	create_report_t
FSHOOK_TYPE_OPEN_WARN: Notifies when someone requests to open a file system object.	4	open_warn_t
FSHOOK_TYPE_OPEN_REPORT: Notifies when someone has successfully opened a file system object.	5	open_report_t
FSHOOK_TYPE_CLOSE_WARN: Notifies when someone requests to close a file system object.	6	close_warn_t
FSHOOK_TYPE_CLOSE_REPORT: Notifies when someone has successfully closed a file system object.	7	close_report_t
FSHOOK_TYPE_RENAME_WARN: Notifies when someone requests to rename a file system object.	8	ren_warn_t
FSHOOK_TYPE_RENAME_REPORT: Notifies when someone has successfully renamed a file system object.	9	ren_report_t
FSHOOK_TYPE_MODIFYINFO_WARN: Notifies when someone requests to modify the information about a file system object.	10	mod_warn_t
FSHOOK_TYPE_MODIFYINFO_REPORT: Notifies when someone has successfully modified information about a file system object.	11	mod_report_t
FSHOOK_TYPE_SETDATASIZE_WARN: Notifies when someone requests to set the size for a file system object.	12	setsize_warn_t
FSHOOK_TYPE_SETDATASIZE_REPORT: Notifies when someone has successfully set the size for a file system object.	13	setsize_report_t
FSHOOK_TYPE_ADDTRUSTEE_WARN: Notifies when someone requests to add a trustee assignment to a file system object.	14	addtrustee_warn_t
FSHOOK_TYPE_ADDTRUSTEE_REPORT: Notifies when someone has successfully added a trustee assignment to a file system object.	15	addtrustee_report_t
FSHOOK_TYPE_REMOVETRUSTEE_WARN: Notifies when someone requests to remove a trustee assignment from a file system object.	16	remtrustee_warn_t
FSHOOK_TYPE_REMOVETRUSTEE_REPORT: Notifies when someone has successfully removed a trustee assignment from a file system object.	17	remtrustee_report_t
FSHOOK_TYPE_SETINHERITEDRIGHTS_WARN: Notifies when someone requests to set the inherited rights mask of a file system object.	18	setrights_warn_t
FSHOOK_TYPE_SETINHERITEDRIGHTS_REPORT: Notifies when someone has successfully set the inherited rights mask of a file system object.	19	setrights_report_t
FSHOOK_TYPE_CHANGEVOLSTATE_WARN: Notifies when someone requests to change the state of a volume.	20	xvolstate_warn_t
FSHOOK_TYPE_CHANGEVOLSTATE_REPORT: Notifies when someone has successfully changed the state of a volume.	21	xvolstate_report_t
FSHOOK_TYPE_CHANGEPOOLSTATE_WARN: Notifies when someone requests to change the state of a pool.	22	xpoolstate_warn_t
FSHOOK_TYPE_CHANGEPOOLSTATE_REPORT: Notifies when someone has successfully changed the state of a pool.	23	xpoolstate_report_t

30.8.2 Event Hooks for Traditional Volumes

On traditional volumes, you can register to be notified when an event starts or after the event has completed. The fs_register and fs_unregister functions use the following flags for this notification process. The FSHOOK_PRE flags notify you when a request has been received and before the operating system has serviced the request. The FSHOOKS_POST flags notify you when the operaing system has successfully completed the request. You can use the generic hooks and the name space entry changing hook for monitioring changes from all client types. The first ten sets of hooks are for DOS clients only.

Flag: Description	Value	Structure
FSHOOK_PRE_ERASEFILE: Notifies when a DOS client requests to delete a file.	0	EraseFileCallBackStruct
FSHOOK_POST_ERASEFILE: Notifies when a DOS client has successfully deleted a file.	0x80000000	EraseFileCallBackStruct
FSHOOK_PRE_OPENFILE: Notifies when a DOS client requests to open a file.	1	OpenFileCallBackStruct
FSHOOK_POST_OPENFILE: Notifies when a DOS client has successfully opened a file.	0x80000001	OpenFileCallBackStruct
FSHOOK_PRE_CREATEFILE: Notifies when a DOS client requests to create a file.	2	CreateFileCallBackStruct
FSHOOK_POST_CREATEFILE: Notifies when a DOS client has successfully created a file.	0x80000002	CreateFileCallBackStruct
FSHOOK_PRE_CREATE_OPENFILE: Notifies when a DOS client requests to create and open a file.	3	CreateAndOpenCallBackStruct
FSHOOK_POST_CREATE_OPENFILE: Notifies when a DOS client has successfully created and opened a file.	0x80000003	CreateAndOpenCallBackStruct
FSHOOK_PRE_RENAME_OR_MOVE: Notifies when a DOS client requests to rename or move a file.	4	RenameMoveEntryCallBackStruct
FSHOOK_POST_RENAME_OR_MOVE: Notifies when a DOS client has successfully renamed or moved a file system object.	0x80000004	RenameMoveEntryCallBackStruct
FSHOOK_PRE_CLOSEFILE: Notifies when a DOS client requests to close a file.	5	CloseFileCallBackStruct
FSHOOK_POST_CLOSEFILE: Notifies when a DOS client has successfully closed a file system object	0x80000005	CloseFileCallBackStruct
FSHOOK_PRE_CREATEDIR: Notifies when a DOS client requests to create a directory.	6	CreateDirCallBackStruct
FSHOOK_POST_CREATEDIR: Notifies when a DOS client has successfully created a directory.	0x80000006	CreateDirCallBackStruct
FSHOOK_PRE_DELETEDIR: Notifies when a DOS client requests to delete a directory.	7	DeleteDirCallBackStruct
FSHOOK_POST_DELETEDIR: Notifies when a DOS client has successfully deleted a directory.	0x80000007	DeleteDirCallBackStruct
FSHOOK_PRE_MODIFY_DIRENTRY: Notifies when a DOS client requests to modify a file system object.	8	ModifyDirEntryCallBackStruct
FSHOOK_POST_MODIFY_DIRENTRY: Notifies when a DOS client has successfully modified a file system object.	0x80000008	ModifyDirEntryCallBackStruct
FSHOOK_PRE_SALVAGE_DELETED: Notifies when a DOS client requests to salvage a deleted file.	9	SalvageDeletedCallBackStruct
FSHOOK_POST_SALVAGE_DELETED: Notifies when a DOS client has successfully salvaged a deleted file system object.	0x80000009	SalvageDeletedCallBackStruct
FSHOOK_PRE_PURGE_DELETED: Notifies when a DOS client requests to purge a deleted file.	10	PurgeDeletedCallBackStruct
FSHOOK_POST_PURGE_DELETED: Notifies when a DOS client has successfully purged a deleted file system object.	0x8000000A	PurgeDeletedCallBackStruct
FSHOOK_PRE_RENAME_NS_ENTRY: Notifies when a client requests to rename an entry.	11	RenameNSEntryCallBackStruct
FSHOOK_POST_RENAME_NS_ENTRY: Notifies when a client has successfully renamed an entry.	0x8000000B	RenameNSEntryCallBackStruct
FSHOOK_PRE_GEN_SALVAGE_DELETED: Notifies when a client requests to salvage a deleted entry.	12	GenericSalvageDeletedCBStruct
FSHOOK_POST_GEN_SALVAGE_DELETED: Notifies when a client has successfully salvaged a deleted entry.	0x8000000C	GenericSalvageDeletedCBStruct
FSHOOK_PRE_GEN_PURGE_DELETED: Notifies when a client requests to purge a deleted entry.	13	GenericPurgeDeletedCBStruct
FSHOOK_POST_GEN_PURGE_DELETED: Notifies when a client has successfully purged a deleted entry.	0x8000000D	GenericPurgeDeletedCBStruct
FSHOOK_PRE_GEN_OPEN_CREATE: Notifies when a client requests to open an entry.	14	GenericOpenCreateCBStruct
FSHOOK_POST_GEN_OPEN_CREATE: Notifies when a client has successfully opened an entry.	0x8000000E	GenericOpenCreateCBStruct
FSHOOK_PRE_GEN_RENAME Notifies when a client requests to rename an entry.	15	GenericRenameCBStruct
FSHOOK_POST_GEN_RENAME: Notifies when a client has successfully renamed an entry.	0x8000000F	GenericRenameCBStruct
FSHOOK_PRE_GEN_ERASEFILE: Notifies when a client requests to delete an entry.	16	GenericEraseFileCBStruct
FSHOOK_POST_GEN_ERASEFILE: Notifies when a client has successfully deleted an entry.	0x80000010	GenericEraseFileCBStruct
FSHOOK_PRE_GEN_MODIFY_DOS_INFO: Notifies when a client requests to modify generic DOS information for an entry.	17	GenericModifyDOSInfoCBStruct
FSHOOK_POST_GEN_MODIFY_DOS_INFO: Notifies when a client has successfully modified the generic DOS information for an entry.	0x80000011	GenericModifyDOSInfoCBStruct
FSHOOK_PRE_GEN_MODIFY_NS_INFO: Notifies when a client requests to modify the generic name space information for an entry.	18	GenericModifyNSInfoCBStruct
FSHOOK_POST_GEN_MODIFY_NS_INFO: Notifies when a client has successfully modified the generic name space information for an entry.	0x80000012	GenericModifyNSInfoCBStruct

30.8.3 File Object Types

The create_warn_t structure uses these flags, which are defined in fshooks.h.

Flag	Value	Description
FSHOOK_FTYP_UNKNOWN	0	The file type is unknown.
FSHOOK_FTYP_REGULAR	1	A normal data file or directory.
FSHOOK_FTYP_EXTENDED_ ATTR	2	An extended attribute. Arbitrary meta-data can be attached to a file.
FSHOOK_FTYP_NAMED_DATA_ STREAM	3	An additional stream attached to a file. Used to implement resource forks for Macintosh support.
FSHOOK_FTYP_PIPE	4	A named pipe. Not currently supported.
FSHOOK_FTYP_VOLUME	5	A volume, which contains a set of files and directories.
FSHOOK_FTYP_POOL	6	A pool, which contains storage that may be used by volumes.

30.8.4 Modify Info Mask Values

The modifyInfoMask parameter is a bit mask that specifies the file object information that is going to be modified. If a bit is set in this bit mask, the corresponding field of zinfo_t structure contains information about what is being modified. All other fields in the zinfo_t structure (for which the bits are not set) are ignored. If a bit doesn’t make sense for a particular file object, it is ignored. These flags are defined in fshooks.h.

Flag	Value	Description
FSHOOKS_MOD_FILE_ ATTRIBUTES	0x00000001	Modify the file object’s attributes.
FSHOOKS_MOD_CREATED_ TIME	0x00000002	Modify the file object’s creation time.
FSHOOKS_MOD_ARCHIVED_ TIME	0x00000004	Modify the file object’s last archived time.
FSHOOKS_MOD_MODIFIED_ TIME	0x00000008	Modify the file object’s last modified time.
FSHOOKS_MOD_ACCESSED_ TIME	0x00000010	Modify the file object’s last accessed time.
FSHOOKS_MOD_METADATA_ MODIFIED_TIME	0x00000020	Modify the file object’s last meta-data modified time.
FSHOOKS_MOD_OWNER_ID	0x00000040	Modify the file object’s owner ID.
FSHOOKS_MOD_ARCHIVER_ID	0x00000080	Modify the file object’s archiver ID.
FSHOOKS_MOD_MODIFIER_ID	0x00000100	Modify the file object’s modifier ID.
FSHOOKS_MOD_METADATA_ MODIFIER_ID	0x00000200	Modify the file object’s meta-data modifier ID.
FSHOOKS_MOD_PRIMARY_ NAMESPACE	0x00000400	Modify the file object’s primary name space ID.
FSHOOKS_zMOD_DELETED_ INFO	0x00000800	Modify the file object’s deleted info. If the file object is not deleted, this is ignored.
FSHOOKS_MOD_MAC_ METADATA	0x00001000	Modify the file object’s Macintosh meta-data.
FSHOOKS_MOD_UNIX_ METADATA	0x00002000	Modify the file object’s UNIX metadata.
FSHOOKS_MOD_EXTATTR_ FLAGS	0x00004000	If the file object is an extended attribute, modify the value of the extAttrUserFlags.
FSHOOKS_MOD_VOL_ ATTRIBUTES	0x00008000	If the file object is a volume, enable or disable features associated with this volume.
FSHOOKS_MOD_VOL_NDS_ OBJECT_ID	0x00010000	If the file object is a volume, modify the value of the directory object ID that identifies this volume in the directory tree.
FSHOOKS_MOD_VOL_MIN_ KEEP_SECONDS	0x00020000	If the file object is a volume, modify the value of salvage.minKeepSeconds. This is the minimum number of seconds that a deleted file will remain on the volume before it becomes a candidate for auto purging.
FSHOOKS_MOD_VOL_MAX_ KEEP_SECONDS	0x00040000	If the file object is a volume, modify the value of salvage.maxKeepSeconds. This is the maximum number of seconds that a deleted file will remain on the volume before it must be auto purged.
FSHOOKS_MOD_VOL_LOW_ WATER_MARK	0x00080000	If the file object is a volume, modify the value of salvage.lowWaterMark. This is an integer percentage value. If the percentage of free space on the volume falls below this value, auto purging will be initiated.
FSHOOKS_zMOD_VOL_HIGH_ WATER_MARK	0x00100000	If the file object is a volume, modify the value of salvage.highWaterMark. This is an integer percentage value. If the percentage of free space on the volume rises above this value, auto purging will be terminated.
FSHOOKS__MOD_POOL _ATTRIBUTES	0x00200000
FSHOOKS__MOD_POOL_NDS_ OBJECT_ID	0x00400000	If the file object is a pool, modify the value of the directory object ID that identifies this pool in the directory tree.
FSHOOKS__MOD_VOL_DATA_ SHREDDING_COUNT	0x00800000
FSHOOKS__MOD_VOL_QUOTA	0x01000000
FSHOOKS__MOD_DIR_QUOTA	0x02000000
FSHOOKS__MOD_READ_ AHEAD_BLOCKS	0x04000000

30.8.5 NetWare File Attributes

An attribute bit mask can contain one or more of the following. Most of these flags are defined in fsio.h; a few are defined in fshooks.h.

Flag	Value
ATTR_NORMAL	0x00000000
ATTR_READ_ONLY	0x00000001	Prevents a file from being modified. This attribute automatically sets Delete Inhibit and Rename Inhibit.
ATTR_HIDDEN	0x00000002	Hides directories and files so they cannot be listed using the DIR command.
ATTR_SYSTEM	0x00000004	Hides the directory or file so it cannot be seen by using the DIR command. System is normally used with operating system files, such as DOS system files.
ATTR_EXECUTE	0x00000008	Prevents the file from being copied, modified, or backed up. It does allow renaming. The only way to remove this attribute is to delete the file. Use the attribute for program files such as .exe or .com. Make a copy of a file before you flag it as Execute Only, so you can replace the file if it becomes corrupted.
ATTR_VOLUME_ID	0x00000008	Indicates the entry has a volume label.
ATTR_DIRECTORY	0x00000010	Indicates the entry is a subdirectory.
ATTR_ARCHIVE	0x00000020	Identifies files that have been modified since the last backup. This attribute is assigned automatically.
ATTR_SHARE	0x00000080	Allows more than one user to access the file at the same time. This attribute is usually used with Read Only.
FSHOOKS_FA_SMODE_BITS	0x00000700	Contains a series of three bits, which the file system reserves and stores, but has no knowledge of their usage or interpretation. These bits are manipulated by clients, and are used as a place to store search modes associated with a file.
ATTR_NO_SUBALLOC	0x00000800	Prevents file data from being suballocated.
ATTR_TRANS	0x00001000	Allows a file to be tracked and protected by the Transaction Tracking System™ (TTS™).
FSHOOKS_FA_NOT_VIRTUAL_ FILE	0x00002000	Indicates the file is not a virtual file. This attribute is only valid on an NSS volume that has enabled the virtual file feature.
ATTR_READAUD	0x00004000	Indicates the file is audited for reading. Not supported on NSS volumes.
ATTR_WRITAUD	0x00008000	Indicates the file is audited for writing. Not supported on NSS volumes.
ATTR_IMMPURG	0x00010000	Flags a directory or file to be erased from the system as soon as it is deleted. Purged directories and files cannot be recovered.
ATTR_NORENAM	0x00020000	Prevents the directory or file name from being modified.
ATTR_NODELET	0x00040000	Prevents the directory or file from being deleted. This attribute overrides the Erase trustee right.
ATTR_NOCOPY	0x00080000	Prevents Macintosh users from copying a file. This attribute overrides Read and File Scan trustee rights.
FSHOOKS_FA_IS_ADMIN_LINK	0x00100000
ATTR_FILE_MIGRATED	0x00400000	Indicates that the directory or file has been migrated from the server's disk to another storage medium. Not supported on NSS volumes.
ATTR_DONT_MIGRATE	0x00800000	Prevents directories and files from being migrated from the server’s disk to another storage medium. Not supported on NSS volumes.
ATTR_IMMEDIATE_COMPRESS	0x02000000	Sets data to be compressed as soon as a file is closed. If applied to a directory, every file in the directory is compressed as each file is closed.
ATTR_FILE_COMPRESSED	0x04000000	Indicates that the file has been compressed.
ATTR_DONT_COMPRESS	0x08000000	Keeps data from being compressed. This attribute overrides settings for automatic compression of files not accessed within a specified number of days.
ATTR_CANT_COMPRESS	0x20000000	Indicates that the data cannot be compressed.
ATTR_ATTR_ARCHIVE	0x40000000	Indicates the file has been modified
FSHOOKS_FA_VOLATILE	0x80000000	Prevents opportunistic locks from being returned. It also indicates that, even if you have the file open for read only, the contents can change. For example, if you read the same location from the file twice, you can get two different answers. The end-of-file marker is not well defined for files marked with this attribute.

30.8.6 Requested Rights

The requested right bits are not stored with the file; they are temporary bits associated with an open instance of the file. The open_warn_t and create_warn_t structures use these flags. They are defined in the fshooks.h file.

Flag	Value	Description
FSHOOKS_RR_READ_ACCESS	0x00000001	Read access is requested on the open file handle.
FSHOOKS_RR_WRITE_ACCESS	0x00000002	Write access is requested on the open file handle.
FSHOOKS_RR_DENY_READ	0x00000004	Deny read access is requested on the open file handle. No other readers should be allowed to have the file open.
FSHOOKS_RR_DENY_WRITE	0x00000008	Deny write access is requested on the open file handle. No other writers should be allowed to have the file open.
FSHOOKS_RR_SCAN_ACCESS	0x00000010	Scan access is requested on the file object.
FSHOOKS_RR_ENABLE_IO_ ON_COMPRESSED_DATA	0x00000100	Rather than reading the decompressed version of the data stream, read the compressed version of the data stream. The zERR_DENY_WRITE bit must also be set for this compression flag to work.
FSHOOKS_RR_LEAVE_FILE_ COMPRESSED	0x00000200	Keep the compressed version of the file even after decompressing it.
FSHOOKS_RR_DELETE_FILE_ ON_CLOSE	0x00000400	When the file is closed, delete the file.
FSHOOKS_RR_FLUSH_ON_ CLOSE	0x00000800	Flush the user and meta-data for the file when it is closed. If the file is closed by the system because of a disconnect, the data is still flushed.
FSHOOKS_RR_PURGE_ IMMEDIATE_ON_CLOSE	0x00001000	Purge the file when it is closed. This bit works with zRR_DELETE_FILE_ON_CLOSE to keep the file from being placed in the salvage system when it is deleted on close.
FSHOOKS_RR_DIO_MODE	0x00002000	Open the file in direct I/O mode. This bit replaces the need to make a separate call to change to direct I/O mode.
FSHOOKS_RR_ALLOW_ SECURE_DIRECTORY_ACCESS	0x00020000
FSHOOKS_RR_TRANSACTION_ ACTIVE	0x00100000	Have the file use the default transaction.
FSHOOKS_RR_PSA_CACHE	0x00200000
FSHOOKS_RR_MASK_READ_ IN_DROP_BOXES	0x02000000
FSHOOKS_RR_READ_ ACCESS_TO_SNAPSHOT	0x04000000
FSHOOKS_RR_DENY_RW_ OPENER_CAN_REOPEN	0x08000000
FSHOOKS_RR_CREATE_ WITHOUT_READ_ACCESS	0x10000000	When the file is created, grant only write access to the file.
FSHOOKS_RR_OPENER_CAN_ DELETE_WHILE_OPEN	0x20000000	While the file is opened, allow only the opener of the file to delete the file.
FSHOOKS_RR_CANT_DELETE_ WHILE_OPEN	0x40000000	While the file is opened, it cannot be deleted.
FSHOOKS_RR_DONT_ UPDATE_ACCESS_TIME	0x80000000	Not implemented.When the file is opened, the meta-data last accessed time should not be updated. Intended to let the clients access the icon information without causing a change in the files meta-data that would eventually have to be written to disk.

30.8.7 Rights Flags

The following flags are ORed together to form a bit mask of a user's effective rights to a file or directory. These same flags are used to set the Inherited Rights Mask. Most of these flags are defined in the nks/dirio.h file. A few are also defined in fshooks.h for NSS volumes.

Flag	Value	Description
NX_READ_EXISTING_FILE	0x00000001	Grants the trustee the ability to open and read the file or folder and any subordinate items. This includes the ability to execute program files.
NX_WRITE_EXISTING_FILE	0x00000002	Grants the trustee the ability to open and write to (modify) the file or folder and any subordinate items.
NX_CREATE_NEW_ENTRY	0x00000008	Grants the trustee the ability to create new items and salvage deleted items in the folder and any subfolders.
NX_DELETE_EXISTING_ENTRY	0x00000010	Grants the trustee the ability to delete the file or folder and any subordinate items.
NX_CHANGE_ACCESS_CONTROL	0x00000020	Grants the trustee the ability to change the trustee (rights) assignments and inherited rights filter of the file or folder.
NX_SEE_FILES	0x00000040	Grants the trustee the ability to see (in a listing or browser) the file or folder and any subordinate items, including its path back to the root of the volume.
NX_MODIFY_ENTRY	0x00000080	Grants the trustee the ability to change the name and attributes of the file or folder and any subordinate items. The trustee can’t see or modify the actual contents of files.
NX_SUPERVISOR_PRIVELEGES	0x00000100	Grants the trustee all rights to the file or folder and any subordinate items. This right can’t be filtered (blocked) on the current file or folder or on subordinate items, nor can it be revoked on individual subordinate items.
FSHOOKS_AUTHORIZE_SALVAGE	0x00000200	Grants the trustee the right to salvage files in this directory and all of its subdirectories. This is only available on NSS volumes.
FSHOOKS_AUTHORIZE_SECURE	0x00008000
NX_ACCESS_RIGHTS_MASK	0x000001FB	Makes the rights to the selected object flow to all objects below.

30.8.8 Search Attributes for Traditional Volumes

In CLib, defined in nwnamspc.h.

Flag	Value	Description
SA_NORMAL	0x0000	Match all entries except those marked hidden or system.
SA_HIDDEN	0x0002	Match entries marked hidden.
SA_SYSTEM	0x0004	Match entries marked system.
SA_SUBDIR_ONLY	0x0010	Match only subdirectories.
SA_SUBDIR_FILES	0x8000	Match only files found in the subdirectories of the current directory.
SA_ALL	0x8006	Match all entries, including hiddenand system entries and directories.

30.8.9 Volume States

The following flags describe the state of a volume on a NetWare server. The volume state structures (xvolstate_warn_t and xvolstate_report_t) and zinfo_t use these flags.

Flag	Value	Description
FSHOOKS_VOLSTATE_ UNKNOWN	0	The volume is new and not yet available.
FSHOOKS_VOLSTATE_ DEACTIVE	2	The volume is not currently activated.
FSHOOKS_VOLSTATE_ MAINTENANCE	3	The volume is in a maintenance mode.
FSHOOKS_VOLSTATE_ ACTIVE	6	The volume is active and available.

30.8 FSHook Values