IGR_Get_Subfile_Entry¶

IGR_Get_Subfile_Entry enumerates the sub-documents contained in a previously opened compound document, such as message documents (MSG) or archive documents (ZIP).

Prototype¶

IGR_LONG IGR_Get_Subfile_Entry(
    IGR_LONG DocHandle,
    IGR_UCS2* ID,
    IGR_UCS2* Name,
    IGR_LONGLONG* FileDate,
    IGR_LONGLONG* FileSize,
    Error_Control_Block* ISYSError);

Parameters¶

DocHandle: IGR_LONG

Is a handle to a file, opened by a call to IGR_Open_File, IGR_Open_Stream or equivalent.

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.

FileDate: Pointer to INT64

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

FileSize: Pointer to INT64

Returns the size in bytes of the sub-document.

ISYSError: 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
20

Error_Control_Block ISYSError;
IGR_UCS2 ID[4096], Name[1024];
INT64 FileDate, FileSize;

while (true)
{
    IGR_LONG rc = IGR_Get_Subfile_Entry(DocHandle, ID, Name, &FileDate, &FileSize,
                &ISYSError);
    if (rc != IGR_OK)
    {
        if (rc != IGR_NO_MORE)
            // ReportError(rc);
        break;
    }
    rc = IGR_Extract_Subfile(DocHandle, ID, _UCS2("TEMP.DAT"), &ISYSError);
    if (rc != IGR_OK)
        // ReportError(rc);
    else
        // DoSomethingWithTheFile("TEMP.DAT", ID, Name);
}

Additional information¶

The previously opened document must have the IGR_FILE_SUPPORTS_SUBFILES capability.

After a successful call to IGR_Open_File / IGR_Open_Stream, each call to IGR_Get_Subfile_Entry 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¶

• IGR_Get_Subfile_Entry_Ex