Skip to content

IGR_Open_Ex

IGR_Open_Ex opens a document for text extraction or enumeration of sub-documents, and takes an IGR_OPEN_CALLBACK parameter that allows for interaction with the API user during API calls.

Prototype

IGR_LONG IGR_Open_Ex(
    IGR_OPEN_FROM source_type,
    const void* source,
    IGR_LONG flags,
    const IGR_UCS2* options,
    IGR_LONG* capabilities,
    IGR_LONG* file_type,
    void* reserved,
    IGR_OPEN_CALLBACK callback,
    void* callback_context,
    IGR_LONG* handle,
    Error_Control_Block* error);

Parameters

source_type: IGR_OPEN_FROM

The type of source, that can be either a UTF-16 string containing the filename, or an IGR_Stream record. See IGR_OPEN_FROM.

source: Pointer to VOID

The pointer to the source based on the source_type parameter. If the source is an IGR_Stream, the stream MUST remain valid for the life-type of the document handle returned.

flags: IGR_LONG

Specifies what type of data is returned from subsequent calls to the IGR_Get_Text function. These Open Document Flags affect the verbosity or the format of the extracted data.

options: Unicode string (UCS2)

Extended processing options, used when converting the document to HTML. The Open Document Options are expressed as Name=Value with a semicolon delimiter.

capabilities: Pointer to IGR_LONG

Returns the Document Capabilities as a bit field.

file_type: Pointer to IGR_LONG

Returns the Document Format Code of the document.

reserved: Pointer to VOID

MUST be NULL. Reserved for future use.

callback: IGR_OPEN_CALLBACK

IGR_OPEN_CALLBACK that will be called for specific events while processing the document. MUST remain valid for the lifetime of the document handle returned.

callback_context: Pointer to VOID

Contextual information that will be passed back when the callback is called. MUST remain valid for the lifetime of the document handle returned.

handle: Pointer to IGR_LONG

Returns a handle to be used in subsequent calls.

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

struct OpenExCallbackContext
{
    OpenExCallbackContext();
    bool isCancellationRequested();
};

IGR_LONG IGR_EXPORT OpenExCallback(IGR_OPEN_CALLBACK_ACTION action, void* payload, void* context)
{
    if (action == IGR_OPEN_CALLBACK_ACTION_HEARTBEAT)
    {
        if (OpenExCallbackContext* callbackContext = static_cast<OpenExCallbackContext*>(context))
        {
            if (callbackContext->isCancellationRequested())
                return IGR_CANCELLED;
        }
    }
    else if (action == IGR_OPEN_CALLBACK_ACTION_PASSWORD)
    {
        IGR_Open_Callback_Action_Password* passwordStruct(static_cast<IGR_Open_Callback_Action_Password*>(payload));

        if (!passwordStruct || passwordStruct->struct_size != sizeof(*passwordStruct))
            return IGR_E_ERROR;

        // Read string from passwordStruct->id to identify which password is being requested

        // Get password string for password being requested

        // Write password string to passwordStruct->password
    }
    else if (action == IGR_OPEN_CALLBACK_ACTION_LOCALIZE)
    {
        IGR_Open_Callback_Action_Localize* localizeStruct(static_cast<IGR_Open_Callback_Action_Localize*>(payload));

        if (!localizeStruct || localizeStruct->struct_size != sizeof(*localizeStruct))
            return IGR_E_ERROR;

        // Read string from localizeStruct->original to identify the string to be replaced 

        // Get replacement string

        // Write replacement string to localizeStruct->replacement
    }
    return IGR_OK;
}

int main(int argc, char** argv)
{
    Error_Control_Block ISYSError;
    IGR_LONG Capabilities, DocType, DocHandle;
    OpenExCallbackContext CallbackContext;

    IGR_LONG RC = IGR_Open_Ex(IGR_OPEN_FROM_FILENAME_UTF16, _UCS2("TEST.DOC"),
    IGR_BODY_AND_META | IGR_FORMAT_HTML, _UCS2("IMAGEPATH=C:\\Temp"),
    &Capabilities, &DocType, NULL,
    OpenExCallback, &CallbackContext, &DocHandle, &ISYSError);

    if (RC == IGR_OK)
    {
        // Extract document text or sub-documents...
        IGR_Close_File(DocHandle, &ISYSError);
    }
}

Additional information

The call will establish a link to the document and populates a handle. The handle can be used to extract the text by calling IGR_Get_Text, generate page images with IGR_Open_Page, or enumerate and extract the sub-documents by calls to IGR_Get_Subfile_Entry and IGR_Extract_Subfile respectively.

The application must call IGR_Close_File when finished using the document.

If a (non-NULL) IGR_OPEN_CALLBACK is provided, the callbacks can happen any time from the point of IGR_Open_Ex being called through to its handle being closed by IGR_Close_File.

See IGR_OPEN_CALLBACK for more information on the specifics of each callback action.

See also