Object Methods

Introduction | Common Methods for MPI Objects
mpiObjectCreate(...) | mpiObjectDelete(...) | mpiObjectValidate(...)

Introduction

Object-oriented languages such as C++ and Java provide capabilities such as inheritance and polymorphism. The MPI is written in the C-language, and so these more exotic object-oriented features are not available. However, the basic concepts of object-oriented design are in the MPI: modularity, data hiding and no global or static data.

It's similar to C++
If you are already familiar with C++, you will quickly realize that the MPI methods that create and delete objects are patterned after C++ constructors and destructors. An MPI method takes an object as its first argument, much as a C++ method has a "this" pointer. Object data is private and available only by calling object methods. MPI source code is organized into modules, with one object per module. Library state is distributed across application-created objects; there is virtually no state information maintained by the library.

All object methods and all functions return a value indicating whether the call to them succeeded or not. In general, the return value is of type long, with a value of 0 indicating success. The return value can be treated as an MPIMessage, so that you can call the mpiMessage(...) function to obtain a text string that describes the return value. The text string that indicates a successful return value of MPIMessageOK (0) is empty ("").

All MPI objects must implement certain required methods. Note that most MPI objects implement standard configuration and memory methods; many MPI objects implement standard status and list manipulation methods and a few objects implement standard event notification methods. For multi-threaded environments, all objects must implement standard resource allocation timeout methods.

In general, there are few methods that are unique to an object, and those unique methods tend to be those that perform object-specific actions. The following sections describe the standard methods that are implemented by many objects. For specific details about objects and their methods/functions, refer to the breakdown of Objects.

Common Methods for MPI Objects

All MPI objects have four types of common methods:

Warning: The mpiControlReset(), mpiControlResetToDefault(), and mpiControlConfigSet() methods will all erase previously configured object settings. For this reason these methods must be called before creating any dependent objects, (motors, axes, recorders, etc.). If these methods are called after the creation of dependent objects and error (MPIControlMessageOBJECTS_CREATED) will be returned. Extra care must be taken for multi-threaded applications. If objects are created in one thread, these control methods may not return an OBJECTS_CREATED error if called from a different thread. The same problems associated with objects created before calling these methods applies however even if the objects are in different threads.

mpiObjectCreate(...)

Use the Create method to create an object and return a handle that uniquely identifies that object. The MPI does not support declaring an object directly, so you must always use the Create method. The Create method arguments depend on the type of object being created.

If an object cannot be created, mpiObjectCreate(…) returns an error and set the handle to MPIHandleVOID. In general, if you call a method using an object handle that is invalid, the method will fail and return a value indicating the cause of failure.

The MPI supports multiple motion controllers. Typically, an MPI application first creates a Control object that corresponds to the desired motion controller. If the application will use more than one motion controller, it must create a Control object for each motion controller. The arguments to mpiControlCreate(...) associate a Control object with a specific motion controller.

Most MPI objects are associated with a specific instance of a resource on a specific motion controller. An Axis object, for example, is associated with a single axis on a motion controller. When creating an MPI object that corresponds to a specific motion controller resource, the Create method takes an MPIControl handle as its first argument and a number as the second argument. The number argument identifies the specific motion controller resource to be used.

mpiObjectDelete(...)

Use the Delete method to delete an object created by the Create method. After an object has been deleted, the handle to that object can no longer be used.

If a method attempts to use a handle to a deleted object, it returns MPIMessageObject_FREED, but not always. If the memory originally allocated for the deleted object is subsequently allocated for a different purpose, then the method will not return MPIMessageObject_FREED.

Your application must ensure that handles to deleted objects are no longer used. After an object is deleted, your application should ensure that the handle to that object is set to MPIHandleVOID. After that, any calls to methods using this handle will return MPIMessageHANDLE_INVALID.

When your application exits, it should call Delete methods for all objects that have been created by your application. We recommend that your application delete objects in the reverse order in which they were created. Regardless, the Control object should be the last object deleted. The MPI does not provide the ability to automatically delete all of the objects that have been created.

Alternatively, to delete objects, your application may use the C library function atexit(...), which guarantees that the objects will be deleted even if the application terminates abnormally.

mpiObjectValidate(...)

Use the Validate method to validate an object handle. The Create methods will automatically validate the object handle.  The Validate method can be called at any time in an application.

If the object is valid, the Validate method will return MPIMessageOK. If the handle passed to the Validate method has value MPIHandleVOID, the Validate method returns MPIMessageHANDLE_INVALID. If a method attempts to use a handle to a deleted object, the method returns MPIMessageObject_FREED. (Also see the previous discussion in mpiObjectDelete(...)).

Other possible return values are declared in the message header file(MPI\include\message.h) and in the object's header file (MPI\include\object.h).