This continues the posts on DM adapters but I have had to break it into 3 parts as its very long because some areas are rather complicated...

The DM adapter framework functions by grouping together a number of requests and then executing them when CompleteOutstandingCmdsL is called synchronously.
This allows the adapter's underlying implementation to batch process a set of commands and deliver them to a slower client as well as allowing transactioning.

To read a setting that is not a group, its a simple matter to call FetchLeafObjectL with the relevant URI and mime type and the adapter will return the value back when CompleteOutstandingCmdsL is called.When an adapter method is called, two ids are also sent with the request. This allows the data that is returned to be identified to  particular transaction and the second allows the actual status of the transaction to be identified.  In practise these are normally made the same.

Calling FetchLeafObjectL and CompleteOutstandingCmdsL will result in two call backs being generated for the class implementing MSmlDmAdapter that was supplied
to the adapter instance when it was created. The first callback will be the status of the call. This will be via the SetStatusL method that was implemented in callback handler. This will return the error code (if any) for that particular transaction.

The second callback will be the actual data for the call. This will be the data and the mime type of the data. Since the data being returned is in the form of a binary blob he actual type of the blob is also required so that it can be decoded by the caller into a suitable format for redelivery to the application or forwarding onto another caller.
 
To write a setting that is not a group, its a simple matter to call UpdateLeafObjectL with the relevant URI, mimetype and the update will occur when CompleteOutstandingCmdsL is called. (I am going to defer the discusion of GUID and LUID values for the next post)

Reading a group is slightly more complicated by the fact that the resultant data needs to be parsed. If the endpoint of the URI is a group then calling ChildURIListL will  return a string in the form of child fragment1/childfragment2/childfragment3 which needs to be split using the '/' character into its individual components of the child URI. Of course there are additional commands to do the other node operations such as DeleteObjectL, AddNodeObjectL, ExecuteCommandL and CopyCommandL all of which do what they say. It is worth noting however that DeleteObjectL will delete all children as well as well as the node in the tree.
 
Inside the DM adapter there are additional transaction commands, StartAtomic, CommitAtomic, RollbackAtomic. These commands function in conjunction with the CompleteOutstandingCmdsL method and work in a similar manner to database transactions. If the adapter is not inside a transaction, then each of the operations in the queued operations list will be executed nd the results of the operations (failure or success) reported to the caller via SetStatusL and so cannot be rolled back if there is an error. However, if before any updates are added to the adapter, StartAtomic is called, all operations that are made via for example UpdateLeafObjectL will be queued as normal and when CompleteOutstandingCmdsL is called will they be executed. This will then execute all the deferred commands, calling SetStatusL
and SetResultsL for each of the operations. If all the operations succeeded, the caller should then call CommitAtomic and this will make all the changes to the adapter permanent. If any of the operations failed, the caller should call RollbackAtomic and the adapter will attempt to restore its state to what it was at the StartAtomic call. Note it is also possible for the Rollback to fail, in which case the results of this will be returned via the SetStatusL callback.

Some adapters also support streaming for large objects. For example if the data the adapter needs is coming from or going to a slow medium then the the adapter may request or respond  with a stream to supply the data in chunks. It is easy to check whether the adapter supports streaming by calling the StreamingSupport method. This returns the size of the data above which the stream methods will be used instead of the blob methods. ETrue is returned if the adapter supports streaming.

There is one API that causes more problems than all the other API's combined. This is the FetchLinkL method and will be the subject of a subsequent post.
The next posting will be on the GUID/LUID mess that form parts of the parameter list...