See header file and man pages for API. All documented API details work
and are tested in the 1560 test case.

Closes #2842