DosEnumAttribute (OS/2 1.x)

From EDM2
Jump to: navigation, search
Att.gif Legacy Function Warning
It is recommended to use a newer replacement for this function.
Replacement: DosEnumAttribute
Remarks:

This call identifies extended attributes for a specific file or subdirectory.

Syntax

DosEnumAttribute (RefType, FileRef, EntryNum, EnumBuf,
                  EnumBufSize, EnumCnt, InfoLevel, Reserved)

Parameters

RefType (USHORT) - input 
A value that indicates the contents of FileRef.
Value  Definition
0      Handle of a file.
1      ASCIIZ name of a file or subdirectory.
FileRef (PVOID) - input
Address of the handle of a file returned by a DosOpen or DosOpen2 request; or the ASCIIZ name of a file or subdirectory.
EntryNum (ULONG) - input 
Ordinal of an entry in the file object's EA list, which indicates where in the list to begin the return of EA information. The value 0 is reserved. A value of 1 indicates the file object's first EA; a value of 2, the second; and so on.
EnumBuf (PVOID) - output 
Address of the buffer where EA information is returned. Level 1 information is returned in the following format:
Reserved (UCHAR) : Zero.
cbName (UCHAR) : Length of name excluding NULL.
cbValue (USHORT) : Length of value.
szName (UCHAR) : Variable length asciiz name.
EnumBufSize (ULONG) - output 
Size of EnumBuf.
EnumCnt (PULONG) - input/output 
Address of, on input, the number of EAs for which information is requested. A value of -1 requests information be returned for as many EAs whose information fits in EnumBuf.
On output, the actual number of EAs for which information is returned. When this value is greater than 1, enumerated information is returned in a packed list. That is, information for the next EA will be stored adjacent to the previous one.
InfoLevel (ULONG) - input 
Level of information required. Only the value 1 can be specified, indicating return of level 1 information.
Reserved (ULONG) - input 
Reserved and must be set to zero.

Return Code

rc (USHORT) - return

Return code descriptions are:

  • 0 NO_ERROR
  • 3 ERROR_PATH_NOT_FOUND
  • 5 ERROR_ACCESS_DENIED
  • 6 ERROR_INVALID_HANDLE
  • 8 ERROR_NOT_ENOUGH_MEMORY
  • 87 ERROR_INVALID_PARAMETER
  • 111 ERROR_BUFFER_OVERFLOW
  • 124 ERROR_INVALID_LEVEL
  • 206 ERROR_FILENAME_EXCED_RANGE

Remarks

The structure returned by DosEnumAttribute is used to calculate the size of the buffer required to hold the full extended attribute (FEA) information for a DosQPathInfo or DosQFileInfo call that actually gets the FEA. The size of buffer required to hold the FEA information is calculated as follows:

  • One byte (for fea_Reserved) +
  • One byte (for fea_cbName) +
  • Two bytes (for fea_cbValue) +
  • Value of cbName (for the name of the EA) +
  • One byte (for terminating NULL in fea_cbName) +
  • Value of cbValue (for the value of the EA)

A process can continue through a file's EA list by reissuing DosEnumAttribute with EntryNum set to the value specified in the previous call plus the value returned in EnumCnt.

DosEnumAttribute does not control the specific ordering of EAs; it merely identifies them. Like the files they are associated with, extended attributes can have multiple readers and writers. If a file is open in a sharing mode that allows other processes to modify the file's EA list, calling DosEnumAttribute repetitively to back up to an EA's position may return inconsistent results. For example, it is possible for another process to edit the EA list with DosSetFileInfo or DosSetPathInfo between calls by your process to DosEnumAttribute. Thus, the EA returned when EntryNum is 11 for the first call may not be the same EA returned when EntryNum is 11 for the next call.

To prevent the modification of EAs between calls to DosEnumAttribute for a specified file handle or file name, the caller must open the file in deny-write sharing mode before it calls DosEnumAttribute. If a subdirectory name is specified, modification by other processes is not a concern , because no sharing is possible.

For RefType = 1, the EAs returned are current only when the call was made, and they may have been changed by another thread or process in the meantime.

Example Code

C Binding

typedef struct _DENA1 {  /* level 1 info returned from DosEnumAttribute */
  UCHAR  reserved;       /* 0                                           */
  UCHAR  cbName;         /* length of name excluding NULL               */
  USHORT cbValue;        /* length of value                             */
  UCHAR  szName[1];      /* variable length asciiz name                 */
} DENA1;

#define INCL_DOSFILEMGR

USHORT  rc = DosEnumAttribute(RefType, FileRef, EntryNum, EnumBuf,
                               EnumBufSize, EnumCnt, InfoLevel, Reserved);

USHORT           RefType;       /* Type of reference  */
PVOID            FileRef;       /* Handle or Name  */
ULONG            EntryNum;      /* Starting entry in EA list  */
PVOID            EnumBuf;       /* Data buffer  */
ULONG            EnumBufSize;   /* Data buffer size  */
PULONG           EnumCnt;       /* Count of entries to return  */
ULONG            InfoLevel;     /* Level of information requested  */
ULONG            0;             /* Reserved (must be zero)  */

USHORT           rc;            /* return code */  */

MASM Binding

DENA1   struc                    ;level 1 info returned from
                                 ;  DosEnumAttribute
 
  level_reserved db           ?  ;0
  level_cbName   db           ?  ;length of name excluding NULL
  level_cbValue  dw           ?  ;length of value
  level_szName   db  1  dup  (?) ;variable length asciiz name
 
DENA1   ends

EXTRN DosEnumAttribute:FAR
INCL_DOSFILEMGR     EQU 1

PUSH  WORD   RefType         ;Type of reference
PUSH@ OTHER  FileRef         ;Handle or Name
PUSH  DWORD  EntryNum        ;Starting entry in EA list
PUSH@ OTHER  EnumBuf         ;Data buffer (returned)
PUSH  DWORD  EnumBufSize     ;Data buffer size
PUSH@ DWORD  EnumCnt         ;Count of entries to return
PUSH  DWORD  InfoLevel       ;Level of information requested
PUSH  DWORD  0               ;Reserved (must be zero)
CALL  DosEnumAttribute