C#

This section describes the C# specific language considerations.

Library properties

Library properties

Property	Value	Remarks
.NET version	.NET Framework 4.7.2	The pmpclient.net.dll is functionally verified with: .NET Framework 4.7.2
C# version	C# 7.3	For data type and function definitions.
Namespace	Pmp	To avoid name clashes, all data types are contained in their own namespace.
Library type	Shared library	Easier library updates, since the application does not have to be rebuilt when a library is updated, as long as its interface remains unchanged.
Thread safety	Thread-safe and process-safe	All functions published by the library are thread-safe and process-safe, unless explicitly stated otherwise.
Notifications	Asynchronous	The application can subscribe to asynchronous notifications to be notified of certain events. Note that these delegate methods can be called from any thread context.
Strings	UTF-8	All strings are UTF-8 encoded, unless explicitly stated otherwise.

Naming conventions

Naming conventions

Naming	Description
IsXXX	A read-only boolean property accessor method.
ReserveXXX/Dispose	Obtains a reference to a scarce resource where it is irrelevant to which instance a reference is obtained. Resources using this paradigm are not named and are not creatable nor configurable using XML controller configuration. The resource implements the System.IDisposable interface to allow for destruction of the users reference to the resource.
CreateXXX/Dispose	Obtains a reference to a dynamically created resource that does not exist when the controller is started. Resources using this paradigm are named and are creatable and configurable using XML controller configuration. The resource implements the System.IDisposable interface to allow for destruction of the resource.
SubscribeXXX	Registers a callback and outputs a subscription that is required to unsubscribe.

Standard types

The motion API uses the following standard types:

• System.IDisposable and consequently System.ObjectDisposedException

• System.Collections.IEnumerable<T>

• System.Collections.ICollection<T>

• System.DateTime

• System.Drawing.Size

For brevity the namespaces of these standard types are omitted in the documentation.

Lifetime and memory allocation

References to interfaces stay valid until the related system object is no longer referenced unless explicitly stated otherwise.

The motion API implementation allocates and owns memory for objects unless explicitly stated otherwise.

Collections

A PMP specific IDictionary is implemented that has a reduced feature set compared to the System.Collections.Generic.IDictionary<K,V>. For user modifiable collections the order of items in the collection is equal to the order in which they were added.

Callbacks

The motion API defines several delegate types. User applications can register a method conforming to such a delegate type with the motion API, to receive a callback on occurrence of an event. Upon registration, an object implementing the ISubscription interface is returned that must be used to unsubscribe a registered method from receiving callbacks.

The motion API supports multiple methods to be registered for the same event. However, user applications can make no assumptions on the order in which registered methods are called.

Attention

Within methods handling a callback it is not allowed to:

• Call any function of the motion API.

• Throw an exception. Exceptions thrown by a callback handler are not handled by the motion API and cause an unhandled exception.

Attention

A callback blocks the execution of (parts of) the motion API. It is strongly recommended to carefully weigh which actions to execute from within callback context and which actions can be executed outside of the callback context. In general it is advised to let the callback return as quickly as possible.

Error handling

The motion API handles errors by throwing exceptions of type PmpException. Typical error handling lists how a user application would typically handle a certain exception.

Typical error handling

Exception	Response
AbortedException	Retry command, ignore, or fail
AccessDeniedException	Application error, provide a filename that can be opened for reading/writing
ChecksumErrorException	Either transfer failed, or source file corrupt; retry or fail
CommunicationErrorException	Motion API implementation error, option to try again, but possible connection lost
ConnectionLostException	Controller connection was lost, reconnect to the controller and try again
ConnectionRefusedException	Initialization failure
IncompatibleException	Older/newer motion API implementation required
InvalidArgumentException	Application error, provide a valid argument
InvalidConfigException	Application error, provide a valid configuration
InvalidFormatException	Application error, provide contents in valid format
InvalidOperationException	Application error, operation not possible in current state, option to change state and try again
NotImplementedException	Requested function not implemented; not recoverable.
NullArgumentException	Application error, provide a valid argument
System.ObjectDisposedException	Requested function called on an object which is disposed; not recoverable
OutOfResourcesException	Wait for resource to become available, option to clean up old unused resources
ReadErrorException	Retry or fail
RebootedException	Controller was rebooted and connection was restored, retrieve the interface again and try again
ResourceBusyException	Wait for resource to become idle
TimeoutException	Investigate reason or try with a larger timeout
UnexpectedException	Motion API implementation error, report to Prodrive Technologies; not recoverable.
UnknownObjectException	Application error, provide a correct object reference
UnsupportedException	Application error, operation not possible (in any state)
WriteErrorException	Out of (disk) space? Retry or fail