Merge pull request #787 from Matthew-J625/docs-editor/iprofadmin-setdefaultprofile-1732662406

lindalu-MSFT · web-flow · commit a0b471afb1a5 · 2024-12-02T13:24:18.000-08:00
Document MAPI "App" Profiles
diff --git a/docs/outlook/mapi/iprofadmin-copyprofile.md b/docs/outlook/mapi/iprofadmin-copyprofile.md
@@ -53,12 +53,16 @@ HRESULTCopyProfile(
   
 > [in] A bitmask of flags that controls how the profile is copied. The following flags can be set:
 
+MAPI_APP_PROFILE
+
+> Allows copying an "app" profile.  This flag must be set if the existing profile is an "app" profile.
+> 
+> This flag may not be recognized or supported in all MAPI implementations.
+
 MAPI_DIALOG
-  
-> Displays a dialog box that prompts the user for the correct password of the profile to copy. If this flag is not set, no dialog box is displayed.
 
+> Displays a dialog box that prompts the user for the correct password of the profile to copy. If this flag is not set, no dialog box is displayed.
 ## Return value
-
 S_OK
   
 > The profile was successfully copied.
@@ -71,6 +75,10 @@ MAPI_E_LOGON_FAILED
   
 > The password for the profile to copy is incorrect, and a dialog box could not be displayed to the user to request the correct password because MAPI_DIALOG was not set in the _ulFlags_ parameter.
 
+MAPI_E_NO_ACCESS
+
+> The existing profile is an "app" profile, and the MAPI_APP_PROFILE flag was not set.
+
 MAPI_E_NOT_FOUND
   
 > The specified profile does not exist.
@@ -91,7 +99,9 @@ The name of the original profile, its password, and the copy can be up to 64 cha
 Profile passwords are not supported on all operating systems. On operating systems that do not support profile passwords, _lpszOldPassword_ can be NULL or a pointer to a zero-length string.
   
 If  _lpszOldPassword_ is set to NULL, the profile to be copied requires a password, and the MAPI_DIALOG flag is set; a dialog box that prompts the user to provide the password is displayed. If a password is required, but  _lpszOldPassword_ is set to NULL and the MAPI_DIALOG flag is not set, **CopyProfile** returns MAPI_E_LOGON_FAILED.
-  
+
+If the existing profile is an "app" profile, and the MAPI_APP_PROFILE flag is not set, **CopyProfile** returns MAPI_E_NO_ACCESS.  If the existing profile is an "app" profile, and the MAPI_APP_PROFILE is set, the new profile will also be an "app" profile.  If the existing profile is not an "app" profile, the new profile will not be an "app" profile regardless of the MAPI_APP_PROFILE flag.
+
 ## See also
 
 [IProfAdmin : IUnknown](iprofadminiunknown.md)
diff --git a/docs/outlook/mapi/iprofadmin-createprofile.md b/docs/outlook/mapi/iprofadmin-createprofile.md
@@ -49,7 +49,13 @@ HRESULT CreateProfile(
  _ulFlags_
   
 > [in] A bitmask of flags that controls how the profile is created. The following flags can be set:
-    
+
+MAPI_APP_PROFILE
+
+> MAPI should create this profile as an "app" profile, which limits discoverability and interactions.
+> 
+> This flag may not be recognized or supported in all MAPI implementations.
+
 MAPI_DEFAULT_SERVICES 
   
 > MAPI should populate the new profile with the message services that are included in the [Default Services] section of the Mapisvc.inf file.
@@ -87,7 +93,7 @@ The name of the new profile and its password can be up to 64 characters in lengt
 - Embedded spaces, but not leading or trailing spaces.
     
 The  _lpszPassword_ parameter must be NULL or a pointer to a zero-length string. 
-  
+
 ## See also
 
 
diff --git a/docs/outlook/mapi/iprofadmin-deleteprofile.md b/docs/outlook/mapi/iprofadmin-deleteprofile.md
@@ -37,14 +37,24 @@ HRESULT DeleteProfile(
     
  _ulFlags_
   
-> [in] Always NULL. 
-    
+> [in] A bitmask of flags that controls how a profile is deleted.  The following flag can be set:
+
+MAPI_APP_PROFILE
+
+> Allows deleting an "app" profile.  This flag must be set if the profile to be deleted is an "app" profile.
+> 
+> This flag may not be recognized or supported in all MAPI implementations.
+
 ## Return value
 
 S_OK 
   
 > The profile was successfully deleted.
-    
+
+MAPI_E_NO_ACCESS
+
+> The profile is an "app" profile, and the MAPI_APP_PROFILE flag was not set.
+
 MAPI_E_NOT_FOUND 
   
 > The specified profile does not exist.
@@ -56,7 +66,9 @@ The **IProfAdmin::DeleteProfile** method deletes a profile. If the profile to de
 The entry point function for each message service in the profile is called with the MSG_SERVICE_DELETE value set in the _ulContext_ parameter. First, the function deletes the service, and then it deletes the service's profile section. The message service entry point function is not called again after the service has been deleted. 
   
 No password is required to delete a profile.
-  
+
+
+
 ## MFCMAPI reference
 
 For MFCMAPI sample code, see the following table.
diff --git a/docs/outlook/mapi/iprofadmin-getprofiletable.md b/docs/outlook/mapi/iprofadmin-getprofiletable.md
@@ -33,8 +33,14 @@ HRESULT GetProfileTable(
 
  _ulFlags_
   
-> [in] Always NULL.
-    
+> [in] A bitmask of flags that controls how the profile table is populated. The following flag can be set:
+
+MAPI_APP_PROFILE
+
+> Include "app" profiles in the profile table. If this flag is not set, "app" profiles are not included.
+> 
+> This flag may not be recognized or supported in all MAPI implementations.
+
  _lppTable_
   
 > [out] A pointer to a pointer to the profile table.
@@ -50,11 +56,11 @@ S_OK
 The **IProfAdmin::GetProfileTable** method provides access to the profile table, which contains one row for every available profile. There are only two columns in each row: the profile's display name, and a flag that indicates whether the profile is the default. 
   
 Profiles that have been deleted, or that are in use but have been marked for deletion, are not included in the profile table. The profile table is static; subsequent additions and deletions of profiles are not reflected in the table. 
-  
+
 If no profiles exist, **GetProfileTable** returns a table with zero rows. 
   
 For more information about the profile table, see [Profile Tables](profile-tables.md). 
-  
+
 ## MFCMAPI reference
 
 For MFCMAPI sample code, see the following table.
diff --git a/docs/outlook/mapi/iprofadmin-renameprofile.md b/docs/outlook/mapi/iprofadmin-renameprofile.md
@@ -53,18 +53,28 @@ HRESULT RenameProfile(
     
  _ulFlags_
   
-> [in] Always NULL.
-    
+> [in] A bitmask of flags that controls how the profile is renamed.  The following flag can be set:
+
+MAPI_APP_PROFILE
+
+> Allows renaming an "app" profile. This flag must be set if the profile is an "app" profile.
+> 
+> This flag may not be recognized or supported in all MAPI implementations.
+
 ## Return value
 
 S_OK 
   
 > The profile was successfully renamed.
-    
+
 MAPI_E_LOGON_FAILED 
-  
+
 > The profile password is incorrect.
-    
+
+MAPI_E_NO_ACCESS
+
+> The profile is an "app" profile, and the MAPI_APP_PROFILE flag was not set.
+
 MAPI_E_USER_CANCEL 
   
 > The user canceled the operation, typically by clicking the **Cancel** button in a dialog box. 
@@ -80,7 +90,7 @@ The old and new names of the profile can be up to 64 characters in length and ca
 - Embedded spaces, but not leading or trailing spaces.
     
 The  _lpszPassword_ should always be NULL or a pointer to a zero-length string. 
-  
+
 ## See also
 
 
diff --git a/docs/outlook/mapi/iprofadmin-setdefaultprofile.md b/docs/outlook/mapi/iprofadmin-setdefaultprofile.md
@@ -50,14 +50,17 @@ S_OK
   
 > A default profile was successfully established or removed.
     
+E_FAIL
+
+> The specified profile cannot be set as the default profile.
+
 MAPI_E_NOT_FOUND 
-  
+
 > The specified profile does not exist.
-    
 ## Remarks
 
-The **IProfAdmin::SetDefaultProfile** method either establishes a particular profile as the client's default profile or clears the current default profile. The default profile is the profile that is automatically used whenever the client begins a MAPI session. **SetDefaultProfile** also sets the new default profile's **PR_DEFAULT_PROFILE** ([PidTagDefaultProfile](pidtagdefaultprofile-canonical-property.md)) property to TRUE.
-  
+The **IProfAdmin::SetDefaultProfile** method either establishes a particular profile as the client's default profile or clears the current default profile. An "app" profile cannot be set as the default profile. The default profile is the profile that is automatically used whenever the client begins a MAPI session. **SetDefaultProfile** also sets the new default profile's **PR_DEFAULT_PROFILE** ([PidTagDefaultProfile](pidtagdefaultprofile-canonical-property.md)) property to TRUE.
+
 ## Notes to callers
 
 To start a session with the default profile, pass the MAPI_USE_DEFAULT flag to the [MAPILogonEx](mapilogonex.md) function. 
diff --git a/docs/outlook/mapi/mapilogonex.md b/docs/outlook/mapi/mapilogonex.md
@@ -59,7 +59,12 @@ HRESULT MAPILogonEx(
 MAPI_ALLOW_OTHERS 
   
 > The shared session should be returned, which allows later clients to obtain the session without providing any user credentials. 
-    
+
+MAPI_APP_PROFILE
+
+> Include "app" profiles in the logon dialog list. If this flag is not set, "app" profiles are not included.
+> This flag may not be recognized or supported in all MAPI implementations.
+
 MAPI_BG_SESSION
   
 > Log on to a session and run any operations in the background. In general, if a client intends to do processing on a background thread or in a separate process in a manner that is unobtrusive to the foreground thread, it should call with the MAPI_BG_SESSION flag. A client application such as an indexing engine or opening a Personal Folders File (PST) for background type access are some examples of where to use MAPI_BG_SESSION.MAPILogonEx.
@@ -135,7 +140,7 @@ MAPI_E_USER_CANCEL
 MAPI client applications call the MAPILogonEx function to log on to a session with the messaging system. All strings that are passed in and returned to and from MAPI calls are null-terminated and must be specified in the current character set or code page of the calling client or provider's operating system.
   
 The  _lpszProfileName_ parameter is ignored if there is an existing previous session that called MapiLogonEx with the MAPI_ALLOW_OTHERS flag set and if the flag MAPI_NEW_SESSION is not set. If the  _lpszProfileName_ parameter is NULL or points to an empty string, and the  _flFlags_ parameter includes the MAPI_LOGON_UI flag, the MAPILogonEx function generates a logon dialog box that has an empty field for the profile name. 
-  
+
 When logging on to a specific profile, a client should pass the MAPI_NEW_SESSION flag into MAPILogonEx in addition to the profile name. Otherwise, if another client has established a shared session by logging on with MAPI_ALLOW_OTHERS, the client will be logged on to the shared session instead of to the profile requested. 
   
 The MAPI_EXPLICIT_PROFILE flag does not cause the default profile name to be used when  _lpszProfileName_ is NULL or empty unless the MAPI_USE_DEFAULT flag is also present. 
