Managing CAF agents

There are some operations performed on agents that do not relate directly to a particular content file. The ContentAccess::CManager interface includes some functions that allow an application to work with a particular agent.

Before working with one particular agent, the client will need to find out which agents are installed on the device. The ContentAccess::CManager::ListAgentsL() function provides this list of agents. The F32Agent is not included in the list, since it does not support any management functions.

The ContentAccess::CAgent objects in the list can be used to refer to the particular agent in subsequent function calls.

// Create a CManager object 
CManager* manager = CManager::NewL(); 

RPointerArray <CAgent> theAgents; 

// Get the list of agents 
manager->ListAgents(theAgents); 

// Check there is at least one agent 
if(theAgents.Count() > 0) 
    {
    // Find the first agent 
    CAgent& agent = theAgents[0];        
    } 

The management API allows applications to request that an agent display management information on the screen. The agent could present configuration settings, status or DRM rights information. Each agent will have unique settings so it is not possible to display one dialog to configure all agents.

// Create a CManager object 
CManager* manager = CManager::NewL(); 

RPointerArray <CAgent> theAgents; 

// Get the list of agents 
manager->ListAgents(theAgents); 

// Check there is at least one agent 
if(theAgents.Count() > 0) 
    {               
    CAgent& agent = (*theAgents)[0]; 

    // Display the management information for the first agent 
    manager->DisplayManagementInfoL(agent);  
    }                                                   

It is possible that some agents will not support this capability and will leave with KErrCANotSupported.

Displaying DRM rights information is only relevant for agents implementing a DRM scheme. It is expected that an agent implementing DRM will provide some or all of the following functionality in the dialog:

• Display all rights objects including state (pending, valid, expired, orphaned, etc.)

• Display detailed information on a particular rights object (play count, validity period, the related content object(s))

• Allow unwanted, expired or orphaned rights to be deleted.

The rights management object is only relevant for agents implementing a DRM scheme. Other agents will leave with KErrCANotSupported.

An application can ask a particular DRM agent to create a ContentAccess::CRightsManager object that can be used to provide generic access to DRM rights within that agent. Since it is a generic interface used by all agents, it will not be able to present all the detailed information available.

CRightsManager *rightsmanager; 

// Create a CManager object 
CManager* manager = CManager::NewL(); 
    
... 

// create the rights manager object for a particular agent 
rightsManager = manager->CreateRightsManagerL(agent); 
                        
// do rights management stuff

To manage the rights in a more comprehensive manner, the application should use the ContentAccess::CManager::DisplayManagementInfoL() function, where the agent can present its own comprehensive information.

This is an extension mechanism to allow a client to perform an agent-specific function. The application will need to know the extended commands that the agent supports and the format of the input and output buffers used in the command. All of this is specified by the CAF agent, not the Content Access Framework.

The buffers allow agent specific objects to be externalized by an application, passed through CAF and internalized by the agent. The same principle applies for data returned from the agent to the application.

TInt FancyApplicationFunction(CManager& aManager, CAgent& aAgent, CFancyAgentInputObject& aInputObject, CFancyAgentOutputObject& aOutputObject)
    {
    // Buffer large enough to hold the expected output object 
    TBuf <1000> outputBuffer; 

    // Dynamic buffer to serialize aInputObject 
    CBufFlat* inputBuffer = CBufFlat::NewL(50); 
    CleanupStack::PushL(inputBuffer); 
    RBufWriteStream streamIn(*inputBuffer); 
    CleanupClosePushL(streamIn); 

    // write aInputObject to the dynamic buffer 
    aInputObject.ExternalizeL(streamIn); 
    CleanupStack::PopAndDestroy(&streamIn); 

    // Call the agent specific function #42 
    aManager.AgentSpecificCommand(aAgent, 42 ,inputBuffer->Ptr(0), outputBuffer); 

    // Don't need the input buffer any longer 
    delete *inputBuffer; 
    inputBuffer = NULL; 

    // Create a stream object to read the output buffer           
    RDesReadStream streamOut(outputBuffer); 

    // Build the output object from the output stream 
    aOutputBuffer.InternalizeL(streamOut); 
    }