CreateRTSystemImage

int CreateRTSystemImage (char IPAddress[], char outputDirPath[], int options, ProgressCallbackType callback, void *callbackData);

Purpose

Creates an image of the target RT system that you can use for system restoration or cloning. Call ApplyRTSystemImage to apply an image to a target system.

An image is a snapshot of an RT system configuration. By default, an image encompasses the entire C:\ volume. If the system also has a Windows installation, the image is limited to the files directly in C:\ and everything under the C:\NI-RT directory. LabWindows/CVI implements images as a local copy of the relevant files and directories of the target system. This implementation makes it possible to hand-edit an image to add, remove, rename, or replace files or directories in any way you want.

Images are useful for restoring a known, working configuration to a system that has become cluttered or unstable over time. Also, because an image is a complete archive of the files on a system at a given time, saving periodic images can be useful for tracking system state over time for quality assurance. Saving an image also makes it possible to install or restore drivers and software from a host Windows machine that does not have any drivers or NI Measurement & Automation Explorer (MAX) installed.

Using images for cloning can simplify the process of deploying a particular system configuration to multiple production targets. Once you configure and test your development system, you can create an image of that system and apply it to any number of unconfigured, identical systems.

You can specify RTUtilOption_GetSoftwareOnly in the options parameter to create an image that contains only core system files and software/drivers installed by MAX. A software-only image is useful as a clean, baseline configuration that you can use as a common starting point for multiple systems or for purging a system of all extraneous programs, data files, and so on that you have added or created over time.

To prevent other applications from interfering with the image creation process, this function locks the target system with the password kilgoretrout for the duration of the operation. If you locked the system with a different password, LabWindows/CVI restores the password after the operation completes.

Windows This function is supported only on Windows.

Parameters

Input
Name	Type	Description
IPAddress	char []	The IP address or DNS-resolvable hostname of the system to image.
outputDirPath	char []	The directory in which to store the system image. If the path does not exist, the function creates the path. An image is comprised of many files, so National Instruments recommends that you specify a new directory for every distinct image you create. Note  Existing files in the directory may be overwritten by files in the new image. National Instruments highly recommends that you empty your image directory before you create the image; CreateRTSystemImage considers any files in the image directory to be part of the image and copies the files to target systems when you apply the image.
options	int	A bit field consisting of 0 or more RTUtilOption flags bitwise OR-ed together. You can specify the following flags: Flag Description RTUtilOption_RunInNewThread The function returns immediately without waiting for the operation to complete. The operation is carried out asynchronously in a new thread. You must register a callback to get progress updates or a return code for the asynchronous operation. RTUtilOption_GetSoftwareOnly The created image should only contain system files and software packages installed from NI Measurement & Automation Explorer (MAX). This option is useful for capturing the NI driver/software configuration of a system without including user programs or other data or output files.
callback	ProgressCallbackType	A callback function that receives notification of events that occur on the system. You can pass NULL if you do not want to register a callback. The callback function, type ProgressCallback, takes the following form: int CVICALLBACK CallbackFunc (const char *systemIP, const char *systemMAC, int event, void *eventData1, void *eventData2, void *callbackData); The callback is executed in a separate thread every time a RTUtilEvent occurs on the system. If you are interested only in certain events, your callback must examine the event parameter passed in. The systemIP parameter contains the IP address of the system for which the event occurred. The systemMAC parameter contains the system MAC address. The callback return value is ignored. You do not need to explicitly unregister your callback. The callback stop receiving notifications once the operation for which it was registered has completed. Just before the callback is unregistered, it receives the RTUtilEvent_CallbackUnregistered event to indicate that it is safe to clean up callbackData, if necessary. The following lists RTUtilEvent events and relevant details for each event: Event Description RTUtilEvent_NewSystemStatus The status of the system changed. eventData1 (int *)—Pointer to the new status. One of RTSystemStatus_Rebooting, RTSystemStatus_Initializing, RTSystemStatus_Connected, RTSystemStatus_Disconnected, RTSystemStatus_Unconfigured, RTSystemStatus_Unknown RTUtilEvent_BeginCreateImage Beginning image creation operation. RTUtilEvent_EndCreateImage Finished image creation operation. eventData1 (int *)—Pointer to the return code. RTUtilEvent_BeginApplyImage Beginning image application operation. RTUtilEvent_EndApplyImage Finished image application operation. eventData1 (int *)—Pointer to the return code. RTUtilEvent_BeginFormatSystem Beginning system HD format operation. RTUtilEvent_EndFormatSystem Finished system HD format operation. eventData1 (int *)—Pointer to the return code. RTUtilEvent_EnumRemoteFiles Enumerating files on the remote system. RTUtilEvent_CreateLocalDirs Creating local image directory hierarchy. RTUtilEvent_BeginTransferFiles Beginning transfer of a batch of files to/from the remote system. eventData1 (int *)—Pointer to the number of files. RTUtilEvent_EndTransferFiles Finished transferring a batch of files to/from the remote system. eventData1 (int *)—Pointer to the number of failures. eventData2 (const char *)—Semicolon-separated list of failed file paths. RTUtilEvent_DeleteExistingFiles Deleting files and/or directories from the remote system. eventData1 (int *)—Pointer to the number of files to delete. eventData2 (int *)—Pointer to the number of directories to remove. RTUtilEvent_CheckingForSafeMode Checking that the remote system is booted into safe mode. RTUtilEvent_RebootIntoSafeMode Rebooting the remote system into safe mode. RTUtilEvent_RebootIntoInstallMode Rebooting the remote system into install mode. RTUtilEvent_BeginReboot Rebooting the remote system. RTUtilEvent_BeginFormattingHD Beginning hard drive format. RTUtilEvent_EndFormattingHD Hard drive finished reformatting. RTUtilEvent_GetFile Getting a file from the remote system. eventData1 (const char *)—File path (local). eventData2 (int *)—Pointer to the 0-based index (in the batch). RTUtilEvent_PutFile Sending a file to the remote system. eventData1 (const char *)—File path (remote). eventData2 (int *)—Pointer to the 0-based index (in the batch). RTUtilEvent_DeleteFile Deleting a file from the remote system. eventData1 (const char *)—File path. eventData2 (int *)—Pointer to the 0-based index (in the batch). RTUtilEvent_DeleteDir Deleting a directory from the remote system. eventData1 (const char *)—Directory path. eventData2 (int *)—Pointer to the 0-based index (in the batch). RTUtilEvent_CreateLocalDir Creating a local directory. eventData1 (const char *)—Directory path. eventData2 (int *)—Pointer to the 0-based index (in the batch). RTUtilEvent_CreateRemoteDir Creating a directory on the remote system. eventData1 (const char *)—Directory path. eventData2 (int *)—Pointer to the 0-based index (in the batch). RTUtilEvent_CallbackUnregistered The callback is about to be unregistered. You can deallocate callbackData if necessary.
callbackData	void *	A pointer-width value the library passes to the callback function through the callbackData parameter. You can use the callbackData as an integer value or as a pointer to a data object you want to access in the callback function. This way, you do not have to declare the data object as a global variable.

Return Value

Additional Information

Library: Real-Time Utility Library

Include file: rtutil.h

LabWindows/CVI compatibility: LabWindows/CVI 8.5 and later