The standard way of calling M-Files API is synchronously, meaning that the outgoing call blocks the execution until the call completes.

The Vault object of the M-Files API offers an entry point to the interface that reflects the functionality of all Vault operation interfaces, but asynchronously. The asynchronous interface can be accessed through the Vault.Async property, and it is functional when M-Files API is used in the client mode, making this technique applicable in UI Extensibility applications.

With asynchronous calls the client can perform multiple operations on the server simultaneously, or perform a long-lasting operation while keeping the user interface responsive.

Invoking Asynchronous Calls

Asynchronous calls are invoked by using the operation interfaces on the Vault.Async property. The code below illustrates how a normal synchronous call and its asynchronous counterpart are formed.

// Check out the object (objver) synchronously.
var objectVersion = vault.ObjectOperations.CheckOut( objver.ObjID );

// Check out the object (objver) asynchronously.
vault.Async.ObjectOperations.CheckOut( objver.ObjID,      
  function ( objectVersion ) {
   
    // ...
  } );

When invoking an asynchronous call, you can use the same method name and operation interface as when invoking a synchronous call. The method input parameters of an asynchronous call are also the same as with a synchronous call, but after the input parameters, the asynchronous method takes from 0 to 3 optional callback functions as parameters. These functions specify the operation that takes place when the call returns a value.

The additional function parameters are as follows:

1. Handler for a successful call. The handler receives one parameter, which is the return value from the method.
2. Handler for a failed call. Receives three parameters: a short error message, a detailed error message, and the error object.
3. Final handler for cleanup code. Receives no parameters but is executed after both a successful and a failed call.

When the asynchronous call is invoked, the call request with the parameters are stored to the call queue. Therefore, each input parameter (as well as the return value) must be cloneable. All basic types can be cloned, but if the input parameter or the output value is an object, it must have a Clone method. After the call is stored to the queue, the program flow continues. Asynchronous calls are executed in multiple separate threads, and the invocation time order may change.

Handling Asynchronous Call Results

The callback methods are called when the M-Files API call is completed and the results (or an error) is ready. However, in order to have a callback, a Windows message pump must run. Normally this happens very frequently, but long sleep, delay, or tight busy-loop may prevent the message processing and therefore delay callback messages.

Below is an example of an asynchronous call with all callback functions set in place.

 // Check out the object.
 vault.Async.ObjectOperations.CheckOut( objver.ObjID,      
   function ( objectVersion ) {
  
     // Succeeded.
     // ...
   },  
   function ( shorterror, longerror, errorobj ) {
  
     // Failed. Report the error.
     MFiles.ReportException( errorobj );
   },  
   function () {
   
     // Final cleanup.
     // ...
   } );