How to properly use Ranger Shutdown()

Why can't we call Shutdown() in every Ranger state?

Many low-level scanner drivers require that they be shutdown in a specific orderly sequence. If they are abruptly disconnected, it can leave the scanner and/or device driver in an unexpected, and often hung state.

As far as programming documentation goes, the description of a Ranger call in the programming guide mentions the Ranger states that a particular call can be made in. The state diagram in the manual also graphically describes this.

In the case of Shutdown(), it can be called when Ranger is in the ChangeOptions and ReadyToFeed states. So the application is responsible for putting Ranger into one of these states before calling Shutdown().

When I write applications, I handle it this way:

When the application decides it will call Shutdown(), it checks the current Ranger state.
If Ranger is in a state where Shutdown() is allowed, the application calls Shutdown().

When Ranger is in a state where Shutdown() cannot be called yet, then the application will:

Set a variable to tell itself that it is preparing to shutdown (ex: PreparingToShutdown = true)
Then the application will call the Ranger function(s) required to bring Ranger into the target state, then let Ranger run unimpeded until the target state is reached.
The application code that handles the Ranger state changing events tests the value of PreparingToShutdown to determine if it is trying to shutdown.
Shutdown() can then be called once Ranger reaches the target state.

Never use a loop that checks the Ranger state. The OS message pump needs to run normally for the Ranger state transitions to complete properly.

There are a few scenarios which may require a couple of state transitions to end up in a state where Shutdown() is allowed.

For example, if Ranger is handling an exception.

So more than one state changing functions, may be required to bring Ranger into the target state.

One of the easiest ways to avoid problems is to disable the ability for the user to exit the application when Ranger is in a state where Shutdown() cannot be called. So if items are feeding for example, they user would not be given the ability to exit (by as disabling the "exit" button). However, once feeding has stopped, and Ranger is in the ReadyToFeed state, then the option to exit the application can be enabled.