CRMCLink::WriteImage Method

Writes the specified controller image to the controller and applies it to the controller. By default, the image will be saved to flash and the controller will be restarted. The controller image must be obtained using the ReadImage method. For saving and restoring the controller image using a file, use the ReadImageToFile and WriteImageFromFile methods. This method is only supported on the RMC75E, RMC150E, and RMC200 controllers.

Syntax

C++

HRESULT WriteImage(

UINT flags,

long const* data,

UINT count

);

Parameters

flags

Options to use when applying the image. Refer to the RMCTools documentation on the Image Area for a current list of options. As of this writing, a single option has been defined. Specify zero (0) to use default options.

+0	Save Image to Flash, and Restart Controller to Apply
+16	Apply Image Immediately and Save To Flash (not supported by RMC200)

data

A pointer to the array of long values containing the controller image. This data must have been created using the ReadImage method.

count

The length (in long elements) of the array passed into the data parameter.

Return Value

Returns S_OK on success. Otherwise, an error code is returned. Possible error codes are listed below.

Remarks

This method is synchronous, which means that it will not return until the write is completed, which may take several seconds. If this method is called on the main thread, then the application will likely be unresponsive until this method completes. For applications where this is not acceptable, this and other synchronous methods should be called from a worker thread, and may use the CancelRequest method to cancel an in progress request.

Error Codes

Member Name	Description
E_OUTOFMEMORY	Out of memory.
E_INVALIDARG	The flags parameter has an unsupported value.
RMCLINK_E_DISCONNECTING	Link is being disconnected by another thread.
RMCLINK_E_DISCONNECTED	The link has not been connected.
RMCLINK_E_SOCK_INTERNAL	Internal socket error.
RMCLINK_E_CANCELLED	Operation cancelled by call to CancelRequest.
RMCLINK_E_TIMEOUT	Operation timed out.
RMCLINK_E_SOCK_GRACEFUL_CLOSE	TCP/IP connection closed by remote device.
RMCLINK_E_SOCK_ERROR_RD	Connection error while waiting for response from the remote device.
RMCLINK_E_SOCK_INV_RD_LEN	Connection error while waiting for response from the remote device.
RMCLINK_E_SOCK_ERROR_WR	Connection error while sending request to the remote device.
RMCLINK_E_SOCK_INV_WR_LEN	Connection error while sending request to the remote device.
RMCLINK_E_CONN_BROKEN	Connection broken.
RMCLINK_E_PARTIAL_WRITE	Unable to send full request to the remote device.
RMCLINK_E_USB_SETTIMEOUT	Internal USB driver error.
RMCLINK_E_USB_OP_ABORT	Unsuccessful transfer of data between the PC and the controller. Ensure that the physical connection between the PC and controller is still intact.
RMCLINK_E_USB_DISCONNECT	The controller appears to have been disconnected from the USB port. Ensure that the physical connection between the PC and controller is still intact.
RMCLINK_E_NOT_SUPPORTED	Operation not supported on this controller type. The controller must be an RMC75E, RMC150E, or RMC200 with firmware supporting the image read/write.
RMCLINK_E_DL_CANT_RESET	Unable to reset Image Area for download.
RMCLINK_E_DL_FAILED	Unable to download controller image.
RMCLINK_E_BAD_IMAGE	Image format is invalid.
RMCLINK_E_APPLY_TIMEOUT	Unable to download controller image.
RMCLINK_E_APPLY_STATE	Unexpected state encountered while applying image.
RMCLINK_E_APPLY_RSTREQ	Image not applied because restart required.
RMCLINK_E_APPLY_FLASH	Error writing to flash memory while applying image.
RMCLINK_E_APPLY_NOTINRUN	Image cannot be applied without restart while in RUN mode.
RMCLINK_E_APPLY_WRONGHW	Image not applied because of hardware mismatch.

Example

The following code example illustrates the use of the WriteImage method.

C++

#include <windows.h>
#include <stdio.h>
#include "RMCLink.h"
  
void main()
{
    long* palData = NULL;
    UINT uDataLen = 0;
 
    // In order to create COM objects, we must initialize the COM sub-system.
    ::CoInitialize(0);
 
    // Create a new RMCLink object for the first controller.
    CRMCLink* pRMC = CRMCLink::CreateUSBLink(CRMCLink::dtRMC70, _T("7573091001"));
    if ( pRMC != NULL )
    {
        // Establish the connection.
        HRESULT hr = pRMC->Connect();
        if ( SUCCEEDED(hr) )
        {
            hr = pRMC->ReadImage(0, palData, uDataLen);
 
            // Close the connection.
            pRMC->Disconnect();
        }
 
        // Free the RMCLink object we created.
        delete pRMC;
    }
 
    if ( palData != NULL )
    {
        // Create a new RMCLink object for the second controller.
        CRMCLink* pRMC2 = CRMCLink::CreateUSBLink(CRMCLink::dtRMC70, _T("7573091002"));
        if ( pRMC2 != NULL )
        {
            // Establish the connection.
            HRESULT hr = pRMC2->Connect();
            if ( SUCCEEDED(hr) )
            {
                // Apply the image to the same controller.
                hr = pRMC2->WriteImage(0, palData, uDataLen);
                if ( SUCCEEDED(hr) )
                {
                    printf("Successfully copied controller image.");
                }
                // Close the connection.
                pRMC2->Disconnect();
            }
 
            // Free the RMCLink object we created.
            delete pRMC2;
        }
 
        // Free the data allocated by ReadImage().
        delete[] palData;
    }
 
    // Release the COM sub-system.
    ::CoUninitialize();
}