MAPI Boolean Service Capability Constants

4/8/2010

These constants represent capabilities supported by a transport. The messaging application can query the transport for and set these capabilities.

Constant	Value	Description
kszCapHTMLMail	L"HTMLMail"	The transport is capable of processing HTML mail.
kszCapAutoPostMeetingResponse	L"AutoPostMeetingResponse"	The transport is capable of automatically posting a default response to a Meeting Request.
kszCapAmountToFetch	L"FetchSize"	The transport is capable of setting the amount of text body retrieved during synchronization.
kszCapAttachAmount	L"AttachFetchSize"	The transport is capable of setting the size of attachments retrieved during synchronization.
kszCapAgeFilter	L"AgeFilter"	The transport is capable of filtering messages according to age (i.e., do not retrieve messages older than).
kszCapSaveSent	L"SaveSent"	The transport is capable of saving sent items locally.
kszCapSMSUnicode	L"SMSUnicode"	The transport is capable of processing Unicode Short Message Service (SMS) messages.
kszCapSMSDeliveryNotify	L"SMSDeliveryNotify"	The transport supports delivery notifications for Short Message Service (SMS) messages.
kszCapSMTPAuthenticate	L"SMTPAuthenticate"	The transport supports SMTP authentication.
kszCapIncludeOriginal	L"IncludeOriginal"	The transport is capable of including the original message along with replies and forwarded messages.
kszCapIndentBody	L"IndentBody"	The transport is capable of indenting the body of messages.
kszCapAddLeading	L"AddLeading"	The transport is capable of adding leading (providing extra space above and below each line of text) to messages.
kszCapLeadChar	L"LeadChar"	No longer supported.
kszCapSyncMsgClasses	L"SyncMsgClasses"	The transport supports these message classes.
kszCapSyncMsgClassDef	L"SyncMsgClassDef"	The default message class the transport supports.
kszCapPropDialog	L"PropDialog"	The transport supports showing a property dialog box, and has a default value of FALSE.
kszCapSyncHierarchy	L"SyncHierarchy"	The transport is capable of recreating a folder hierarchy during synchronization.
kszCapDeleteAction	L"DeleteAction"	The transport supports the delete actions DELACTION_IMMEDIATELY and DELACTION_MANUALLY.
kszCapMoveToTrash	L"TrashMoves"	The transport is capable of moving message items to the Deleted folder.
kszCapReturnAddress	L"ReturnAddress"	The transport supports the return address property.
kszCapCurrentService	L"CurrentService"	The transport supports the current service property.
kszCapCreateSpecialFldrs	L"CreateSpecialFolders"	The transport supports the creation of special folders such as the Inbox, Outbox, and search-results.
kszCapFolders	L"Folders"	The transport recognizes the use of folders in the message store. The default value is TRUE. Overrides the defaults in IMailSyncHandler::GetCapability.
kszCapFolderNotifications	L"FolderNotifications"	The transport supports folder change notifications. The default value is FALSE. Overrides the defaults in IMailSyncHandler::GetCapability.
kszCapClearAll	L"ClearAll"	The transport supports Clear All Items, and the default value is TRUE.
kszCapEmptyDeleteItem	L"EmptyDeleteItem"	The transport supports the capability to empty the deleted items folder, and the default value is TRUE.
kszCapEditProperties	L"EditProperties"	The transport allows the editing of properties, and the default value is TRUE.
kszCapFolderOptions	L"EmptyFolderOptions"	The transport supports the capability of setting options for emptying folder contents, and the default value is TRUE.
kszCapMgmtFolder	L"MgmtFolder"	The transport supports folder management, and the default value is TRUE.
kszCapSync	L"Sync"	The transport supports synchronization of the message store, and the default value is TRUE.
kszCapSyncOnDockEvent	L"SyncOnDockEvent"	The transport supports the synchronize on docking event, and the default value is TRUE.
kszCapConnect	L"Connect"	The transport supports the connection event, and the default value is TRUE.
kszCapRequireRadio	L"RequireRadio"	Use of the transport requires a radio transceiver, and the default value is FALSE.
kszCapMarkAttachments	L"MarkAttachments"	The transport supports the ability to mark attachments, and the default value is FALSE.
kszCapReplyAll	L"ReplyAll"	The transport supports the ability to reply to all recipients, and has a default value of TRUE. Cannot be TRUE if there is no compose capability.
kszCapAlwaysIncludeOriginal	L"AlwaysIncludeOriginal"	The transport supports the capability to always include the original message along with replies and forwarded messages, and the default value is FALSE.
kszCapCompose	L"Compose"	The transport supports the capability to compose new messages, and the default value is TRUE.
kszCapOfflineStatus	L"OfflineStatus"	The transport supports capability to detect the offline status event, and the default value is TRUE.
kszCapCallSender	L"CallSender"	The transport supports the capability to call the sender, and the default value is FALSE.
kszCapLanguage	L"Language"	The transport supports the capability to detect language, and the default value is TRUE.
kszCapAttachments	L"Attachments"	The transport supports the capability to send and receive attachments, and the default value is TRUE.
kszCapFolderManagementAllowCreate	L"FolderManagementAllowCreate"	The transport supports the capability of folder creation, and the default value is TRUE.
kszCapFolderManagementAllowRename	L"FolderManagementAllowRename"	The transport supports the capability of folder renaming, and the default value is TRUE.
kszCapFolderManagementAllowDelete	L"FolderManagementAllowDelete"	The transport supports the capability of folder deletion, and the default value is TRUE.
kszCapCannotSendMeetingRequests	L"CannotSendMeetingRequests"	The transport is not capable of sending meeting requests, and the default value is FALSE.
kszCapClearAllOnServer	L"ClearAllDeletesFromServer"	The transport supports clearing all deleted items from the server, and the default value is TRUE.
kszCapServiceFromMessage	L"ServiceFromMessage"	The transport does not rely upon another transport. Only used in IMailSyncCallBack::GetGlobalSetting. To handle this, the kszCapServiceFromMessage capability constant returns a pointer to the IMailSyncHandler interface, which corresponds to a given message. A pointer to the message is passed in the SPropVal passed into IMailSyncCallBack::GetGlobalSetting. > [!NOTE] > This behavior is slightly different than other capabilities, which use this parameter only as an OUT parameter, not an IN/OUT parameter.
kszCapFollowUpFlags	L"FollowUpFlags"	The transport supports tagging Message items with flags for follow-up. The default value is FALSE.
kszCapImmediateDownload	L"ImmediateDownload"	The transport supports the ability to fetch the rest of the message contents, on a per-message basis (as opposed to just tagging the message so the rest of the message downloads during the next AutoUpdate or Send/Receive). The default value is FALSE.
kszCapSwitchFormat	L"SwitchFormat"	This capability specifies whether a transport is able to retrieve messages in the format specified in the PR_CE_PENDING_BODY_FORMAT property, regardless of the transport's preferred download format (as specified in the PR_CE_PREFERRED_DOWNLOAD_FORMAT property). When a transport supports the ability to deliver HTML messages in Plain Text as well as HTML, and the account is configured to retrieve HTML messages in Plain Text format (to conserve resources)—users have the option to fetch the native HTML version of a message. The Get HTML menu item is hidden for transports that do not support format switching, and is visible but disabled when format switching is supported by at least one transport besides the current transport. The IMAP transport supports format switching. The ActiveSync transport supports format switching only if it also supports per-item operations. The POP transport does not support format switching. This constant is used with the IMailSyncHandler::GetCapability method. > [!NOTE] > This capability differs from kszCapHTMLMail in that if a transport supports downloading HTML mail, it can still disregard the PR_CE_PENDING_BODY_FORMAT property—which might differ among the batch of messages being downloaded. The default value is FALSE.
kszCapConnectHomeNetwork	L"ConnectHomeNetwork"	This capability specifies whether a transport is able to establish a non-roaming connection to the server. The default value is TRUE. For more information, see the code example below.

