FS_ATTACH - Attach to an FSD

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: 

flag == 0 requests an attach. The FSD is being called to attach a 
specified driver or character device. 
flag == 1 requests a detach. 
flag == 2 requests the FSD to fill in the specified buffer with attachment 
information. 

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.