Purpose

Attach or detach a remote drive or pseudo-device to an FSD.

Calling Sequence

int far pascal FS_ATTACH(flag, pDev, pvpfsd, pcdfsd, pParm, pLen)
 
unsigned short flag;
char far * pDev;
struct vpfsd far * pvpfsd;
struct cdfsd far * pcdfsd;
char far * pParm;
unsigned short far * pLen;

Where

flag indicates attach or detach:

pDev is a pointer to the ASCIIZ text of either the driver (driver letter followed by a colon) or to the character device (must be \DEV\device) that is being attached, detached, or queried. The FSD does not need to verify this pointer.

tpvpfsd is a pointer to a data structure containing file-system-dependent volume parameter information. When an attach/detach/query of a character device is requested, this pointer is NULL. When attaching a drive, this structure contains no data and is available for the FSD to store information needed to manage the remote drive. All subsequent FSD calls have access to the hVPB in one of the structures passed in, so the FSD has access to this structure by using FSH_GETVOLPARMS. This structure will have its contents as the FSD had left them. When detaching or querying a drive, this structure contains the data as the FSD left them.

pcdfsd is a pointer to a data structure containing file-system dependent working directory information for drives. When attaching a drive, this structure contains no data and is available for the FSD to store information needed to manage the working directory. All subsequent FSD calls generated by API calls that reference this drive are passed a pointer to this structure with contents left as the FSD left them. When detaching or querying a drive, this structure contains the data as the FSD left them. For character devices, pcdfsd points to a DWORD. When a device is attached, the DWORD contains no data, and can be used by the FSD to store a reference to identify the device later on during FS_OPENCREATE, when it is passed in to the FSD. When detaching or querying the device, this DWORD contains the data as the FSD left them.

pParm is the address of the application parameter area.

When an attach is requested, this will point to the API-specified user data block that contains information regarding the attach operation (for example, passwords). For a query, the OS/2 kernel will fill in part of the buffer, adjust the pointer, and call the FSD to fill in the rest (see the structures returned by DosQFSAttach; pParm will point to cbFSAData; the FSD should fill in cbFSAData and rgFSAData.)

Addressing of this data area is not validated by the OS/2 kernel. pParm must be verified, even in the query case. The FSD verifies this parameter by calling the FS helper routine FSH_PROBEBUF.

pLen is the pointer to the length of the application parameter area. For attach, this points to the length of the application data buffer. For query, this is the length of the remaining space in the application data buffer. Upon filling in the buffer, the FSD will set this to the length of the data returned. If the data returned is longer than the data buffer length, the FSD sets this value to be the length of the data that query could return. In this case, the FSD also returns a BUFFER OVERFLOW error.

The FSD does not need to verify this pointer.

Remarks

Local FSDs will never get called with attempts to attach or detach drives or queries about drives.

For remote FSDs called to do a detach, the kernel does not do any checking to see if there are any open references on the drive (for example, open or search references). It is entirely up to the FSD to decide whether it should allow the detach operation.