Example

The following code example demonstrates how a custom transport might use the MAPI Boolean Service Capability Constants in its implementation of IMailSyncHandler::GetCapability, which allows a messaging application to query the transport to determine if it supports a particular capability.

Note

To make the following code example easier to read, security checking and error handling are not included. This code example should not be used in a release configuration unless it has been modified to include them.

HRESULT CSampleMailSyncHandler::GetCapability(LPCWSTR pszName, LPSPropValue pval)
{
    HRESULT hr = S_OK;
    if (NULL == pszName || NULL == pval)
    {
        hr = E_INVALIDARG;
    }
    else if (0 == wcscmp(pszName, kszCapMarkAttachments))
    {
        // Marking attachments is supported.
        pval->ulPropTag = PT_LONG;
        pval->Value.ul = (ULONG)TRUE;
    }
    else if (0 == wcscmp(pszName, kszCapMgmtFolder))
    {
        // Folder management is not supported.
        pval->ulPropTag = PT_LONG;
        pval->Value.ul = (ULONG)FALSE;
    }
    else if (0 == wcscmp(pszName, kszCapAgeFilter))
    {
        // Age filter feature is experimental. Default to FALSE unless overridden by registry.
        LONG lResult;
        HKEY hkey = NULL;
        
        pval->ulPropTag = PT_LONG;
        pval->Value.ul = (ULONG)FALSE;

        lResult = RegOpenKeyEx(HKEY_LOCAL_MACHINE, TEXT("\\Software\\SampleHandler\\Settings"), 0, 0, &hkey);

        if (ERROR_SUCCESS == lResult)
        {
            DWORD dwValue = 0;
            DWORD cbValue = sizeof(dwValue);

            lResult = RegQueryValueEx(hkey, TEXT("AgeFilter"), NULL, NULL, (LPBYTE)&dwValue, &cbValue);

            if (ERROR_SUCCESS == lResult && dwValue)
            {
                // Overridden by registry key.
                pval->Value.ul = (ULONG)TRUE;
            }
        }

        if (NULL != hkey)
        {
            RegCloseKey(hkey);
        }
    }
    else
    {
        // Unhandled capability, let application use default value.
        hr = MAPI_E_NOT_FOUND;
    }
    return hr;
}

