Symbian OS Communications (779884), страница 77
Текст из файла (страница 77)
The number can be used as an easy way todetermine if the command is being performed on the DM adapter parentTHE EXAMPLE DM ADAPTER381node, the unnamed node or a leaf node. The name of the node can thenbe used to identify which leaf node the command is for. Is it importantto remember when determining the number of nodes in the URI, that theroot node ‘.’ is stripped by the DM framework as it is not used within DMadapters.The DM framework uses a call to the interface method DDFStructureL() to retrieve the DDF information for the DM adapter. TheDM adapter builds its DDF structure by calling methods on the passedreference to an MSmlDmDdfObject object.
Each node of the MO isrepresented by an object of type MSmlDmDdfObject and the referenceprovided by the DM framework is for the root node. There are twomethods provided for adding child nodes, one is to add named nodesand the other to add unnamed nodes. These are respectively:MSmlDmDdfObject& AddChildObjectL(const TDesC8& aNodeName)MSmlDmDdfObject& AddChildObjectGroupL()Both methods return the reference to a MSmlDmDdfObject objectthat represents the new node. This reference can be used to add theDFProperty information of the node and also to create the children of thenode.voidvoidvoidvoidvoidvoidvoidvoidSetAccessTypesL(TSmlDmAccessTypes aAccessTypes)SetDefaultValueL(const TDesC8& aDefaultValue)SetDescriptionL(const TDesC8& aDescription)SetDFFormatL(TDFFormat aFormat)SetOccurenceL(TOccurence aOccurence)SetScopeL(TScope aScope)SetDFTitleL(const TDesC8& aTitle)AddDFTypeMimeTypeL(const TDesC8& aMimeType)These references to MSmlDmDdfObject objects are only valid forthe duration of the call to the DDFStructureL() method and the DMadapter must not retain pointers to them.
The format of the DDF versionis not defined by the DM framework or the OMA and can be an emptydescriptor.To assist the DM adapter in searching for the location of account data,the DM framework provides methods to set and retrieve local uniqueidentifiers (LUIDs) for each node of the management tree. These LUIDscan be used to provide mapping information between the managementtree URI and the account to which they refer. For each of the interfacemethods that handle DM commands, the DM framework will pass theLUID information for the URI. The LUIDs are available via a hierarchicalsearch, so even if the node has no LUID associated with it, the providedLUID may be from its parent or an ancestor.
The methods for setting andretrieving LUIDs are respectively:382OMA DEVICE MANAGEMENTvoid SetMappingL(const TDesC8& aUri, const TDesC8& aLuid)HBufC8* GetLuidAllocL(const TDesC8& aUri)For the example adapter, the ID of the XMPP account is used as theLUID for an unnamed node. As the LUIDs are hierarchical, the interfacemethods to handle DM commands on the children of the unnamed nodewill also be supplied the correct LUID.To indicate to the DM framework the status of a DM command, the DMcommand interface method includes an argument that has a status reference for the command.
This status reference is used by the DM adapterto indicate either a successful command handle or an error value. Thepermissible values for the returned status are defined by the enumeratedtype MSmlDmAdapter::TError and are as shown in Table 12.2.Table 12.2 Permissible values for returned statusStatus codeDescription of appropriate useEOkWhen the command has been successfulENotFoundIf the URI supplied doesn’t correspond to a validsetting in the setting store, or the LUID suppliedwith the command references a setting (or groupof settings) that is no longer valid in the mappedsettings storeEInvalidObjectIf the value expected in anUpdateLeafObjectL should belong to a set ofenumerations but wasn’t a valid member, wasn’trecognized, or isn’t supportedEAlreadyExistsIf the URI supplied corresponds to a setting that isalready in the setting storeETooLargeObjectIf the object supplied to UpdateLeafObjectLor ExecuteCommandL is too large for the settingmapped to by a URIEDiskFullIf during processing of the command anout-of-disk or out-of-memory condition occurredEErrorA general error code that can be used if no othersapplyERollbackFailedUsed to complete outstanding commands, if theRollbackAtomicL call is used but thecommand can’t be revertedTHE EXAMPLE DM ADAPTER383Table 12.2 (continued )Status codeDescription of appropriate useEObjectInUseUsed to indicate that the setting can’t bemodified, accessed or deleted because it is in useby another processENoMemoryUsed to indicate that memory allocation failedduring processing of a commandERollbackOkUsed to indicate that the roll-back operation wassuccessfulECommitOkUsed to indicate that the commit operation wassuccessfulECommitFailedUsed to indicate that the commit operation failedThe status of a command is reported to the DM framework via thecallback method:void SetStatusL(TInt aStatusRef, MSmlDmAdapter::TError aErrorCode)Standard Symbian OS error values must not be used for reporting thestatus of a command.
The setting of the status value is also used to indicateto the DM framework that the DM command has been fully handled andall result data has been returned.In a similar way to the status reference, each of the Get DM commandmethods provide the argument aResultsRef, which allows the DMadapter to specify which DM command the result data is for. The resultdata is returned via two callback methods:void SetResultsL(TInt aResultsRef, CBufBase& aObject, const TDesC8& aType)void SetResultsL(TInt aResultsRef, RReadStream*& aStream, const TDesC8&aType)The first method is used to return data that is below the streaming sizeof the DM adapter. The second method is used for returning large objectsas an RReadStream object, this allows the DM framework to read thedata in chunks to reduce the memory usage and the DM framework isresponsible for closing the RReadStream when it has finished readingthe data.The interface methods for DM commands do not exactly match thosespecified as part of the OMA DM specification.384OMA DEVICE MANAGEMENTFor Get DM commands, there are three methods:void FetchLeafObjectL(const TDesC8& aURI, const TDesC8& aLUID, constTDesC8& aType, TInt aResultsRef, TInt aStatusRef)void FetchLeafObjectSizeL(const TDesC8& aURI, const TDesC8& aLUID, constTDesC8& aType, TInt aResultsRef, TInt aStatusRef)void ChildURIListL(const TDesC8& aURI, const TDesC8& aLUID, constCArrayFix<TSmlDmMappingInfo>& aPreviousURISegmentList, TIntaResultsRef, TInt aStatusRef)The first two methods are specific to leaf nodes only, FetchLeafObjectL() is used to retrieve leaf node values, and FetchLeafObjectSizeL() is used to retrieve the size of the data that would be returned fora FetchLeafObjectL() call.
The third method, ChildURIListL(),is specific to interior nodes and the DM adapter must return a list of thechildren of the interior node – each child node in the list is separated bya ‘/’. The CArrayFix<TSmlMappingInfo> argument is provided bythe DM framework to assist in listing the children of an unnamed interiornode – the array contains a list of the children of the node and theirassociated LUIDs. Here, the first action is to get a list of all the accountIDs and use these to compare against the passed array values; this willprovide a list of known child node names. If there are accounts that areadded through routes other than the DM adapter, e.g., manually by theuser through a configuration user interface in the application, then thesealso need to be added to the list, but a new unique name will need tobe generated for them.
Any generated name should be compared to thepassed list to ensure that they are unique, and once the uniqueness of thegenerated name is confirmed, then the LUID for this new URI must beset. The easiest method of generating unique names is to use a name andappend an integer value to the end.For Add and Replace DM commands there are three methods:void UpdateLeafObjectL(const TDesC8& aURI, const TDesC8& aLUID, constTDesC8& aObject, const TDesC8& aType, TInt aStatusRef)void UpdateLeafObjectL(const TDesC8& aURI, const TDesC8& aLUID,RWriteStream*& aStream, const TDesC8& aType, TInt aStatusRef)void AddNodeObjectL(const TDesC8& aURI, const TDesC8& aParentLUID, TIntaStatusRef)The first two methods are specific to leaf nodes, and encompass boththe Add and Replace DM commands.
The third method is to add interiornodes – both named and unnamed ones. The second method is providedto support large objects – if the data being passed by the DM server isgreater than the streaming size specified by the DM Adapter, then thismethod will be called.THE EXAMPLE DM ADAPTER385For Delete DM commands there is one method:void DeleteObjectL(const TDesC8& aURI, const TDesC8& aLUID, TIntaSttusRef)For Copy DM commands there is one method:void CopyCommandL(const TDesC8& aTargetURI, const TDesC8& aTargetLUID,const TDesC8& aSourceURI, const TDesC8& aSourceLUID, const TDesC8&aType, TInt aStatusRef)For Execute DM commands there are two methods:void ExecuteCommandL(const TDesC8& aURI, const TDesC8& aLUID, constTDesC8& aArgument, const TDesC8& aType, TInt aStatusRef)void ExecuteCommandL(const TDesC8& aURI, const TDesC8& aLUID,RWriteStream*& aStream, const TDesC8& aType, TInt aStatusRef)In the methods that the DM adapter implements to handle DM commands, there are two that pass an argument of type RWriteStream.There are two further methods that the DM adapter must implement thatrelate to streaming large objects:TBool StreamingSupport(TInt& aItemSize)void StreamCommittedL(RWriteStream& aStream)StreamingSupport() is used to determine if DM adapters supportthe streaming interfaces and the size above which the DM adapterexpects the streaming interfaces to be used.
StreamCommittedL() isused by the DM framework to indicate to the DM adapter that it has readall the data from the RWriteStream object.There are three interface methods specific to atomic transactions:void StartAtomicL()void CommitAtomicL()void RollbackAtomicL()The DM framework will call StartAtomicL() to signal the start of anew transaction and all commands received before this method is calledmust be handled before this method completes.
![](https://s.studizba.com/z.php?f=/templates/si/i/noavatar.png&w=100&h=100&t=1"){kind=avatar}
