NWReadEA
Reads the next block of data from the specified Extended Attribute
#include <nwnamspc.h> #include <nwea.h> or #include <nwcalls.h> N_EXTERN_LIBRARY(NWCCODE) NWReadEA ( NW_EA_HANDLE N_FAR *EAHandle, nuint32 bufferSize, pnuint8 buffer, pnuint32 totalEASize, pnuint32 amountRead);
uses calwin32 Function NWReadEA (Var EAHandle : NW_EA_HANDLE; bufferSize : nuint32; buffer : pnuint8; totalEASize : pnuint32; amountRead : pnuint32 ) : NWCCODE;
These are common return values; see Return Values (Return Values for C) for more information.
The data block to be read is determined from the state information identified by the EAHandle parameter.
NWReadEA and the NWWriteEA function can perform multiple actions, such as opening or creating an Extended Attribute and then calling the appropriate function. To properly end NWReadEA, call the NWCloseEA function 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 read from the Extended Attribute by calling NWReadEA again. In this case, EAHandle is already positioned correctly for the next subsequent call. If 0x0001 is returned, no more data can be read and the data in the buffer was read successfully. If other error values are returned, the data in the buffer is not considered valid.
IMPORTANT:If an Extended Attribute is not read or written completely, data past the end of the last Read or Write may be lost!
The NW_EA_HANDLE structure is referenced in all Extended Attribute functions. NWReadEA and the NWWriteEA function use the NW_EA_HANDLE structure to maintain state information. The state information is required to access the Extended Attribute database. The NW_EA_HANDLE structure is for internal use only; do not manipulate it in any way.
Before calling NWReadEA initially, you must obtain the EAHandle parameter to access the Extended Attribute database. An application can obtain an Extended Attribute handle by calling one of the following functions:
NWReadEA can be called multiple times until the bytes of data read is equal to the value identified by the totalEASize parameter.
NOTE:The value referenced by the amountRead parameter does not reflect the total number of bytes in the Extended Attribute.
For Reads, the bufferSize parameter must be at least 512 bytes; it can be greater than 512 bytes—but must be in multiples of 512. If the bufferSize parameter is less than 512 bytes, NWReadEA returns INVALID_BUFFER_LENGTH.
The NWEARead function reads up to the number of bytes specified by the bufferSize parameter or until the end of the Extended Attribute data, whichever comes first.