Skip to content

IGR_Subfiles_Next_Ex

IGR_Subfiles_Next_Ex 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_Ex(
    HSUBFILES enumerator, 
    struct IGR_Subfile_Info* result, 
    Error_Control_Block* error);

Parameters

enumerator: HSUBFILES

Handle to an enumerator opened by IGR_Get_Subfiles_Enumerator.

result: Pointer to IGR_Subfile_Info

Pointer to a user allocated IGR_Subfile_Info to be populated with the subfile information.

error: Pointer to Error_Control_Block

Returns error details if the call fails.

Return value

Success: IGR_LONG

Returns IGR_OK.

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
20
21
22
23
24
25
26
27
28
29
30
31
Error_Control_Block error = { 0 };
IGR_Subfile_Info subfile = { 0 };
IGR_RETURN_CODE res;
HSUBFILES subs;

std::array<IGR_UCS2, 4096> id;
std::array<IGR_UCS2, 1024> name;
std::array<IGR_UCS2, 4096> comment;

subfile.struct_size = sizeof(subfile);
subfile.id = &id[0];
subfile.id_size = id.size();

subfile.name = &name[0];
subfile.name_size = name.size();

subfile.comment = &comment[0];
subfile.comment_size = comment.size();

if ((res = IGR_Get_Subfiles_Enumerator(docHandle, &subs, &error)) == IGR_OK)
{
    while ((res = IGR_Subfiles_Next_Ex(subs, &subfile, &error)) == IGR_OK)
    {
        res = IGR_Extract_Subfile(DocHandle, ID, _UCS2("TEMP.DAT"), &ISYSError);
        if (res != IGR_OK)
            // ReportError(rc);
        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_Get_Subfile_Entry_Ex 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 result.ID and result.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