DosFSCtl

From EDM2
Jump to: navigation, search

Provides an extended standard interface between an application and a file-system driver (FSD).

Syntax

DosFSCtl(pData, cbData, pcbData, pParms,
        cbParms, pcbParms, function, pszRoute,
        hFile, method);

Parameters

pData (PVOID) - input 
Address of the data area.
cbData (ULONG) - input 
The length, in bytes, of pData.
This is the maximum length of the data to be returned by the file-system driver in pData. pcbData may be larger than this on input, but not on output.
pcbData (PULONG) - in/out 
Pointer to the length of data passed to or returned from the FSD.
Input : Pointer to the length, in bytes, of the data passed to the file-system driver in pData
Output: Pointer to the length, in bytes, of the data returned by the file-system driver in pData. If this function returns ERROR_BUFFER_OVERFLOW, pcbData points to the size of the buffer required to hold the data returned by the file-system driver.
pParms (PVOID) - input 
Address of the command-specific parameter list.
cbParms (ULONG) - input 
The length, in bytes, of pParms.

This is the maximum length of the data to be returned by the file-system driver in pParms. pcbParms may be larger than this on input, but not on output.

pcbParms (PULONG) - in/out 
Pointer to the length of the parameters passed to or returned from the FSD.
Input: Pointer to the length, in bytes, of the parameters passed to the file-system driver in pParms.
Output: Pointer to the length, in bytes, of the parameters returned by the file-system driver in pParms. If this function returns ERROR_BUFFER_OVERFLOW, pcbParms. points to the size of the buffer required to hold the parameters returned by the file-system driver. No other data is returned in this case.
function (ULONG) - input 
The function code that is specific to the file-system driver.
For remote file-system drivers, two kinds of DosFSCtl functions are possible: functions that are handled locally, and functions that are exported across the network. If bit 0x4000 is set in function, this indicates to the remote file-system driver (FSD) that the function should be exported.
Function codes from 0x0000 to 0x7FFF are reserved for use by the operating system. Function codes from 0x8000 to 0xBFFF are FSD-defined DosFSCtl functions handled by the local file-system driver. Function codes from 0xC000 to 0xFFFF are FSD-defined DosFSCtl functions exported to the server.
function may have one of the following values:
1 - FSCTL_ERROR_INFO Returns error-code information from the file-system driver.
Input - The error code is passed to the file-system driver in the first word of pParms.
Output - The ASCIIZ string returned in pData is an explanation of the error code.
2 - FSCTL_MAX_EASIZE
Queries the file-system driver for the maximum size of individual EAs (extended attributes), and the maximum size of the full EA list that it supports. The information is returned in pData in the form of an EASIZEBUF structure.
pszRoute (PSZ) - input 
Address of the ASCIIZ name of the FSD, or the path name of a file or directory that the operation applies to.
This parameter must be a null pointer (OL) If method is equal to FSCTL_HANDLE
hFile (HFILE) - input 
File-specific or device-specific handle.
This parameter must be -1 when method is equal to FSCTL_PATHNAME or FSCTL_FSDNAME.
method (ULONG) - input 
Method used to routed the request.
Possible values are shown in the following list:
1 FSCTL_HANDLE hFile directs routing. pszRoute must be a null pointer (0L). The file-system driver associated with the handle receives the request.
2 FSCTL_PATHNAME
pszRoute refers to a path name that directs routing. hFile must be -1. The file-system driver associated with the drive that the path name refers to at the time of the request receives the request. The path name need not refer to a file or directory that actually exists, only to a drive. A relative path name may be used; it is processed like any other path name.
3 FSCTL_FSDNAME
pszRoute refers to a file-system driver name that directs routing. hFile must be -1. The named file-system driver receives the request.

Return Code

ulrc (APIRET) - returns

DosFSCtl returns one of the following values:

  • 0 NO_ERROR
  • 1 ERROR_INVALID_FUNCTION
  • 6 ERROR_INVALID_HANDLE
  • 87 ERROR_INVALID_PARAMETER
  • 95 ERROR_INTERRUPT
  • 111 ERROR_BUFFER_OVERFLOW
  • 117 ERROR_INVALID_CATEGORY
  • 124 ERROR_INVALID_LEVEL
  • 252 ERROR_INVALID_FSD_NAME

Remarks

For debugging considerations, see DosDebug.

Example Code

The following is NOT a complete C program. It is intended to provide an idea of how to communicate with a file system driver (FSD).

This example assumes that FileHandle has been initialized with the handle to the file and that the file system driver (FSD) recognizes a function code of hex 81DE. It further assumes that the input parameters and input data area are appropriate for the function.

 #define INCL_DOSFILEMGR   /* File Manager values */
 #define INCL_DOSERRORS    /* Error values */
 #include <os2.h>
 #include <stdio.h>
 #include <string.h>

 UCHAR   uchDataArea[200] = {0};          /* Input and output data area */
 ULONG   ulDataLen        = 0;            /* Input and output data size */
 UCHAR   uchParms[120]    = {0};          /* Input and output for function */
 ULONG   ulParmLen        = 0;            /* Input and output parameter size */
 ULONG   ulFunction       = 0x81DE;       /* Device-specific function */
 HFILE   hfFile           = NULLHANDLE;   /* Handle for file */
 APIRET  rc               = NO_ERROR;     /* Return code */

  strcpy(uchDataArea,"34 22 37");   /* Data to pass to file system */
  ulDataLen = strlen(uchDataArea);  /* Length of input data */

  strcpy(uchParms,"PARM1: 98");     /* Input parameters */
  ulParmLen = strlen(uchParms);     /* Length of input parameters */

  rc = DosFSCtl(uchDataArea,         /* Input/output data area */
                sizeof(uchDataArea), /* Maximum output data size */
                &ulDataLen,          /* Input:  size of input data area */
                                     /* Output: size of data returned   */
                uchParms,            /* Input/Output parameter list */
                sizeof(uchParms),    /* Maximum output parameter size */
                &ulParmLen,          /* Input:  size of parameter list */
                                     /* Output: size of parameters returned */
                ulFunction,          /* Function being requested */
                "MY_FSD",            /* File System Driver (FSD) name */
                hfFile,              /* Handle for file */
                FSCTL_FSDNAME);      /* Indicate FSD name is the route */

  if (rc != NO_ERROR) {
      printf("DosFSCtl error: return code = %u\n", rc);
      return 1;
  }

Related Functions