ApplyRTSystemImage

Download PDF

Updated2023-02-21
5 minute(s) read

User Manual

int ApplyRTSystemImage (char IPAddress[], char imagePath[], int options, ProgressCallbackType callback, void *callbackData);

Purpose

Applies an image to a target system, replacing its current configuration with that of the image. Call CreateRTSystemImage to create an image.

The target system must have an IP address in order to be imaged. You can configure a target IP stack by calling SetRTIPConfiguration. The imaging process preserves a target IP stack configuration and hostname.

Before copying the image to the target system, ApplyRTSystemImage deletes every file and directory on the C:\ drive. If the target system has a Windows installation, ApplyRTSystemImage deletes only the \NI-RT directory.

Note Images created from Windows dual boot RT systems contain some Windows system files from the root directory. Because of this, National Instruments recommends that you not apply such an image to a different Windows dual boot system because the system files on the target are overwritten by the ones from the image, potentially corrupting the Windows installation.

To prevent other applications from interfering with the imaging process, ApplyRTSystemImage 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 imaging completes.

Windows This function is supported only on Windows.

Parameters

Input

Name Type Description

IPAddress char [] IP address or DNS-resolvable hostname of the system to image.

You cannot apply an image to a system that is freshly formatted or otherwise unconfigured. You must first call SetRTIPConfiguration to configure its IP address and reboot it with RebootRTSystem.

imagePath char [] The path to the image directory. This is the directory that contains the RTCtrlr.ini file.

Images are not compatible across different controller models because the drivers in an image are model-specific. You must specify an image that was created from a model that matches the target system.

options

int

A bitfield consisting of 0 or more RTUtilOptions bitwise OR-ed together:

RTUtilOption_RunInNewThread	The function should return 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_RequireSystemMatch	Ensure that the specified image only be applied to the system from which it was created. By default, an image must only match the target system's device code (i.e. hardware model). This option imposes an additional restriction that source and target machines not only be the same model of system, but actually be the same system.

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

Name	Type	Description
status	int	Return value indicating whether the function was successful. Unless otherwise stated, zero indicates successful execution and a negative number indicates that an error occurred. You can call the GetRTUtilErrorString function to obtain a message that describes the error.

Additional Information

Library: Real-Time Utility Library

Include file: rtutil.h

LabWindows/CVI compatibility: LabWindows/CVI 8.5 and later

Example

Refer to realtime\RTSystemImaging\RTSystemImaging.cws for an example of using the ApplyRTSystemImage function.

LabWindows/CVI Real-Time Module