Skip to content

IGR_Subfiles_Next

IGR_Subfiles_Next iterates through the sub-documents within a subfile enumeration obtained from IGR_Get_Subfiles_Enumerator or a similar function.

Prototype

IGR_RETURN_CODE IGR_Subfiles_Next(
    HSUBFILES handle,
    IGR_UCS2* id,
    IGR_UCS2* name,
    IGR_LONGLONG* date,
    IGR_LONGLONG* size,
    Error_Control_Block* error);

Parameters

handle: IGR_LONG

Is a handle to a file, opened by a call to IGR_Open_File.

id: Unicode string (UCS2)

Application allocated memory block of 8192 bytes that will be filled with up to 4096 Unicode characters that specify the unique id of the next sub-document.

name: Unicode string (UCS2)

Application allocated memory block of 2048 bytes that will be filled with up to 1024 Unicode characters that specify the name of the sub-document.

date: Pointer to INT64

Returns the date and time of the sub-document in FILETIME format.

size: Pointer to INT64

Returns the size in bytes of the sub-document.

error: Pointer to Error_Control_Block

Returns error details if the call fails.

Return value

Success: IGR_LONG

Returns IGR_OK.

Success and the end of the document was reached: IGR_LONG

Returns IGR_NO_MORE.

Failure: IGR_LONG

Returns one of the possible IGR_E error codes.

Sample code

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
Error_Control_Block error;
HSUBFILES subs;
std::array<IGR_UCS2, 4096> id;
std::array<IGR_UCS2, 1024> name;
IGR_LONGLONG date, size;
IGR_RETURN_CODE res;

if ((res = IGR_Get_Subfiles_Enumerator(docHandle, &subs, &error)) == IGR_OK)
{
    while ((res = IGR_Subfiles_Next(subs, &id[0], &name[0], &date, &size, &error)) == IGR_OK)
    {
        res = IGR_Extract_Subfile(docHandle, id, _UCS2("TEMP.DAT"), &error);
        if (res != IGR_OK)
            // ReportError(res);
        else
            // DoSomethingWithTheFile("TEMP.DAT", id, name);
    }
    IGR_Subfiles_Close(subs, &error);
}

Additional information

The previously opened document must have the IGR_FILE_SUPPORTS_SUBFILES capability.

After a successful call to IGR_Get_Subfiles_Enumerator, each call to IGR_Subfiles_Next will retrieve information about the next sub-document contained in the compound document, referenced by DocHandle. To traverse all the sub-documents, the application will need to call this method in a loop until IGR_NO_MORE is returned.

Note that the null-terminating character will also be copied to the id and name parameters. The name parameter could be an empty string if the id of the sub-document is not available. If the function succeeds, the id is guaranteed not to be empty and will be unique among all traversed sub-documents retrieved from the document. The returned id can be used in a call to IGR_Extract_Subfile to save the binary content of the sub-document to disk.

If the date of the sub-document is not available, the parameter FileDate will be set to 0, otherwise it will be populated in FILETIME format.

If the size of the sub-document is not available, the parameter FileSize will be set to 0.

See Also