libmapi/IProfAdmin.c File Reference

MAPI Profiles interface. More...

#include <libmapi/libmapi.h>

Functions

_PUBLIC_ enum MAPISTATUS ChangeProfilePassword (const char *profile, const char *old_password, const char *password)
_PUBLIC_ enum MAPISTATUS CreateProfile (const char *profile, const char *username, const char *password, uint32_t flag)
_PUBLIC_ enum MAPISTATUS CreateProfileStore (const char *profiledb, const char *ldif_path)
_PUBLIC_ enum MAPISTATUS DeleteProfile (const char *profile)
_PUBLIC_ enum MAPISTATUS FindProfileAttr (struct mapi_profile *profile, const char *attribute, const char *value)
_PUBLIC_ enum MAPISTATUS GetDefaultProfile (char **profname)
_PUBLIC_ enum MAPISTATUS GetProfileAttr (struct mapi_profile *profile, const char *attribute, unsigned int *count, char ***value)
_PUBLIC_ enum MAPISTATUS GetProfileTable (struct SRowSet *proftable)
_PUBLIC_ enum MAPISTATUS LoadProfile (struct mapi_profile *profile)
_PUBLIC_ enum MAPISTATUS mapi_profile_add_string_attr (const char *profile, const char *attr, const char *value)
_PUBLIC_ enum MAPISTATUS mapi_profile_delete_string_attr (const char *profname, const char *attr, const char *value)
_PUBLIC_ const char * mapi_profile_get_ldif_path (void)
_PUBLIC_ enum MAPISTATUS mapi_profile_modify_string_attr (const char *profname, const char *attr, const char *value)
_PUBLIC_ enum MAPISTATUS OpenProfile (struct mapi_profile *profile, const char *profname, const char *password)
_PUBLIC_ enum MAPISTATUS ProcessNetworkProfile (struct mapi_session *session, const char *username, mapi_profile_callback_t callback, const void *private_data)
_PUBLIC_ enum MAPISTATUS RenameProfile (const char *old_profile, const char *profile)
_PUBLIC_ enum MAPISTATUS SetDefaultProfile (const char *profname)
_PUBLIC_ enum MAPISTATUS ShutDown (struct mapi_profile *profile)

Detailed Description

MAPI Profiles interface.


Function Documentation

_PUBLIC_ enum MAPISTATUS ChangeProfilePassword ( const char *  profile,
const char *  old_password,
const char *  password 
)

Change the profile password of an existing MAPI profile

Parameters:
profile the name of the profile to have its password changed
old_password the old password
password the new password
Returns:
MAPI_E_SUCCESS on success, otherwise MAPI error.
Note:
Developers may also call GetLastError() to retrieve the last MAPI error code. Possible MAPI error codes are:
  • MAPI_E_INVALID_PARAMETER: One of the following argument was not set: profile, old_password, password
  • MAPI_E_NOT_FOUND: The profile was not found in the database
See also:
CreateProfile, GetProfileTable, GetProfileAttr, ProcessNetworkProfile, GetLastError

References mapi_profile_modify_string_attr().

_PUBLIC_ enum MAPISTATUS CreateProfile ( const char *  profile,
const char *  username,
const char *  password,
uint32_t  flag 
)

Create a profile in the MAPI profile database

This function creates a profile named profile in the MAPI profile database and sets the specified username in that profile.

This function may also set the password. If the flags include OC_PROFILE_NOPASSWORD then the password will not be set. Otherwise, the specified password argument will also be saved to the profile.

Parameters:
profile the name of the profile
username the username of the profile
password the password for the profile (if used)
flag the union of the flags.
Returns:
MAPI_E_SUCCESS on success, otherwise MAPI error.
Note:
Developers may also call GetLastError() to retrieve the last MAPI error code. Possible MAPI error codes are:
  • MAPI_E_NOT_INITIALIZED: MAPI subsystem has not been initialized. The MAPI subsystem must be initialized (using MAPIInitialize) prior to creating a profile.
  • MAPI_E_NOT_ENOUGH_RESOURCES: MAPI subsystem failed to allocate the necessary resources to operate properly
  • MAPI_E_NO_SUPPORT: An error was encountered while setting the MAPI profile attributes in the database.
profile information (including the password, if saved to the profile) is stored unencrypted.
See also:
DeleteProfile, SetDefaultProfile, GetDefaultProfile, ChangeProfilePassword, GetProfileTable, ProcessNetworkProfile, GetLastError

References mapi_profile_add_string_attr().

_PUBLIC_ enum MAPISTATUS CreateProfileStore ( const char *  profiledb,
const char *  ldif_path 
)

Create a profile database

This function creates a new profile database, including doing an initial setup.

Parameters:
profiledb the absolute path to the profile database intended to be created
ldif_path the absolute path to the LDIF information to use for initial setup.
Returns:
MAPI_E_SUCCESS on success, otherwise MAPI error.
Note:
Developers may also call GetLastError() to retrieve the last MAPI error code. Possible MAPI error codes are:
  • MAPI_E_CALL_FAILED: profiledb or ldif_path is not set
  • MAPI_E_NOT_ENOUGH_RESOURCES: ldb subsystem initialization failed
  • MAPI_E_NO_ACCESS: connection or ldif add failed
