Developer

API Reference

IVFSNODE_GetData()

deprecated
Items marked as deprecated have been replaced by a more powerful, alternative feature. Deprecated interfaces include a reference to the replacement interface, which should be used for all new application development. Deprecated features are still supported for backward compatibility, but should be avoided when developing new applications.
Brew Release
Brew MP 1.0.2
See Also
IVFSNODEMODEL_GetNodeData() IVFSNODE_SetData()
Description
This is the routine used to retrieve data from a Vfs path. It also provides information about the node, such as the type of data held, and the size of buffer (in bytes) required to make a copy of the data.
All information in the Vfs tree is reached using a PATH. The path is comprised of a NULL terminated array of VfsPathElement items (currently AECHAR*). Each VfsPathElement represents a single 'level' or 'depth' of the entire Vfs tree.
The simplest way to implement data handlers in the Vfs tree is to use the 'standard' vfs nodes, available via the IActorContext interface. These standard nodes implement a single node, which may be a container (or parent) of further nodes.
It is also possible, by implementing the entire IVfsNode interface yourself, to create Vfs entries that handle entire path sequences, rather than just the single level supported by the standard nodes.
Parameters
  • node
    []:
    Pointer to the IVfsNode interface object
  • path
    []:
    The remainder of the path to the desired node
  • pType
    []:
    A pointer to the data type required. The type may be modified by the call to one which is supported.
  • pBuf
    []:
    The address of a buffer at which to store the returned data.
  • pSize
    []:
    The address of an integer which specifies the size of the buffer at pBuf. If the integer is -1, it will be change to the size of buffer required.
Interface
IVFSNODE
Prototype
   int IVFSNODE_GetData( IVfsNode * node, VfsPath path, AEECLSID * pType, void * pBuf, int * pSize )
Return
   SUCCESS - the call has been completed successfully.
   ENOSUCH - the node specified by the path cannot be found.
   ENEEDMORE - The data type or size has been corrected by the call.
   EBUFFERTOOSMALL - the buffer supplied is too small to copy out the data.
   EMEMPTR - the buffer supplied is NULL.
   EBADPARM - the buffer supplied is badly aligned for the type of data.
   EBADITEM - it is not possible to read data from this node.

Other errors may be returned by node models.
Side Effect
Nodes may be created (by IVfsCacheContainers) in order to satisfy this request. The interface returned by an interface node is AddRef()ed before being returned. It is the responsibility of the caller to IBase_Release() the interface after use.
Comment
This is a complex function, best descibed by pseudocode.
First the path is checked. * If at the end of the path, then the data should be read from this node. * Otherwise: * if this node is a container, the call is passed on to the appropriate child node (one whose name matches path[0]) with the first element of the path stripped. * if this node is NOT a container, the call fails with ENOSUCH

If pType, pObj, or pSize are NULL, the call fails with EMEMPTR
If *pType is NOT a type handled by this node, then *pType will be set to the class id of a supported data type, and the call fails with ENEEDMORE
If *pSize is -1 (size request), then *pSize will be set to the size in bytes of the associated data, and the call will fail with ENEEDMORE
If *pSize is less than the size of data held by the node, then the call will fail with EBUFFERTOOSMALL
The data returned depends on the type of data held by the node:
   Data        type                       pObj cast from Code snippet
   ----------- -------------------------- -------------- -------------------------------------
   integer     AEEIID_VFS_INTEGER_DATA    int *          int i; pObj = (void*)&i;
   string      AEEIID_VFS_STRING_DATA     AECHAR *       AECHAR s[]; pObj = (void*)&s[0];
   byte data   AEEIID_VFS_BYTE_DATA       uint8 *        uint8 d[]; pObj = (void*)&d[0];
   interface   (interface id)             IBase **       IBase * p; pObj = (void*)&p;

Note that this call COPIES data from the Vfs node into the buffer area supplied.
SIGNAL type and container nodes have no data that can be read; this call would fail with EBADITEM.
  • Follow