For Users
  Download Plug-ins
  Desktop Search Forum

For Developers
  Plug-in Development
  Download SDK
  Developer Guide
    Index API
    Query API
    Display API
      Script API
      Communication API
      Plug-in Design Guidelines
      Plug-in Tutorials
        Using Wizard
        Using Helper Framework
        Using ActiveX
    Action API
    Event API
    Plug-in Installer
  Submit Software
  Developer Forum
  Desktop Blog

Overview

• Getting Started
• Development Process Overview

Custom Actions Developer API

• Registering Custom Actions Plug-Ins
• Implementing Custom Actions

GoogleDesktopActionAPI.idl

Getting Started

Google Desktop Custom Actions allow plug-in developers to override the default actions when a user clicks on a specific UI item.

To implement Custom Actions and integrate your application with Google Desktop you will need, in addition to the information in this document:

• Sufficient access to write a plug-in for your application and an installer for it.
• Programming knowledge of the Microsoft Windows Component Object Model (COM).

Development Process Overview

To develop a GD Custom Action, start by downloading the SDK, in particular the GoogleDesktopActionAPI.idl file. We recommend developing your application with Microsoft Visual Studio.

You will then need to write code to:

• Register your application with the GD (required).
• Implement the required Custom Actions interfaces.
• Unregister your application with GD when your application uninstalls.

We recommend that you look over the sample code provided with the SDK. Please note that the sample code examples have their GUIDs hardcoded, so if you choose to reuse code from there you must change the interfaceIDs, classIDs, and libIDs to ones valid for your application.

Registering Custom Action Components

GD will not accept unregistered components. Custom Action component registration is a one-time process done using the IGoogleDesktopRegistrar interface, and should be done during component installation. As part of the registration process, the component must provide its GUID as well as information about itself.

As part of its own uninstallation process, a component should unregister itself with GD.

The following summarizes the interface and its methods. All method return values are of type HRESULT.

• Note: Components are required to to call this interface to register themselves with Google Desktop before they can interact with any APIs or other provided services.
  
• Note: The registration process consists of a call to StartComponentRegistration followed by individual registrations for various services obtained through GetRegistrationInterface and finished by a call to FinishComponentRegistration. For action components, the registration progid is "GoogleDesktop.ActionRegistration" and the interface is IGoogleDesktopRegisterCustomAction.
  
• StartComponentRegistration: Must be invoked by any component to initiate the registration process.
  • Arguments:
    • BSTR component_guid_or_progid: The component's GUID or ProgID.
    • VARIANT component_description: A SAFEARRAY of pairs, where the first element is a descriptive parameter name and the second element is that parameter's value. The method expects only the following three required parameters, which should be given in this order.
      • "Title": Component title that will be displayed on the GD preferences page.
      • "Description": Component description that will be displayed on the GD preferences page.
      • "Icon": A string pointing to an ICON resource, of the form "c:\program files\boo\comp.dll,23". This icon may be used to indicate the component and its results on various GD pages.
  • Returns:
    • S_OK if successful.
    • E_COMPONENT_ALREADY_REGISTERED if this component has already been registered with GD.
    • Appropriate error on failure, such as an unregistered component classID or appID, component prohibited by policy, etc.
  
  
• GetRegistrationInterface: Provides the requested type of registration interface.
  • Arguments:
    • BSTR registration_type: a stringified CLSID or a progid to the type of registration required.
    • [out, retval] IUnknown **registration_interface: provides the requested registration mechanism.
  • Returns:
    • S_OK if successful.
    • Appropriate error on failure.
  
  
• FinishComponentRegistration: Must be invoked to finish the registration process.
  • Returns:
    • S_OK if successful.
    • Appropriate error on failure, such as an unregistered component classID or appID, component prohibited by policy, etc.
  
  
• UnregisterComponent
  • Arguments:
    • BSTR component_guid_or_progid: the same GUID used when registering the component.
  • Returns:
    • S_OK if successful.
    • Appropriate error on failure.

The following template demonstrates how a component can register to handle the "Reply" action for emails. Note that this registration should only be done once, not every time the plug-in starts.