See also:
GetLastError, mapi_profile_get_ldif_path
_PUBLIC_ enum MAPISTATUS DeleteProfile ( const char *  profile  ) 

Delete a profile from the MAPI profile database

Parameters:
profile the name of the profile to delete
Returns:
MAPI_E_SUCCESS on success, otherwise MAPI error.
Note:
Developers may also call GetLastError() to retrieve the last MAPI error code. Possible MAPI error codes are:
  • MAPI_E_NOT_INITIALIZED: MAPI subsystem has not been initialized. The MAPI subsystem must be initialized (using MAPIInitialize) prior to creating a profile.
  • MAPI_E_NOT_FOUND: The profile was not found in the database.
See also:
CreateProfile, ChangeProfilePassword, GetProfileTable, GetProfileAttr, ProcessNetworkProfile, GetLastError
_PUBLIC_ enum MAPISTATUS FindProfileAttr ( struct mapi_profile *  profile,
const char *  attribute,
const char *  value 
)

Search the value of an attribute within a given profile

_PUBLIC_ enum MAPISTATUS GetDefaultProfile ( char **  profname  ) 

Get the default profile from the database

Parameters:
profname the result of the function (name of the default profile)
Returns:
MAPI_E_SUCCESS on success, otherwise MAPI error.
Note:
Developers may also call GetLastError() to retrieve the last MAPI error code. Possible MAPI error codes are:
  • MAPI_E_NOT_INITIALIZED: MAPI subsystem has not been initialized
  • MAPI_E_NOT_FOUND: The profile was not found in the database
On success GetDefaultProfile profname string is allocated. It is up to the developer to free it when not needed anymore.
See also:
SetDefaultProfile, GetProfileTable, GetLastError
Examples:
fetchappointment.c, fetchmail.c, and mapi_sample1.c.

References GetProfileTable().

_PUBLIC_ enum MAPISTATUS GetProfileAttr ( struct mapi_profile *  profile,
const char *  attribute,
unsigned int *  count,
char ***  value 
)

Retrieve attribute values from a profile

This function retrieves all the attribute values from the given profile. The number of results is stored in count and values are stored in an allocated string array in the value parameter that needs to be free'd using MAPIFreeBuffer().

Parameters:
profile the name of the profile to retrieve attributes from
attribute the attribute(s) to search for
count the number of results
value the resulting values
Returns:
MAPI_E_SUCCESS on success, otherwise MAPI error.
Note:
Developers may also call GetLastError() to retrieve the last MAPI error code. Possible MAPI error codes are:
  • MAPI_E_NOT_INITIALIZED: MAPI subsystem has not been initialized
  • MAPI_E_INVALID_PARAMETER: Either profile or attribute was not set properly
  • MAPI_E_NOT_FOUND: The profile was not found in the database
See also:
SetDefaultProfile, GetDefaultProfile, MAPIFreeBuffer, GetProfileTable, GetLastError
_PUBLIC_ enum MAPISTATUS GetProfileTable ( struct SRowSet *  proftable  ) 

Retrieve the profile table

This function retrieves the profile table. Two fields are returned:

  • PR_DISPLAY_NAME: The profile name stored as a UTF8 string
  • PR_DEFAULT_PROFILE: Whether the profile is the default one(1) or not(0), stored as an integer
Parameters:
proftable the result of the call
Returns:
MAPI_E_SUCCESS on success, otherwise MAPI error.
Note:
Developers may also call GetLastError() to retrieve the last MAPI error code. Possible MAPI error codes are:
  • MAPI_E_NOT_INITIALIZED: MAPI subsystem has not been initialized
  • MAPI_E_NOT_FOUND: The profile was not found in the database
See also:
SetDefaultProfile, GetLastError

Referenced by GetDefaultProfile(), and RenameProfile().

_PUBLIC_ enum MAPISTATUS LoadProfile ( struct mapi_profile *  profile  ) 

Load a MAPI Profile and sets its credentials

This function loads a named MAPI profile and sets the MAPI session credentials.

Returns:
MAPI_E_SUCCESS on success, otherwise MAPI error.
Note:
Developers may also call GetLastError() to retrieve the last MAPI error code. Possible MAPI error codes are:
  • MAPI_E_NOT_INITIALIZED: MAPI subsystem has not been initialized
  • MAPI_E_INVALID_PARAMETER: The profile parameter is not initialized
  • MAPI_E_NOT_ENOUGH_RESOURCES: MAPI subsystem failed to allocate the necessary resources to perform the operation
See also:
OpenProfile, GetLastError

Referenced by MapiLogonProvider().

_PUBLIC_ enum MAPISTATUS mapi_profile_add_string_attr ( const char *  profile,
const char *  attr,
const char *  value 
)

Add an attribute to the profile

