NWReadEA(3nw)

NWReadEA -- reads next block of data from Extended Attribute

Synopsis

   #include <nwnamspc.h> 
   #include <nwea.h> 
   or 
   #include <nwcalls.h> 
    
   NWCCODE N_API NWReadEA 
     (NW_EA_HANDLE N_FAR    EAHandle, 
      nuint32                bufferSize, 
      pnuint8                buffer, 
      pnuint32               totalEASize, 
      pnuint32               amountRead);

Description

The parameters are as follows:

EAHandle: (IN/OUT) Points to NW_EA_HANDLE, obtained by calling either NWGetHandleStruct, NWFindFirstEA, NWFindNextEA, or NWOpenEA.
bufferSize: (IN) Specifies the size of the buffer.
buffer: (OUT) Points to a data buffer.
totalEASize: (OUT) Points to the size of the EA.
amountRead: (OUT) Points to the total amount of data read with the call. Not cumulative across multiple calls.

Return values

0x0000: SUCCESSFUL
0x8833: INVALID_BUFFER_LENGTH
0x8988: INVALID_FILE_HANDLE
0x898C: NO_MODIFY_PRIVILEGES
0x8996: SERVER_OUT_OF_MEMORY
0x899C: INVALID_PATH
0x89C9: EA_NOT_FOUND
0x89CE: EA_BAD_DIR_NUM
0x89CF: INVALID_EA_HANDLE
0x89D1: EA_ACCESS_DENIED
0x89D3: EA_VOLUME_NOT_MOUNTED
0x89D5: INSPECT_FAILURE

Notices

The data block to be read is determined from the state information identified by EAHandle.

NWReadEA and NWWriteEA can perform multiple actions, such as opening or creating an EA and then performing the appropriate function. To properly end NWReadEA, call NWCloseEA after the last Read or Write.

Extended Attribute values should always be read or written completely. Extended Attributes are not treated like files when transferring. Therefore, partial Reads or Writes are not allowed.

If 0x0000 is returned, more data can be written to the EA. If 0x0001 is returned, the data in the buffer was written successfully; however, no more data can be written to the EA. If other errors are returned, the data in the buffer was not written to the EA.

CAUTION: If an Extended Attribute is not read or written completely, data past the end of the last Read or Write may be lost!

NW_EA_HANDLE is referenced in all EA functions. NWReadEA and NWWriteEA use NW_EA_HANDLE to maintain state information. The state information is required to access the EA database. NW_EA_HANDLE is for internal use only; applications must not manipulate it in any way.

Before calling NWReadEA initially, an application must obtain an EAHandle in order to access the EA database. An application can obtain an EA handle by calling one of the following:

NWFindFirstEA
NWFindNextEA
NWGetEAHandleStruct
NWOpenEA

NWReadEA can be called multiple times until the amount of bytes of data read is equal to the value identified by totalEASize.

NOTE: The value referenced by amountRead is not cumulative across multiple calls and, therefore, does not reflect the total number of bytes in the EA.

For Reads, bufferSize must be at least 512 bytes. bufferSize can be greater than 512 bytes, but must be in multiples of 512. If bufferSize is less than 512, NWReadEA returns INVALID_BUFFER_LENGTH.

NWEARead reads up to the bufferSize number of EA information bytes or until the end of the EA data, whichever comes first.

Services

Extended Attribute

NCP calls

0x2222 86 03 Read Extended Attribute

 
 -------------------------------------------- 
| 0x2222|  86|  03|  Read Extended Attribute| 
|-------|----|----|-------------------------|

References

NWFindNextEA(3nw), NWFindFirstEA(3nw), NWOpenEA(3nw), NWWriteEA(3nw)