PosCommon.UpdateFirmware Method (POS for .NET v1.12 SDK Documentation)

2/27/2008

Updates the firmware of a device with the version of the firmware contained or defined in the file specified by the firmwareFileName parameter regardless of whether that firmware’s version is newer than, older than, or the same as the version of the firmware already in the device.

Namespace: Microsoft.PointOfService
Assembly: Microsoft.PointOfService (in microsoft.pointofservice.dll)

Syntax

'Declaration
Public Overridable Sub UpdateFirmware ( _
    firmwareFileName As String _
)

public virtual void UpdateFirmware (
    string firmwareFileName
)

public:
virtual void UpdateFirmware (
    String^ firmwareFileName
)

public void UpdateFirmware (
    String firmwareFileName
)

public function UpdateFirmware (
    firmwareFileName : String
)

Parameters

• firmwareFileName
  Specifies either the name of the file that contains the firmware or a file that contains a set of firmware files that are to be downloaded into the device.

Remarks

When UpdateFirmware is invoked, the Service Object should check that the specified firmware file exists and that its contents are valid for this device. If so, this method should return immediately and the rest of the update firmware process should continue asynchronously.

The Service Object should notify applying the status of the update firmware process by raising StatusUpdateEvents events with values of StatusUpdateFirmwareProgress + an integer between 1 and 100 that indicates the completion percentage of the update firmware process. For application convenience, the StatusUpdateEvent event value StatusUpdateFirmwareComplete is defined to be the same value as StatusUpdateFirmwareProgress + 100.

For consistency, the update firmware process is complete after the new firmware has been downloaded into the physical device, any necessary physical device reset has finished, and the Service Object and the physical device have been returned to the state they were in before the update firmware process began.

For consistency, a Service Object must always raise at least one StatusUpdateEvent with an incomplete progress completion percentage (that is, a percentage between 1 and 99), even if the device cannot physically report the progress of the update firmware process. If the update firmware process is completed successfully, the Service Object must raise a StatusUpdateEvent event with a progress of 100 or use the special constant StatusUpdateFirmwareComplete, which has the same value. These Service requirements allow applications that use this method to be designed to always expect some level of progress notification.

If an error is detected during the asynchronous part of an update firmware process, one of the following StatusUpdateEvent events is raised.

Value	Meaning
StatusUpdateFirmwareFailedDeviceOK	The update firmware process failed but the device is still operational.
StatusUpdateFirmwareFailedDeviceUnrecoverable	The update firmware process failed and the device is neither usable nor recoverable through software. The device requires service to be returned to an operational state.
StatusUpdateFirmwareFailedDeviceNeedsFirmware	The update firmware process failed and the device will not be operational until another try to update the firmware is successful.
StatusUpdateFirmwareFailedDeviceUnknown	The update firmware process failed and the device is in an indeterminate state.

UpdateFirmware may throw a PosControlException with the following values:

Value	Meaning
Illegal	The CapUpdateFirmware property is set to false.
NoExist	The file specified by firmwareFileName does not exist or, if firmwareFileName specifies a file list, one or more of the component firmware files are missing.
ExtendedErrorFirmwareBadFile	The specified firmware file or files exist, but one or more are either not in the correct format or are corrupted.

Thread Safety

Any public static (Shared in Visual Basic) members of this type are thread-safe. Any instance members are not guaranteed to be thread-safe.

See Also

Reference

PosCommon Class
PosCommon Members
Microsoft.PointOfService Namespace
CapUpdateFirmware