This chapter includes the following sections:
DAInit and DaThreadInit have both been deprecated. DAInitEx now replaces these two functions. All new implementations should use DAInitEX, although the other two functions will continue to be supported.
This function tells the Data Access module to perform any necessary initialization it needs to prepare for document access. This function must be called before the first time the application uses the module to retrieve data from any document. This function supersedes the old DAInit and DAThreadInit functions.
DAInitEx should only be called once per application, at application startup time. Any number of documents can be opened for access between calls to DAInitEx and DADeInit. If DAInitEx succeeds, DADeInit must be called regardless of any other API calls.
If the ThreadOption parameter is set to something other than DATHREAD_INIT_NOTHREADS, then this function's preparation includes setting up mutex function pointers to prevent threads from clashing in critical sections of the technology's code. The developer must actually code the threads after this function has been called. DAInitEx should be called only once per process and should be called before the developer's application begins the thread.
Multiple threads are supported for all Windows platforms, the 32-bit versions of Linux x86 and Solaris SPARC, Linux x64 and Solaris SPARC 64. Failed initialization of the threading function will not impair other API calls. If threading isn't initialized or fails, stub functions are called instead of mutex functions.
Prototype
DAERR DAInitEx(VTSHORT ThreadOption, VTDWORD dwFlags);
Parameters
ThreadOption: can be one of the following values:
DATHREAD_INIT_NOTHREADS: No thread support requested.
DATHREAD_INIT_PTHREADS: Support for PTHREADS requested.
DATHREAD_INIT_NATIVETHREADS: Support for native threading requested. Supported only on Microsoft Windows platforms and Oracle Solaris.
dwFlags: can be one or more of the following flags OR-ed together
OI_INIT_DEFAULT: Options Load and Save are performed normally
OI_INIT_NOSAVEOPTIONS: The options file will not be saved on exit
OI_INIT_NOLOADOPTIONS: The options file will not be read during initialization.
Return Values
DAERR_OK: If the initialization was successful. Otherwise, one of the other DAERR_ values in sccda.h or one of the SCCERR_ values in sccerr.h is returned.
This function tells the Data Access module that it will not be asked to read additional documents, so it should perform any cleanup tasks that may be necessary. This function should be called at application shutdown time, and only if the module was successfully initialized with a call to DAInitEx.
Prototype
DAERR DADeInit();
Return Values
DAERR_OK: If the de-initialization was successful. Otherwise, one of the other DAERR_ values in sccda.h or one of the SCCERR_ values in sccerr.h is returned.
Opens a source file to make it accessible by one or more of the data access technologies. If DAOpenDocument succeeds, DACloseDocument must be called regardless of any other API calls.
Prototype
DAERR DAOpenDocument( VTLPHDOC phDoc, VTDWORD dwSpecType, VTLPVOID pSpec, VTDWORD dwFlags);
Parameters
lphDoc: Pointer to a handle that will be filled with a value that uniquely identifies the document to data access. The developer will use this handle in subsequent calls to data access to identify this particular source file.
This is not an operating system file handle.
dwSpecType: Describes the contents of pSpec. Together, dwSpecType and pSpec describe the location of the source file.
The values used within IOTYPE_ARCHIVEOBJECT, IOTYPE_LINKEDOBJECT, and IOTYPE_OBJECT may change if different options are applied, with different versions of the technology, or after patches are applied.
Must be one of the following values:
IOTYPE_ANSIPATH: Windows only. pSpec points to a NULL-terminated full path name using the ANSI character set and FAT 8.3 (Win16) or NTFS (Win32 and Win64) file name conventions.
IOTYPE_UNICODEPATH: Windows only. pSpec points to a NULL-terminated full path name using the Unicode character set and NTFS (Win32 and Win64) file name conventions.
IOTYPE_UNIXPATH: X Windows on UNIX platforms only. pSpec points to a NULL-terminated full path name using the system default character set and UNIX path conventions. Unicode paths can be accessed on UNIX platforms by using a UTF-8 encoded path with IOTYPE_UNIXPATH.
IOTYPE_SUBOBJECT: All platforms. Opens an embedded object for data access. pSpec points to a structure IOSPECSUBOBJECT (see IOSPECSUBOBJECT Structure) that has been filled with values returned in a SCCCA_OBJECT content entry from Content Access.
IOTYPE_REDIRECT: All platforms. pSpec points to a developer-defined struct that allows the developer to redirect the IO routines used to read the file.
IOTYPE_ARCHIVEOBJECT: All platforms. Opens an embedded archive object for data access. pSpec points to a structure IOSPECARCHIVEOBJECT (see IOSPECARCHIVEOBJECT Structure) that has been filled with values returned in a SCCCA_OBJECT content entry from Content Access.
IOTYPE_LINKEDOBJECT: All platforms. Opens an object specified by a linked object for data access. pSpec points to a structure IOSPECLINKEDOBJECT (see IOSPECLINKEDOBJECT Structure) that has been filled with values returned in an SCCCA_BEGINTAG or SCCCA_ENDTAG with a subtype of SCCCA_LINKEDOBJECT content entry from Content Access.
IOTYPE_OBJECT: All platforms. Opens an object (archive, embedded, or linked) for data access. pSpec points to a structure SCCDAOBJECT (see SCCDAOBJECT Structure) that has been filled with values from Content Access (SCCCA_OBJECT or SCCCA_BEGINTAG with a subtype of SCCCA_LINKEDOBJECT) or from the <document> element in the SearchML flavor of Search Export.
pSpec: File location specification.
dwFlags: The low WORD is the file ID for the document (0 by default). If you set the file ID incorrectly, the technology will fail. If set to 0, the file identification technology will determine the input file type automatically. The high WORD should be set to 0. It may also be set to the following flags:
DAOPENDOCUMENT_ARCHIVEONLYMODE: This flag may only be used with archive files. It opens the archive in a special mode that is only usable with DASaveRandomTreeRecord and DAOpenRandomTreeRecord.
DAOPENDOCUMENT_CONTINUEONFAILURE: Some embeddings may have both an OLE representation and an alternate graphic. When this flag is set for IOTYPE_OBJECT, the technology will first try to access the OLE representation. If there are errors, it will then attempt to access the alternate graphic.
Return Values
DAERR_OK: Returned if the open was successful. Otherwise, one of the other DAERR_ values in sccda.h or one of the SCCERR_ values in sccerr.h is returned.
typedef struct IOSPECSUBOBJECTtag
{
VTDWORD dwStructSize;
VTSYSPARAM hDoc; /* Parent Doc hDoc */
VTDWORD dwObjectId; /* Object Identifier */
VTDWORD dwStreamId; /* Stream Identifier */
VTDWORD dwReserved1; /* Must always be 0 */
VTDWORD dwReserved2; /* Must always be 0 */
} IOSPECSUBOBJECT, * PIOSPECSUBOBJECT;
typedef struct IOSPECLINKEDOBJECTtag
{
VTDWORD dwStructSize;
VTSYSPARAM hDoc;
VTDWORD dwObjectId; /* Object identifier. */
VTDWORD dwType; /* Linked Object type */
/* (SO_LOCATORTYPE_*) */
VTDWORD dwParam1; /* parameter for DoSpecial call */
VTDWORD dwParam2; /* parameter for DoSpecial call */
VTDWORD dwReserved1; /* Reserved. */
VTDWORD dwReserved2; /* Reserved. */
} IOSPECLINKEDOBJECT, * PIOSPECLINKEDOBJECT;
typedef struct IOSPECARCHIVEOBJECTtag
{
VTDWORD dwStructSize;
VTDWORD hDoc; /* Parent Doc hDoc */
VTDWORD dwNodeId; /* Node ID */
VTDWORD dwStreamId;
VTDWORD dwReserved1; /* Reserved */
VTDWORD dwReserved2; /* Reserved */
} IOSPECARCHIVEOBJECT, * PIOSPECARCHIVEOBJECT;
typedef struct SCCDAOBJECTtag
{
VTDWORD dwSize; /* sizeof(SCCDAOBJECT) */
VTHDOC hDoc; /* DA handle for the document
containing the object */
VTDWORD dwObjectType; /* SCCCA_EMBEDDEDOBJECT,
SCCCA_LINKEDOBJECT,
SCCCA_COMPRESSEDFILE or
SCCCA_ATTACHMENT */
VTDWORD dwData1; /* Data identifying the object */
VTDWORD dwData2; /* Data identifying the object */
VTDWORD dwData3; /* Data identifying the object */
VTDWORD dwData4; /* Data identifying the object */
} SCCDAOBJECT, * PSCCDAOBJECT;
This function is called to close a file opened by the reader that has not encountered a fatal error.
Prototype
DAERR DACloseDocument( VTHDOC hDoc);
Parameters
hDoc: Identifier of open document. Must be a handle returned by the DAOpenDocument function.
DAERR_OK: Returned if close succeeded. Otherwise, one of the other DAERR_ values in sccda.h or one of the SCCERR_ values in sccerr.h is returned.
This function returns the document handle associated with any type of Data Access handle. This allows the developer to only keep the value of hItem, instead of both hItem and hDoc.
Prototype
DAERR DARetrieveDocHandle( VTHDOC hItem, VTLPHDOC phDoc);
Parameters
hItem: Identifier of open document. May be the subhandle returned by the DAOpenDocument or DAOpenTreeRecord functions in the data access submodule. Passing in an hDoc created by DAOpenDocument for this parameter will result in an error.
phDoc: Pointer to a handle that will be filled with the document handle associated with the passed subhandle.
Return Value
DAERR_OK: Returned if the handle in phDoc is valid. Otherwise, one of the other DAERR_ values in sccda.h or one of the SCCERR_ values in sccerr.h is returned.
This function is called to set the value of a data access option.
Prototype
DAERR DASetOption( VTHDOC hDoc, VTDWORD dwOptionId, VTLPVOID pValue, VTDWORD dwValueSize);
Parameters
hDoc: Identifier of open document. May be a VTHDOC returned by the DAOpenDocument function, or the subhandle returned by the DAOpenDocument or DAOpenTreeRecord functions (VTHCONTENT, VTHTEXT, and so forth). Setting an option for a VTHDOC will affect all subhandles opened under it, while setting an option for a subhandle will only affect that handle.
If this parameter is NULL, then setting the option will affect all documents opened thereafter. Once an option is set using the NULL handle, this option becomes the default option thereafter. Note that this parameter should only be set to NULL if the option being set can take that value.
dwOptionId: The identifier of the option to be set.
pValue: Pointer to a buffer containing the value of the option.
dwValueSize: The size in bytes of the data pointed to by pValue. For a string value, the NULL terminator should be included when calculating dwValueSize.
Return Value
DAERR_OK: Returned if DASetOption succeeded. Otherwise, one of the other DAERR_ values in sccda.h or one of the SCCERR_ values in sccerr.h is returned.
This function is called to retrieve the value of a data access option. Note that the results of a call to this option are only valid if DASetOption has already been called on the option.
Prototype
DAERR DAGetOption( VTHDOC hItem, VTDWORD dwOptionId, VTLPVOID pValue, VTLPDWORD pSize);
Parameters
hItem: Identifier of open document. May be a VTHDOC returned by the DAOpenDocument function, or the subhandle returned by the DAOpenDocument or DAOpenTreeRecord functions (VTHCONTENT, VTHTEXT, and so forth). Getting an option for a VTHDOC will get the value of that option for that handle, which may be different than the subhandle's value.
dwOptionId: The identifier of the option to be returned. For a list of option IDs with descriptions, see Content Description.
pValue: Pointer to a buffer containing the value of the option.
pSize: This VTDWORD should be initialized by the caller to the size of the buffer pointed to by pValue. If this size is sufficient, the option value will be copied into pValue and pSize will be set to the actual size of the option value. If the size is not sufficient, pSize will be set to the size of the buffer needed for the option and an error will be returned.
Return Value
DAERR_OK: Returned if DAGetOption was successful. Otherwise, one of the other DAERR_ values in sccda.h or one of the SCCERR_ values in sccerr.h is returned.
This function allows the developer to retrieve the format of the file based on the technology's content-based file identification process. This can be used to make intelligent decisions about how to process the file and to give the user feedback about the format of the file they are working with.
Note: in cases where File ID returns a value of FI_UNKNOWN, then this function will apply the Fallback Format before returning a result.
Prototype
DAERR DAGetFileId( VTHDOC hDoc, VTLPDWORD pdwFileId);
Parameters
hDoc: Identifier of open document. May be a VTHDOC returned by the DAOpenDocument function, a VTHEXPORT returned by the EXOpenExport function, or the subhandle returned by the DAOpenDocument or DAOpenTreeRecord functions (VTHEXPORT, VTHCONTENT, VTHTEXT, and so forth).
pdwFileId: Pointer to a DWORD that receives a file identification number for the file. These numbers are defined in sccfi.h.
Return Value
DAERR_OK: Returned if DAGetFileId was successful. Otherwise, one of the other DAERR_ values in sccda.h or one of the SCCERR_ values in sccerr.h is returned.
This function allows the developer to retrieve the format of the file based on the technology's content-based file identification process. This can be used to make intelligent decisions about how to process the file and to give the user feedback about the format of the file they are working with. This function has all the functionality of DAGetFileID and adds the ability to return the raw FI value; in other words, the value returned by normal FI, without applying the FallbackFI setting.
Prototype
DAERR DAGetFileIdEx( VTHDOC hDoc, VTLPDWORD pdwFileId, VTDWORD dwFlags);
Parameters
hDoc: Identifier of open document. May be a VTHDOC returned by the DAOpenDocument function, or the subhandle returned by the DAOpenDocument or DAOpenTreeRecord functions (VTHEXPORT, VTHCONTENT, VTHTEXT, and so forth).
pdwFileId: Pointer to a DWORD that receives a file identification number for the file. These numbers are defined in sccfi.h.
dwFlags: DWORD that allows user to request specific behavior.
DA_FILEINFO_RAWFI: This flag tells DAGetFileIdEx() to return the result of the File Identification operation before Extended File Ident. is performed and without applying the FallbackFI value.
Return Value
DAERR_OK: Returned if DAGetFileIdEx was successful. Otherwise, one of the other DAERR_ values in sccda.h or one of the SCCERR_ values in sccerr.h is returned. See the following tables for examples of expected output depending on the value of various options.
Values with RAWFI turned off
| Input file type | ExtendedFI | FallbackID | DAGetFileId | DAGetFileIdEx |
|---|---|---|---|---|
true binary |
off |
fallback value |
fallback value |
fallback value |
true binary |
on |
fallback value |
fallback value |
fallback value |
true text |
off |
fallback value |
fallback value |
fallback value |
true text |
on |
fallback value |
40XX |
40XX |
Values with RAWFI turned on
This function returns to the developer a string describing the input error code. If the error string returned does not fit the buffer provided, it is truncated.
VTVOID DAGetErrorString( DAERR deError, VTLPVOID pBuffer, VTDWORD dwBufSize);
Parameters
Error: Error code passed in by the developer for which an error message is to be returned.
pBuffer: This buffer is allocated by the caller and is filled in with the error message by this routine. The error message will be a NULL-terminated string.
dwBufSize: Size of what pBuffer points to in bytes.
Return Value
none
This function returns information about the document or object pointed to by hDoc. The object may be an embedded object, a linked object, or a compressed file.
DAERR DAGetObjectInfo( VTHDOC hDoc, VTDWORD dwInfoId, VTLPVOID pInfo);
Parameters
hDoc: The handle returned by DAOpenDocument.
dwInfoId
The identifier of the requested information. Can be any of the following values:
DAOBJECT_NAME_A: Retrieves the name of the object, in 8-bit characters. pInfo points to a buffer of size DA_PATHSIZE.
DAOBJECT_NAME_W: Retrieves the name of the object in Unicode characters. pInfo points to a buffer of 16 bit characters of size DA_PATHSIZE.
DAOBJECT_FORMATID: Retrieves the file ID of the object. pInfo points to a VTDWORD value.
DAOBJECT_COMPRESSIONTYPE: Retrieves an identifier of the type of compression used to store the object, if known. pInfo points to a VTDWORD value.
DAOBJECT_FLAGS: Retrieves a bitfield of flags indicating additional attributes of the object. pInfo points to a VTDWORD value. Possible flag values include DAOBJECTFLAG_PARTIALFILE (would not normally exist outside the source document), DAOBJECTFLAG_PROTECTEDFILE (encrypted or password protected), DAOBJECTFLAG_LINKTOFILE (indicates that an OLE object is linked to the file and a corresponding file is not found on the host machine), DAOBJECTFLAG_UNIDENTIFIEDFILE (indicates that an object could not be identified), and DAOBJECTFLAG_UNSUPPORTEDCOMP (compressed with an unsupported compression), and DAOBJECTFLAG_ARCKNOWNENCRYPT (see note below).
DAOBJECT_ALTSTRING_A: Retrieves the alternate string describing the object, in 8-bit characters. pInfo points to a buffer of size DA_PATHSIZE.
DAOBJECT_ALTSTRING_W: Retrieves the alternate string describing the object, in 16-bit Unicode characters. pInfo points to a buffer of size DA_PATHSIZE.
pInfo: Destination of the requested information. The possible types are described in the preceding section about dwInfoId.
DAOBJECTFLAG_ARCKNOWNENCRYPT indicates that the object is protected by a known encryption. It can be accessed after the correct credentials (password and/or Lotus Notes id file) are provided through the File Access Callback. For more information, see DASetFileAccessCallback.
Return Values
DAERR_OK: Returned if the save was successful. Otherwise, one of the other DAERR_ values in sccda.h or one of the SCCERR_ values in sccerr.h is returned.
This function is called to retrieve the number of records in an archive file.
DAERR DAGetTreeCount( VTHDOC hDoc, VTLPDWORD lpRecordCount);
Parameters
hDoc: Identifier of open document. May be a VTHDOC returned by the DAOpenDocument function, or the subhandle returned by any of the DAOpenDocument or DAOpenTreeRecord functions (VTHCONTENT, VTHTEXT, and so forth).
lpRecordCount: A pointer to a VTLPDWORD that will be filled with the number of stored archive records.
Return Value
DAERR_OK: DAGetTreeCount was successful. Otherwise, one of the other DAERR_ values in sccda.h or one of the SCCERR_ values in sccerr.h is returned.
DAERR_BADPARAM: The selected file does not contain an archive section, or the requested record does not exist.
This function is called to retrieve information about a record in an archive file.
DAERR DAGetTreeRecord( VTHDOC hDoc, PSCCDATREENODE pTreeNode);
Parameters
hDoc: Identifier of open document. May be a VTHDOC returned by the DAOpenDocument function, or the subhandle by any of the DAOpenDocument or DAOpenTreeRecord functions (VTHCONTENT, VTHTEXT, and so forth).
pTreeNode: A pointer to a PSCCDATREENODE structure that will be filled with information about the selected record.
Return Values
DAERR_OK: DAGetTreeRecord was successful. Otherwise, one of the other DAERR_ values in sccda.h or one of the SCCERR_ values in sccerr.h is returned.
DAERR_BADPARAM: The selected file does not contain an archive section, or the requested record does not exist.
DAERR_EMPTYFILE: Empty file.
DAERR_PROTECTEDFILE: Password protected or encrypted file.
DAERR_SUPFILEOPENFAILS: Supplementary file open failed.
DAERR_FILTERNOTAVAIL: The file's type is known, but the appropriate filter is not available.
DAERR_FILTERLOADFAILED: An error occurred during the initialization of the appropriate filter.
This structure is passed by the OEM through the DAGetTreeRecord function. The structure is defined in sccda as follows:
typedef struct SCCDATREENODEtag{
VTDWORD dwSize;
VTDWORD dwNode;
VTBYTE szName[1024];
VTDWORD dwFileSize;
VTDWORD dwTime;
VTDWORD dwFlags;
VTDWORD dwCharSet;
} SCCDATREENODE, *PSCCDATREENODE;
Parameters
dwSize: Must be set by the OEM to sizeof(SCCDATREENODE).
dwNode: The number of the record to retrieve information about. The first node is node 0.
szName: A buffer to hold the name of the record.
dwFileSize: Returns the file size, in bytes, of the requested record.
dwTime: Returns the timestamp of the requested record, in MS‐DOS time.
dwFlags: Returns additional information about the node. It can be a combination of the following:
SCCDA_TREENODEFLAG_FOLDER: Indicating that the selected node is a folder and not a file.
SCCDA_TREENODEFLAG_SELECTED: Indicating that the node is selected.
SCCDA_TREENODEFLAG_FOCUS: Indicating that the node has focus.
SCCDA_TREENODEFLAG_ENCRYPT: Indicating that the node is encrypted and can not be decrypted.
SCCDA_TREENODEFLAG_ARCKNOWNENCRYPT: indicating that the node is encrypted with an unknown encryption and can not be decrypted.
SCCDA_TREENODEFLAG_BUFFEROVERFLOW: the name of the node was too long for the szName field.
dwCharSet: Returns the SO_* (charsets.h) character set of the characters in szName. The output character set is either the default native environment character set or Unicode if the SCCOPT_SYSTEMFLAGS option is set to SCCVW_SYSTEM_UNICODE.
This function is called to open a record within an archive file and make it accessible by one or more of the data access technologies.
DAERR DAOpenTreeRecord( VTHDOC hDoc, VTLPHDOC lphDoc, VTDWORD dwRecord);
lphDoc is not a file handle.
Parameters
hDoc: Identifier of open document. May be a VTHDOC returned by the DAOpenDocument function, or the subhandle returned by the DAOpenDocument or DAOpenTreeRecord functions (VTHCONTENT, VTHTEXT, and so forth).
lphDoc: Pointer to a handle that will be filled with a value that uniquely identifies the document to data access. The developer will use this handle in subsequent calls to data access to identify this particular document.
dwRecord: The record in the archive file to be opened.
Return Value
DAERR_OK: Returned if DAOpenTreeRecord was successful. Otherwise, one of the other DAERR_ values in sccda.h or one of the SCCERR_ values in sccerr.h is returned.
This function is called to open a record within an archive file and make it accessible by one or more of the data access technologies. It is similar to DAOpenTreeRecord, except that instead of reading the data for all nodes in the archive in a sequential order, this function will only read the data for the requested nodes from the archive. To use this function, you must first process the archive with Content Access or Search Export and save the Node Locator data for later use in this function.
DAERR DAOpenRandomTreeRecord( VTHDOC hDoc, VTLPHDOC lphDoc, SOTREENODELOCATOR sTreeNodeLocator )
lphDoc is not a file handle.
Parameters
hDoc: Identifier of open document. This hDoc must come from an archive document opened with DAOpenDocument with the flag DAOPENDOCUMENT_ARCHIVEONLYMODE set.
lphDoc: Pointer to a handle that will be filled with a value that uniquely identifies the document to data access. The developer will use this handle in subsequent calls to data access to identify this particular document.
sTreeNodeLocator: An SOTREENODELOCATOR structure which contains data identifying the desired node. This data should come from a previous conversion of the archive document using Content Access or Search Export.
Return Value
DAERR_OK: Returned if DAOpenRandomTreeRecord was successful. Otherwise, one of the other DAERR_ values in sccda.h or one of the SCCERR_ values in sccerr.h is returned.
typedef struct DATREENODELOCATORtag
{
VTDWORD dwSize; /* size of this structure */
VTDWORD dwSpecialFlag; /* special flags coming from CA or SX */
VTDWORD dwData1; /* dwData1 coming from CA or SX */
VTDWORD dwData2; /* dwData2 coming from CA or SX */
}SCCDATREENODELOCATOR, *PSCCDATREENODELOCATOR;
This content type contains information to be used in the SOTREENODELOCATOR structure, which is used by DAOpenRandomTreeRecord and DASaveRandomTreeRecord.
SCCCA_TREENODELOCATOR Content Description
dwType: SCCCA_TREENODELOCATOR
dwSubType: Reserved
dwData1: SOTREENODELOCATOR.dwSpecialFlags
dwData2: SOTREENODELOCATOR.dwData1
dwData3: SOTREENODELOCATOR.dwData2
dwData4: Reserved
pDataBuf: Not used
This function saves a copy of the document or object pointed to by hDoc. The object may be an embedded object, a linked object or a compressed file.
Some file formats store only partial files as embedded objects. Outside In will not be able to create readable files from these objects. It is recommended that you use DAGetObjectInfo with dwInfoId set to DAOBJECT_FLAGS to discern which objects Outside In will be able to successfully extract.
DAERR DASaveInputObject( VTHDOC hDoc, VTDWORD dwSpecType, VTLPVOID pSpec, VTDWORD dwFlags);
Parameters
hDoc: The handle returned by DAOpenDocument.
dwSpecType: Describes the contents of pSpec. Together, dwSpecType and pSpec describe the location of the source file to which the file will be extracted. Must be one of the following values:
IOTYPE_ANSIPATH: Windows only. pSpec points to a NULL-terminated full path name using the ANSI character set and FAT 8.3 (Win16) or NTFS (Win32 and Win64) filename conventions.
IOTYPE_REDIRECT: Specifies that redirected I/O will be used to save the file.
IOTYPE_UNICODEPATH: Windows only. pSpec points to a NULL-terminated full path name using the Unicode character set and NTFS (Win32 and Win64) file name conventions.
IOTYPE_UNIXPATH: X Windows on UNIX platforms only. pSpec points to a NULL-terminated full path name using the system default character set and UNIX path conventions. Unicode paths can be accessed on UNIX platforms by using a UTF-8 encoded path with IOTYPE_UNIXPATH.
pSpec: File location specification.
dwFlags: Currently not used. Should be set to 0.
Return Values
DAERR_OK: Returned if the save was successful. Otherwise, one of the other DAERR_ values in sccda.h or one of the SCCERR_ values in sccerr.h is returned.
This function is called to extract a record in an archive file to disk.
DAERR DASaveTreeRecord( VTHDOC hDoc, VTDWORD dwRecord, VTDWORD dwSpecType, VTLPVOID pSpec, VTDWORD dwFlags);
Parameters
hDoc: Handle that uniquely identifies the document to data access. NOTE: This is not an operating system file handle.
dwRecord: The record in the archive file to be extracted.
dwSpecType: Describes the contents of pSpec. Together, dwSpecType and pSpec describe the location of the source file to which the file will be extracted. Must be one of the following values:
IOTYPE_ANSIPATH: Windows only. pSpec points to a NULL-terminated full path name using the ANSI character set and FAT 8.3 (Win16) or NTFS (Win32 and Win64) filename conventions.
IOTYPE_REDIRECT: Specifies that redirected I/O will be used to save the file.
IOTYPE_UNICODEPATH: Windows only. pSpec points to a NULL-terminated full path name using the Unicode character set and NTFS (Win32 and Win64) file name conventions.
IOTYPE_UNIXPATH: X Windows on UNIX platforms only. pSpec points to a NULL-terminated full path name using the system default character set and UNIX path conventions. Unicode paths can be accessed on UNIX platforms by using a UTF-8 encoded path with IOTYPE_UNIXPATH.
pSpec: File location specification.
dwFlags: Currently not used. Should be set to 0.
Return Values
DAERR_OK: Returned if the save was successful. Otherwise, one of the other DAERR_ values in sccda.h or one of the SCCERR_ values in sccerr.h is returned.
DAERR_UNSUPPORTEDCOMP: Unsupported Compression Encountered.
DAERR_PROTECTEDFILE: The file is encrypted.
DAERR_BADPARAM: The request option is invalid. The record is possibly a directory.
Otherwise, one of the other DAERR_ values in sccda.h is returned.
This function is called to extract a record in an archive file to disk. It is similar to DASaveTreeRecord, except that instead of reading the data for all nodes in the archive in a sequential order, this function will only read the data for the requested nodes from the archive. To use this function, you must first process the archive with Content Access or Search Export and save the Node Locator data for later use in this function.
DAERR DASaveRandomTreeRecord( VTHDOC hDoc, SOTREENODELOCATOR sTreeNodeLocator, VTDWORD dwSpecType, VTLPVOID pSpec, VTDWORD dwFlags)
Parameters
hDoc: Identifier of open document. This hDoc must come from an archive document opened with DAOpenDocument with the flag DAOPENDOCUMENT_ARCHIVEONLYMODE set.
sTreeNodeLocator: An SOTREENODELOCATOR structure which contains data identifying the desired node. This data should come from a previous conversion of the archive document using Content Access or Search Export.
dwSpecType: Describes the contents of pSpec. Together, dwSpecType and pSpec describe the location of the source file to which the file will be extracted. Must be one of the following values:
IOTYPE_ANSIPATH: Windows only. pSpec points to a NULL-terminated full path name using the ANSI character set and FAT 8.3 (Win16) or NTFS (Win32 and Win64) filename conventions.
IOTYPE_REDIRECT: Specifies that redirected I/O will be used to save the file.
IOTYPE_UNICODEPATH: Windows only. pSpec points to a NULL-terminated full path name using the Unicode character set and NTFS (Win32 and Win64) file name conventions.
IOTYPE_UNIXPATH: X Windows on UNIX platforms only. pSpec points to a NULL-terminated full path name using the system default character set and UNIX path conventions. Unicode paths can be accessed on UNIX platforms by using a UTF-8 encoded path with IOTYPE_UNIXPATH.
pSpec: File location specification
dwFlags: Currently not used. Should be set to 0.
Return Value
DAERR_OK: Returned if DASaveTreeRecord was successful. Otherwise, one of the other DAERR_ values in sccda.h or one of the SCCERR_ values in sccerr.h is returned.
typedef struct DATREENODELOCATORtag
{
VTDWORD dwSize; /* size of this structure */
VTDWORD dwSpecialFlag; /* special flags coming from CA or SX */
VTDWORD dwData1; /* dwData1 coming from CA or SX */
VTDWORD dwData2; /* dwData2 coming from CA or SX */
}SCCDATREENODELOCATOR, *PSCCDATREENODELOCATOR;
This content type contains information to be used in the SOTREENODELOCATOR structure, which is used by DAOpenRandomTreeRecord and DASaveRandomTreeRecord.
SCCCA_TREENODELOCATOR Content Description
dwType: SCCCA_TREENODELOCATOR
dwSubType: Reserved
dwData1: SOTREENODELOCATOR.dwSpecialFlags
dwData2: SOTREENODELOCATOR.dwData1
dwData3: SOTREENODELOCATOR.dwData2
dwData4: Reserved
pDataBuf: Not used
This function is called to close an open record file handle.
DAERR DACloseTreeRecord( VTHDOC hDoc);
Parameters
hDoc: Identifier of open record document.
Return Value
DAERR_OK: Returned if DACloseTreeRecord was successful. Otherwise, one of the other DAERR_ values in sccda.h or one of the SCCERR_ values in sccerr.h is returned.
This function sets up a callback that the technology will periodically call into to verify that the file is still being processed. The customer can use this with a monitoring process to help identify files that may be hung. Since this function will be called more frequently than other callbacks, it is implemented as a separate function.
Use of the Status Callback Function
An application's status callback function will be called periodically by Outside In to provide a status message. Currently, the only status message defined is OIT_STATUS_WORKING, which provides a "sign of life" that can be used during unusually long processing operations to verify that Outside In has not stopped working. If the application decides that it would not like to continue processing the current document, it may use the return value from this function to tell Outside In to abort.
The status callback function has two return values defined:
OIT_STATUS_CONTINUE: Tells Outside In to continue processing the current document.
OIT_STATUS_ABORT: Tells Outside In to stop processing the current document.
The following is an example of a minimal status callback function.
VTDWORD MyStatusCallback( VTHANDLE hUnique, VTDWORD dwID, VTSYSVAL
pCallbackData, VTSYSVAL pAppData)
{
if(dwID == OIT_STATUS_WORKING)
{
if( checkNeedToAbort( pAppData ) )
return (OIT_STATUS_ABORT);
}
return (OIT_STATUS_CONTINUE);
}
Prototype
DAERR DASetStatCallback(DASTATCALLBACKFN pCallback, VTHANDLE hUnique, VTLPVOID pAppData)
Parameters
pCallback: Pointer to the callback function.
dwID: Handle that indicates the callback status.
OIT_STATUS_WORKING
OIT_STATUS_CONTINUE
OIT_STATUS_ABORT
pCallbackData: Currently always NULL
Return Values
DAERR_OK: If successful. Otherwise, one of the other DAERR_ values in sccda.h or one of the SCCERR_ values in sccerr.h is returned.
This function sets up a callback that the technology will call into to request information required to open an input file. This information may be the password of the file or a support file location.
Use of the File Access Callback
When the technology encounters a file that requires additional information to access its contents, the application's callback function will be called for this information. Currently, only two different forms of information will be requested: the password of a document, or the file used by Lotus Notes to authenticate the user information.
The status callback function has two return values defined:
SCCERR_OK: Tells Outside In that the requested information is provided.
SCCERR_CANCEL: Tells Outside In that the requested information is not available.
This function will be repeatedly called if the information provided is not valid (such as the wrong password). It is the responsibility of the application to provide the correct information or return SCCERR_CANCEL.
Prototype
DAERR DASetFileAccessCallback (DAFILEACCESSCALLBACKFN pCallback);
Parameters
pCallback: Pointer to the callback function.
Return Values
DAERR_OK: If successful. Otherwise, one of the other DAERR_ values in sccda.h or one of the SCCERR_ values in sccerr.h is returned.
The callback function should be of type DAFILEACCESSCALLBACKFN. This function has the following signature:
typedef VTDWORD (* DAFILEACCESSCALLBACKFN)(VTDWORD dwID, VTSYSVAL pRequestData, VTSYSVAL pReturnData, VTDWORD dwReturnDataSize);
dwID – ID of information requested:
OIT_FILEACCESS_PASSWORD – Requesting the password of the file
OIT_FILEACCESS_NOTESID – Requesting the Notes ID file location
pRequestData – Information about the file.
typedef struct {
VTDWORD dwSize; /* size of this structure */
VTWORD wFIId; /* FI id of reference file */
VTDWORD dwSpecType; /* file spec type */
VTVOID *pSpec; /* pointer to a file spec */
VTDWORD dwRootSpecType; /* root file spec type */
VTVOID *pRootSpec; /* pointer to the root file spec */
VTDWORD dwAttemptNumber; /* The number of times the callback has */
/* already been called for the currently */
/* requested item of information */
} IOREQUESTDATA, * PIOREQUESTDATA;
pReturnData – Pointer to the buffer to hold the requested information – for OIT_FILEACCESS_PASSWORD and OIT_FILEACCESS_NOTESID, the buffer is an array of WORD characters.
dwReturnDataSize – Size of the return buffer.
Not all formats that use passwords are supported. Only Microsoft Office binary (97-2003), Microsoft Office 2007, Microsoft Outlook PST 97-2013, Lotus NSF, PDF (with RC4 encryption), and Zip (with AES 128 & 256 bit, ZipCrypto) are currently supported.
Passwords for PST/OST files must be in the Windows single-byte character set. For example, Cyrillic characters should use the 1252 character set. For PST/OST files, Unicode password characters are not supported.