Article ID: 170225
Article Last Modified on 8/18/2005
APPLIES TO
- Microsoft Messaging Application Programming Interface
This article was previously published under Q170225
SUMMARY
This article explains how to programmatically change the values of the Microsoft Exchange Transport Provider and review those changes after they have been committed.
MORE INFORMATION
Changing the settings for the Microsoft Exchange Server service provider can be broken into two phases: creating and configuring a profile and modifying some or all of the settings of the Microsoft Exchange Server service provider.
Creating and Configuring a Profile
First follow the steps listed below to create and configure a profile. (These steps can be found on the Microsoft Developer Network (MSDN) in the article "Creating and Configuring a Profile.")
- Read the header file for each service. Understand what properties you need to configure and what values you will use.
- Call the MAPIAdminProfiles function to obtain an IProfAdmin interface. Call the CreateProfile method to create your profile, and the AdminServices method to obtain an IMsgServiceAdmin interface.
- Add message services to the profile. Refer to the previous guidelines for the order you should use. For each service, use the IMsgServiceAdmin interface to do the following :
- Call the CreateMsgService method.
- Obtain the MAPIUID structure of the service you just created:
- Call the GetMsgServiceTable method to obtain an IMAPITable interface.
- Call the HrQueryAllRows function to retrieve all rows from the table.
- Get the PR_SERVICE_UID column from the last row. This is the MAPIUID structure of the last service added. You may wish to check with an assertion that other properties of the service are as you expect.
- Call the ConfigureMsgService method, passing the MAPIUID structure of the service you just created and a property value array with its configuration properties.
- If you must make configuration calls that require an IMAPISession interface, such as IMAPISession::SetDefaultStore, IAddrBook::SetPAB, or IAddrBook::SetABSearchPath, pass the MAPI_NO_MAIL flag to the MAPILogonEx function.
- To make your profile temporary, call the IProfAdmin::DeleteProfile method immediately after logging on to the profile. It will be deleted after you log off, and will not be visible to other applications in the meantime.
Modifying Settings of Service Provider
The steps above helped you to create and configure a generic profile. In the second phase you will modify some or all of the settings of the Microsoft Exchange Server service provider. (These steps can also be found on MSDN in the article "Creating a Profile through MAPI.")
When you reach the step in which the MAPI IMsgServiceAdmin::ConfigureMsgService method is called, specify the following information in the lpProps parameter. This parameter is a pointer to an SPropValue structure containing the values of the properties to display to the user in the property sheet.
- Home Server of the application's mailbox. Use the property tag PR_PROFILE_HOME_SERVER. This property is defined in EDKMDB.H.
- Name of the application's mailbox, using the property tag PR_PROFILE_MAILBOX. This property is defined in EDKMDB.H.
Summary
Following the steps above you should have code that is comparable to the pseudo-code below.
(NOTE: The following pseudo-code uses PR_UNRESOLVE_XXX properties to configure the profile. Using the properties mentioned above generally fail to configure the service as expected.)
- Get IProfAdmin interface pointer with MAPIAdminProfiles()
- Create a new profile with IProfAdmin::CreateProfile()
- Get IMsgServiceAdmin interface pointer with IProfAdmin::AdminServices()
- Add a message service to the newly created profile with IMsgServiceAdmin::CreateMsgService()
- Get the message service table of the Message service with IMsgServiceAdmin::GetMsgServiceTable()
- Get the row from the message service table which represents the Microsoft Exchange Server service provider (MSEMS) with HrQueryAllRows()
- Set the values for PR_PROFILE_UNRESOLVED_NAME and PR_PROFILE_UNRESOLVED_SERVER with IMSgServiceAdmin::ConfigureMsgService()
- Logon to a new MAPI session using the new profile with MAPILogonEx()
- Release and reuse IMsgService and IMAPITable objects
- Get new IMsgServiceAdmin interface pointer
- Get the Message service table
- Find the row that represents the MSEMS message service
- Open the property sheet for the service with IMsgServiceAdmin::ConfigureMsgService
Sample Code
Following is one possible implementation of the pseudo-code. It is only a sample, but it meets the design goals of changing various settings of the Microsoft Exchange Service Provider and displaying the results of those changes:
#include "windows.h"
#include "edk.h"
#include "stdio.h"
#include "d:\customer\makeprofile\makeprofile\makeprofile.h"
char g_lpszProfile[256];
STDMETHODIMP ChangeMSESPSettings ( LPSTR lpszProfile, HWND hWnd )
{
HRESULT hRes = S_OK;
LPPROFADMIN pProfAdmin = NULL;
LPSERVICEADMIN pSvcAdmin = NULL;
LPMAPITABLE pMsgSvcTable = NULL;
LPSRowSet pRows = NULL;
SPropValue rgval[2];
LPMAPISESSION pSession = NULL;
SRestriction sres;
SPropValue pSvcProps;
enum {iSvcName, iSvcUID, cptaSvc};
SizedSPropTagArray (cptaSvc, sptCols) = { cptaSvc,
PR_SERVICE_NAME,
PR_SERVICE_UID };
// Copy the profile name into a global variable.
strcpy ( g_lpszProfile, lpszProfile );
for ( int i = 0; i < 2; i++)
ZeroMemory ( &rgval[i], sizeof ( SPropValue ) );
// Get IProfAdmin interface pointer.
if ( FAILED ( hRes = MAPIAdminProfiles ( 0L, &pProfAdmin ) ) )
goto Quit;
// Create a new profile -- IProfAdmin::CreateProfile()
// If the attempt to create the profile fails, remove the
// profile.
if ( FAILED ( hRes = pProfAdmin -> CreateProfile ( lpszProfile,
"",
0L,
0L ) ) )
{
hRes = pProfAdmin -> DeleteProfile ( lpszProfile, 0L );
goto Quit;
}
printf("CreateProfile worked\n");
// Get IMsgServiceAdmin interface pointer.
if ( FAILED ( hRes = GetAdminService ( &pSvcAdmin, 0L ) ) )
goto Quit;
// Add a message service to the newly created profile.
if (FAILED(hRes = pSvcAdmin->CreateMsgService ( "MSEMS",
"Microsoft Exchange",
(ULONG)hWnd,
0L ) ) )
goto Quit;
// Get the message service table of the Message service.
if ( FAILED ( hRes = pSvcAdmin->GetMsgServiceTable(0L,
&pMsgSvcTable) ) )
goto Quit;
// Get the row from the message service table that represents the
// Microsoft Exchange Server service provider.
sres.rt = RES_CONTENT;
sres.res.resContent.ulFuzzyLevel = FL_FULLSTRING;
sres.res.resContent.ulPropTag = PR_SERVICE_NAME;
sres.res.resContent.lpProp = &pSvcProps;
pSvcProps.ulPropTag = PR_SERVICE_NAME;
pSvcProps.Value.lpszA = "MSEMS";
if ( FAILED ( hRes = HrQueryAllRows ( pMsgSvcTable,
(LPSPropTagArray)&sptCols,
&sres,
NULL,
0,
&pRows ) ) )
goto Quit;
// Set the values for PR_PROFILE_UNRESOLVED_NAME and
// PR_PROFILE_UNRESOLVED_SERVER
rgval[0].ulPropTag = PR_PROFILE_UNRESOLVED_NAME;
// rgval[0].Value.lpszA = <mailbox name> ;
rgval[0].Value.lpszA = "Karenwo";
rgval[1].ulPropTag = PR_PROFILE_UNRESOLVED_SERVER;
// rgval[1].Value.lpszA = <Exchange Server Name>;
rgval[1].Value.lpszA = "Karenwo";
if ( FAILED ( hRes = pSvcAdmin -> ConfigureMsgService(
(LPMAPIUID) pRows -> aRow->lpProps[iSvcUID].Value.bin.lpb,
0, NULL, 2, rgval ) ) )
hRes = pProfAdmin -> DeleteProfile ( lpszProfile, 0L );
// Logon to a new MAPI session using new profile -- MAPILogonEx()
if ( SUCCEEDED ( hRes = MAPILogonEx ( ( ULONG )hWnd,
lpszProfile,
"",
MAPI_NEW_SESSION |
MAPI_NO_MAIL, &pSession ) ) )
{
// Release and reuse IMsgService and IMAPITable
// objects.
pSvcAdmin -> Release ( );
pMsgSvcTable -> Release ( );
FreeProws ( pRows );
pSvcAdmin = NULL;
pMsgSvcTable = NULL;
pRows = NULL;
// Get new IMsgServiceAdmin interface pointer.
hRes = pSession -> AdminServices ( 0L, &pSvcAdmin );
// Get the Message service table.
if(FAILED(hRes = pSvcAdmin->GetMsgServiceTable ( 0L,
&pMsgSvcTable ) ) )
goto Quit;
// Find the row that represents the MSEMS message service.
if ( FAILED ( hRes = HrQueryAllRows (pMsgSvcTable,
(LPSPropTagArray)&sptCols,
&sres,
NULL,
0,
&pRows ) ) )
goto Quit;
// Open the property sheet for the service.
if ( FAILED ( hRes = pSvcAdmin -> ConfigureMsgService(
(LPMAPIUID) pRows -> aRow -> lpProps[iSvcUID].Value.bin.lpb,
0,
SERVICE_UI_ALLOWED |
SERVICE_UI_ALWAYS,
5,
rgval) ) )
goto Quit;
return hRes;
}
Quit:
if ( hRes )
hRes = pProfAdmin -> DeleteProfile ( lpszProfile, 0L );
if ( pMsgSvcTable )
{
FreeProws( pRows );
pRows = NULL;
pMsgSvcTable -> Release ( );
pMsgSvcTable = NULL;
}
if ( pSvcAdmin )
{
pSvcAdmin -> Release ( );
pSvcAdmin = NULL;
}
if ( pSession )
{
pSession -> Logoff ( (ULONG)hWnd, MAPI_LOGOFF_SHARED, 0L );
pSession -> Release ( );
pSession = NULL;
}
return hRes;
}
STDMETHODIMP GetAdminService ( LPSERVICEADMIN * lppSvcAdmin,
LPMAPISESSION m_pSession)
{
HRESULT hRes = S_OK;
LPSERVICEADMIN lpSvcAdmin = NULL;
LPPROFADMIN pProfAdmin = NULL;
if(NULL!=m_pSession)
hRes = m_pSession -> AdminServices ( 0L, &lpSvcAdmin );
else
hRes = MAPIAdminProfiles(0L, &pProfAdmin);
if ( SUCCEEDED ( hRes ) )
hRes = pProfAdmin -> AdminServices( g_lpszProfile, "", 0L, 0L,
&lpSvcAdmin );
else
return hRes;
if ( SUCCEEDED ( hRes ) )
*lppSvcAdmin = lpSvcAdmin;
return hRes;
}
This code results in the messaging service property sheet for Microsoft Exchange Server service provider being displayed with the server and mailbox properties set for the profile.
Keywords: kbhowto kbmsg kbcode KB170225