To register a component:

  CComPtr<IGoogleDesktopRegistrar> spRegistrar;
  HRESULT hr;
  
  hr = spRegistrar.CoCreateInstance(CLSID_GoogleDesktopRegistrar);
  
  if (SUCCEEDED(hr)) {
    ATLASSERT(spRegistrar != NULL);
    
    // Component description is 6 strings
    CComSafeArray<VARIANT> arr_descr(6);

    arr_descr.SetAt(0, CComVariant(L"Title"));
    arr_descr.SetAt(1, CComVariant(L"A sample action plug-in"));
    arr_descr.SetAt(2, CComVariant(L"Description"));
    arr_descr.SetAt(3, CComVariant(L"Implements sample custom actions"));
    arr_descr.SetAt(4, CComVariant(L"Icon"));
    arr_descr.SetAt(5, CComVariant(L",1"));

    // our CLSID in string format
    CComBSTR our_clsid(clsid);
    
    // Wrap description array in variant
    CComVariant descr(arr_descr.m_psa);

    // and register
    hr = spRegistrar->StartComponentRegistration(our_clsid, descr);
    if (FAILED(hr))
      return hr;

    // success, now register as a action component.
    // This two step registration allows the same plug-in to implement multiple
    // components
    CComPtr<IGoogleDesktopRegisterCustomAction> spRegistration;

    CComBSTR action_registrar_progid("GoogleDesktop.ActionRegistration");
    hr = spRegistrar->GetRegistrationInterface(action_registrar_progid,
      reinterpret_cast<IUnknown**>(&spRegistration));
    ATLASSERT(FAILED(hr) || spRegistration);

    if (SUCCEEDED(hr)) {
      CComVariant var;
      var.Clear();
      hr = spRegistration->RegisterAction(CComBSTR(CLSID_EmailActions), 
                    CComBSTR(ACTION_EMAIL_REPLY), CComVariant());

      if (SUCCEEDED(hr)) {
        hr = spRegistrar->FinishComponentRegistration();
      }
    }

To unregister a component:

  CComPtr<IGoogleDesktopRegistrar> spRegistrar;
  HRESULT hr;
  
  hr = spRegistrar.CoCreateInstance(CLSID_GoogleDesktopRegistrar);
  
  if (SUCCEEDED(hr)) { 
    // our CLSID in string format
    CComBSTR bstrClsid(clsid);
  
    hr = spRegistrar->UnregisterComponent(bstrClsid);
  }

Implementing and Handling Custom Actions

After a successful registration with GD, a component can use the Custom Action APIs to implement and override the default actions for specific user actions.

The Action API consists of a COM interface, which must be exposed by plug-ins wishing to implement custom actions. Whenever a custom action is rendered GD will query registered plug-ins about their interest in the action i.e., whether to change he action title and whether to override or perform the default action. Please note that the custom action plugins will be loaded in a COM multi-threaded apartment.

• QueryInterest: Invoked when an action is being rendered to query for the plug-ins interest in the action.
  • Arguments:
    • ACTION_LOCATION location: The GUID identifier for the location where the action is being rendered (ACTION_LOCATION_ALL is a wildcard and currently the only supported location).
    • ACTION_ID action: The GUID for the action queried (e.g., ACTION_EMAIL_REPLY, ACTION_EMAIL_REPLY, ACTION_EMAIL_FORWARD).
    • BSTR query_string: The query string, if applicable and if allowed by the user's preferences. Note: we will not implement a preference to disallow this parameter in this iteration.
    • IUnknown * item: An interface to the item being rendered, most commonly a IGoogleDesktopNotifyEvent.
    • [in, out] BSTR * action_title: If the action is handled, this string will be displayed as the action title. On input this contains the default title for the current language.
    • [out] BSTR * action_cookie: A string which will be handed back to the object if the action is performed. This could be an item specific property (e.g., "uri", "cookie") or any string combination
    • [out] ActionHandling * handling: Specifies whether and how the action should be handled (e.g., ACTION_HANDLING_DEFAULT, ACTION_HANDLING_QUENCH, ACTION_HANDLING_OVERRIDE).
  • Returns:
    • S_OK in all cases.
    • An error return may result in the removal of the plug-in's registration for this action, or until GD is restarted.
      
• HandleAction: Invoked when an action needs to be performed.
  • Arguments:
    • ACTION_LOCATION location: The identifier for the location where the action was rendered.
    • ACTION_ID action: The identifier for the action to perform.
    • BSTR query_string: The query string, if applicable and if allowed by the user's preferences.
    • IUnknown * item: An interface to the item who is rendered, most frequently this is IGoogleDesktopNotifyEvent. May be NULL in cases where it's not feasible to pass back the same instance as in QueryInterest.
    • BSTR action_cookie: The string cookie the plug-in provided in the call from QueryInterest.
  • Returns:
    • S_OK if successful.
    • Appropriate error on failure.

The following template demonstrates how a component can implement the methods on the IGoogleDesktopCustomAction interface.

When QueryInterest is invoked for an email message the plug-in will override Forward and quench Reply.

  /// IGoogleDesktopCustomAction
  STDMETHOD(QueryInterest)( 
      /* [in] */ ACTION_LOCATION location,
      /* [in] */ ACTION_ID action,
      /* [in] */ BSTR query_string,
      /* [in] */ IUnknown *item,
      /* [out][in] */ BSTR *action_title,
      /* [out] */ BSTR *action_cookie,
      /* [out] */ ActionHandling *handling) {
      ATLASSERT(NULL != query_string);
      ATLASSERT(NULL != action_title && NULL != *action_title);
      ATLASSERT(NULL != action_cookie && NULL == *action_cookie);
      ATLASSERT(NULL != handling);
      
      /// Override Forward always, quench reply always
      if (IsEqualGUID(action, ACTION_EMAIL_FORWARD)) {
        CString title(L"Overridden Forward");
        CString cookie(L"Email Forward");
        
        ATLASSERT(NULL != item);
        
        title.SetSysString(action_title);
        *action_cookie = cookie.AllocSysString();

        *handling = ACTION_HANDLING_OVERRIDE;

      } else if (IsEqualGUID(action, ACTION_EMAIL_REPLY)) {
        *handling = ACTION_HANDLING_QUENCH;
      } else {
        /// unknown 
        ATLASSERT(false && "Unregistered action in QueryInterest");
        *handling = ACTION_HANDLING_DEFAULT;
      }

      return S_OK;
    }		
		

When HandleAction is invoked the plug-in will simply display a message box with the query and action strings.

  /// IGoogleDesktopCustomAction
  STDMETHOD(HandleAction)( 
    /* [in] */ ACTION_LOCATION location,
    /* [in] */ ACTION_ID action,
    /* [in] */ BSTR query_string,
    /* [in] */ IUnknown *item,
    /* [in] */ BSTR action_cookie) {
    /// Action processing displays a message box.
    CString str;
    
    str.Format(_T("Query: %ws, action: %ws"), query_string, action_cookie);
    MessageBox(NULL, str, _T("Action!"), MB_OK | MB_SERVICE_NOTIFICATION);

    return S_OK;
  }