Referenced by CreateProfile(), and ProcessNetworkProfile().

_PUBLIC_ enum MAPISTATUS mapi_profile_delete_string_attr ( const char *  profname,
const char *  attr,
const char *  value 
)

Delete an attribute

_PUBLIC_ const char* mapi_profile_get_ldif_path ( void   ) 

Get default ldif_path

This function returns the path for the default LDIF files.

See also:
CreateProfileStore
_PUBLIC_ enum MAPISTATUS mapi_profile_modify_string_attr ( const char *  profname,
const char *  attr,
const char *  value 
)

Modify an attribute

Referenced by ChangeProfilePassword(), and SetDefaultProfile().

_PUBLIC_ enum MAPISTATUS OpenProfile ( struct mapi_profile *  profile,
const char *  profname,
const char *  password 
)

Load a profile from the database

This function opens a named profile from the database, and fills the mapi_profile structure with common profile information.

Parameters:
profile the resulting profile
profname the name of the profile to open
password the password to use with the profile
Returns:
MAPI_E_SUCCESS on success, otherwise MAPI error.
Note:
Developers may also call GetLastError() to retrieve the last MAPI error code. Possible MAPI error codes are:
  • MAPI_E_NOT_ENOUGH_RESOURCES: ldb subsystem initialization failed
  • MAPI_E_NOT_FOUND: the profile was not found in the profile database
  • MAPI_E_COLLISION: profname matched more than one entry
See also:
MAPIInitialize, GetLastError

Referenced by MapiLogonProvider().

_PUBLIC_ enum MAPISTATUS ProcessNetworkProfile ( struct mapi_session *  session,
const char *  username,
mapi_profile_callback_t  callback,
const void *  private_data 
)

Process a full and automated MAPI profile creation

This function process a full and automated MAPI profile creation using the username pattern passed as a parameter. The functions takes a callback parameter which will be called when the username checked matches several usernames. Private data needed by the callback can be supplied using the private_data pointer.

   typedef int (*mapi_callback_t) callback(struct SRowSet *, void *private_data);

The callback returns the SRow element index within the SRowSet structure. If the user cancels the operation the callback return value should be SRowSet->cRows or more.

Parameters:
session the session context
username the username for the network profile
callback function pointer callback function
private_data context data that will be provided to the callback
Returns:
MAPI_E_SUCCESS on success, otherwise MAPI error.
Note:
Developers may also call GetLastError() to retrieve the last MAPI error code. Possible MAPI error codes are:
  • MAPI_E_NOT_INITIALIZED: MAPI subsystem has not been initialized. The MAPI subsystem must be initialized (using MAPIInitialize) prior to creating a profile.
  • MAPI_E_END_OF_SESSION: The NSPI session has not been initialized
  • MAPI_E_CANCEL_USER: The user has aborted the operation
  • MAPI_E_INVALID_PARAMETER: The profile parameter was not set properly.
  • MAPI_E_NOT_FOUND: One of the mandatory field was not found during the profile creation process.
See also:
OpenProfileStore, MAPILogonProvider, GetLastError

References mapi_profile_add_string_attr(), MAPIFreeBuffer(), nspi_DNToMId(), nspi_GetMatches(), nspi_GetProps(), nspi_GetSpecialTable(), and nspi_QueryRows().

_PUBLIC_ enum MAPISTATUS RenameProfile ( const char *  old_profile,
const char *  profile 
)

Rename a profile

Parameters:
old_profile old profile name
profile new profile name
Returns:
MAPI_E_SUCCESS on success, otherwise MAPI error.

References GetProfileTable().

_PUBLIC_ enum MAPISTATUS SetDefaultProfile ( const char *  profname  ) 

Set a default profile for the database

Parameters:
profname the name of the profile to make the default profile
Returns:
MAPI_E_SUCCESS on success, otherwise MAPI error.
Note:
Developers may also call GetLastError() to retrieve the last MAPI error code. Possible MAPI error codes are:
  • MAPI_E_NOT_INITIALIZED: MAPI subsystem has not been initialized
  • MAPI_E_INVALID_PARAMETER: The profile parameter was not set properly.
  • MAPI_E_NOT_FOUND: The profile was not found in the database
See also:
GetDefaultProfile, GetProfileTable, GetLastError

References mapi_profile_modify_string_attr().

_PUBLIC_ enum MAPISTATUS ShutDown ( struct mapi_profile *  profile  ) 

Release a profile

This function releases the credentials associated with the profile.

Parameters:
profile the profile to release.
Returns:
MAPI_E_SUCCESS on success, otherwise MAPI error.
Note:
Developers may also call GetLastError() to retrieve the last MAPI error code. Possible MAPI error codes are:
  • MAPI_E_INVALID_PARAMETER: The profile parameter was not set or not valid

Creative Commons License
Creative Commons Attribution icon Creative Commons Share Alike icon
This content is licensed under the Creative Commons
Attribution ShareAlike License v. 3.0:
http://creativecommons.org/licenses/by-sa/3.0/