How To Modify Settings of MS Exchange Transport Provider (170225)
The information in this article applies to:
- Microsoft Extended Messaging Application Programming Interface (MAPI)
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.
| Modification Type: | Minor | Last Reviewed: | 8/18/2005 |
|---|
| Keywords: | kbcode kbhowto kbMsg KB170225 |
|---|
|