CAF and the user interface

It should be assumed that it is only possible for CAF agents to display dialogs on screen if the CAF function is called from a thread where a static Uikon environment exists.

CAF provides several APIs that allow a client application to request an agent to display information on the screen. Some agents may not support these calls and leave with KErrCANotSupported.

Both the ContentAccess::CContent::DisplayInfoL() function and the ContentAccess::CManager::DisplayInfoL() function allow the application to display file information such as last modification date and/or DRM rights information

CManager *manager = CManager::NewL(); 
manager->DisplayInfoL(EFileProperties, virtualPath);    

Applications can also ask a particular agent to go into management mode, displaying configuration information on screen, allowing the user to view and set agent specific information.

// create manager 
CManager *manager = CManager::NewL(); 
        
// Get a list of the agents 
RPointerArray <CAgent> theAgents; 
manager->ListAgentsL(theAgents); 

// Display management info for the first agent 
manager->DisplayManagementInfoL(*theAgents[0]);

The agents will display errors on screen when they occur. Once the error has been acknowledged by the user, the agent will return the error code to the client application.

If a client application does not want errors displayed on screen, it can request to disable the agent UI using the SetProperty() functions, for example ContentAccess::CContent::SetProperty(). The agent may ignore this request and still present dialogs on screen.

CContent *content = CContent::NewL(URI); 
    
// Disable UI 
content->SetProperty(EAgentPropertyAgentUI, 0); 

// Open CData 
CData *data = content->OpenContent(EPlay, uniqueId);

Some agents may present confirmation dialogs to the user before allowing them to perform certain operations. A good example would be when an application tries to delete a DRM protected file. The user may have purchased the content and may have pressed delete by accident. The agent can present a dialog asking "are you sure?"

The agent can then return the outcome of the deletion to the application, i.e. KErrCancel, if the user presses cancel.

The application can use the same SetProperty() function as above to disable these dialogs, but some agents may ignore that request and display the dialogs regardless.

The default implementation of the F32AgentUI.DLL does not do anything. If licensees want the F32Agent to display information on the screen they should replace the existing F32AgentUI.DLL with one that does support display functions.