The ImportHistory method imports a previously exported
conversation history file and restores it as the active conversation
history for the client session. Imported messages and responses become
part of the current session history and are treated the same as messages
generated during the current session.
Importing conversation history replaces the existing history associated
with the client session. This method does not merge imported messages
with the current conversation history or append them to the existing
session. It is not necessary for your application to call
ClearHistory prior to calling this function.
If the FileName parameter specifies a directory or
device name, the method will fail. It is permitted to use
environment variables in the file name by surrounding the variable
name with the percent symbol. If the file name contains any leading or
trailing space characters, they will be removed. The file must exist
and the current process must have permission to read the file.
If the MessageCount parameter is non-zero, only the most
recent messages and responses in the import file are restored. If the
specified count exceeds the number of available messages in the file,
all available messages are imported. If the total number of messages
to be imported exceeds the current history size, the function will
only import the most recent messages up to that limit. For example, if
the import file contains 20 messages and the value of the
HistorySize property is
15, the most recent 15 messages will be imported.
The import file must contain valid UTF-8 encoded JSON data in a
format compatible with the ExportHistory method. If the
file does not appear to contain a valid conversation history, the
import operation fails before the current session history is cleared.
After the JSON data has been successfully parsed, the current session
history is cleared before the imported messages and responses are added
to the client session. If an error occurs while processing imported
messages or responses, the previous conversation history cannot be
restored and partial import data may remain in the current session.
If the import file contains malformed message or response data,
the LastError property will return stErrorInvalidMessageFormat.
Because imported history files may contain sensitive or private
information, applications should take reasonable precautions to protect
them. Applications which allow users to import conversation history
should consider warning users before importing untrusted or unknown
files.