Creating Content Handler Plug-ins

This tutorial describes how to use the NFC Content Handler API to create Content Handler plug-ins.

Context

Content Handler plug-ins can be created by implementing the pre-defined CNfcCH ECOM base class and defining the NDEF registration information in a resource file.

Prerequisites

Before you begin, refer to the following header files and NFC libraries:
  • nfcch.h (declares CNfcCH base class that must be inherited)

  • ndef.lib (NDEF message)

  • ecom.lib (ECom framework)

Steps

  1. Define the NDEF registration information of Content Handlers in a resource file. The following resource file example illustrates how two different NFC Content Handlers are registered for NDEF messages.

    Example:

    RESOURCE REGISTRY_INFO NfcOwnCHExampleInfo
        {
        // The UID of this example DLL
        dll_uid = 0xe1000001;
        interfaces = 
            {
            INTERFACE_INFO
                {
                // The NFC Content Handler ECOM interface UID
                interface_uid = 0x20018416;
                implementations = 
                    {
                    // The registration information for urn:nfc:ext:helloworld NDEF messages
                    IMPLEMENTATION_INFO
                        {
                        // The UID of this example content handler
                        implementation_uid = 0xe1000002;
                        version_no = 1;
                        display_name = "NfcHelloWorldCH";
                        default_data = "urn:nfc:ext:helloworld";
                        opaque_data = "";
                        },
                    
                    // The registration information for urn:nfc:ext:advancedhelloworld and 
                    // urn:nfc:ext:moreadvancedhelloworld NDEF messages
                    IMPLEMENTATION_INFO
                        {
                        // The UID of this example content handler
                        implementation_uid = 0xe1000003;
                        version_no = 1;
                        display_name = "NfcAdvancedHelloWorldCH";
                        default_data = "urn:nfc:ext:advancedhelloworld||urn:nfc:ext:moreadvancedhelloworld";
                        opaque_data = "";
                        }
                    };
                }
            };
        }
    

    The first content handler is registered to listen to NDEF messages with TNF = 0x04 (NFC Forum external type) and a type "helloworld". The second Content Handler is registered to listen to NDEF messages with the same TNF (Type Name Format) value but with types "advancedhelloworld" and "moreadvancedhelloworld"

    Note:

    • The NDEF message type is defined in the default_data field.

    • It is possible to register for multiple NDEF message types in a single default_data field by using "||" as a separator.

    • The following list describes the mapping between default_data field and NFC Forum NDEF specification:

      • urn:nfc:wkt:<TYPE> => TNF = NFC Forum well-known type (0x01), where <TYPE> is the NFC Forum NDEF record type.

      • urn:nfc:ext:<TYPE> => TNF = NFC Forum external type (0x04), where <TYPE> is the NFC Forum NDEF record type.

  2. Implement the NFC Content Handler using the CNfcCH::HandleNdefMessage() method. The following code snippet illustrates an example of CNfcHelloWorldCH::HandleNdefMessage() method:

    Example:

    void CNfcHelloWorldCH::HandleNdefMessage( TRequestStatus& aRequestStatus,
                                              CNdefMessage& aMessage,
                                            )
        {
        TInt err = KErrNone;
        
        // KRequestPending needs to be assigned to the TRequestStatus
        TRequestStatus status = &aRequestStatus
        status = KRequestPending;
        
        // Handle aMessage here!
        
       
        // Finally the request needs to be completed
        User::RequestComplete( status, err );
        }
    

    Note: The CNfcCH::HandleNdefMessage() function is called when the NFC server receives an NDEF message and the registry information of NFC Content Handler matches the TNF and type of the NDEF message.

  3. Grant the NFC Content Handler capabilites.

    The Content Handler Loader has the following capabilities. To be loaded by the Content Handler Loader, the same capabilities must be granted to your Content Handler plug-in.

    • LocalServices
    • ReadUserData
    • WriteUserData
    • NetworkServices
    • UserEnvironment
    • Location
    • SwEvent
    • ReadDeviceData
    • WriteDeviceData

Related information