Function Name:	GetCapability. For more information, see IMailSyncHandler::GetCapability.
Purpose:	Provide a way for Messaging to query whether the transport supports a particular set of capabilities.

Arguments

pszName	[in] To find out if the transport supports a particular service capability, you supply the string value for that service capability. These string values come from the Value column in the table above.
pval	[in]/[out] You supply an SPropValue structure that the transport then uses for setting the property value.

Return Values

S_OK	Indicates success.
E_INVALIDARG	Indicates that invalid arguments were passed into the function.
MAPI_E_NOT_FOUND	Indicates that the transport does not support the service capability.

The following code example demonstrates how to use the kszCapConnectHomeNetwork constant. Before issuing a Connect or Synchronize command to the IMailSyncHandler, the messaging application can query the transport for its roaming status so it can then warn the user about potential roaming charges. The application can use IMailSyncHandler::GetCapability with kszCapConnectHomeNetwork specified as the pszName argument.

The IMailSyncHandler will return a non-zero PT_LONG value in the LPSPropValue pval [out]-parameter if it is able to establish a non-roaming connection to the server. If only a roaming connection is available, then the returned value is zero.

Note

To make the following code example easier to read, security checking and error handling are not included. This code example should not be used in a release configuration unless it has been modified to include them.

BOOL fPerformSync = TRUE;
SPropValue val;

hr = pSyncHandler->GetCapability(kszCapConnectHomeNetwork, &val);

if (SUCCEEDED(hr) && !val.Value.ul)
{
   // Warn the user about roaming charges.
   if (IDCANCEL == ::MessageBox(hwnd,
                                L"Synchronizing may incur additional roaming charges.",
                                L"Warning", MB_OKCANCEL | MB_ICONWARNING | MB_DEFBUTTON2))
   {
      fPerformSync = FALSE;
   }
}

if (fPerformSync)
{
   hr = pSyncHandler->Synchronize(pMailSyncRequest);
}

See Also

Reference

IMessageFormHostEx::GetGlobalSetting
IMailSyncHandler::SetCapability
IMailSyncHandler::GetCapability
IMailSyncCallBack::GetGlobalSetting
IMessageFormHostEx::GetGlobalSetting

Other Resources

MAPI Constants