IProfAdmin.c File Reference

MAPI Profiles interface. More...

#include "libmapi/libmapi.h"
#include "libmapi/libmapi_private.h"

Functions

_PUBLIC_ enum MAPISTATUS ChangeProfilePassword (struct mapi_context *mapi_ctx, const char *profile, const char *old_password, const char *password)
 
_PUBLIC_ enum MAPISTATUS CopyProfile (struct mapi_context *mapi_ctx, const char *profile_src, const char *profile_dst)
 
_PUBLIC_ enum MAPISTATUS CreateProfile (struct mapi_context *mapi_ctx, 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 (struct mapi_context *mapi_ctx, const char *profile)
 
_PUBLIC_ enum MAPISTATUS DuplicateProfile (struct mapi_context *mapi_ctx, const char *profile_src, const char *profile_dst, const char *username)
 
_PUBLIC_ enum MAPISTATUS FindProfileAttr (struct mapi_profile *profile, const char *attribute, const char *value)
 
_PUBLIC_ enum MAPISTATUS GetDefaultProfile (struct mapi_context *mapi_ctx, char **profname)
 
_PUBLIC_ enum MAPISTATUS GetProfileAttr (struct mapi_profile *profile, const char *attribute, unsigned int *count, char ***value)
 
_PUBLIC_ enum MAPISTATUS GetProfileTable (struct mapi_context *mapi_ctx, struct SRowSet *proftable)
 
_PUBLIC_ enum MAPISTATUS LoadProfile (struct mapi_context *mapi_ctx, struct mapi_profile *profile)
 
_PUBLIC_ enum MAPISTATUS mapi_profile_add_string_attr (struct mapi_context *mapi_ctx, const char *profile, const char *attr, const char *value)
 
_PUBLIC_ enum MAPISTATUS mapi_profile_delete_string_attr (struct mapi_context *mapi_ctx, 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 (struct mapi_context *mapi_ctx, const char *profname, const char *attr, const char *value)
 
_PUBLIC_ enum MAPISTATUS OpenProfile (struct mapi_context *mapi_ctx, struct mapi_profile *profile, const char *profname, const char *password)
 
enum MAPISTATUS OpenProfileStore (TALLOC_CTX *mem_ctx, struct ldb_context **ldb_ctx, const char *profiledb)
 
_PUBLIC_ enum MAPISTATUS ProcessNetworkProfile (struct mapi_session *session, const char *username, mapi_profile_callback_t callback, const void *private_data)
 
_PUBLIC_ enum MAPISTATUS RenameProfile (struct mapi_context *mapi_ctx, const char *old_profile, const char *profile)
 
_PUBLIC_ enum MAPISTATUS SetDefaultProfile (struct mapi_context *mapi_ctx, const char *profname)
 
_PUBLIC_ enum MAPISTATUS ShutDown (struct mapi_profile *profile)
 

Detailed Description

MAPI Profiles interface.

Function Documentation

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

Change the profile password of an existing MAPI profile

Parameters
mapi_ctxpointer to the MAPI context
profilethe name of the profile to have its password changed
old_passwordthe old password
passwordthe 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(), mapi_context::mem_ctx, and OPENCHANGE_RETVAL_IF.

_PUBLIC_ enum MAPISTATUS CopyProfile ( struct mapi_context mapi_ctx,
const char *  profile_src,
const char *  profile_dst 
)

Copy a profile

Parameters
mapi_ctxpointer to the MAPI context
profile_srcthe source profile to copy from
profile_dstthe destination profile to copy to
Returns
MAPI_E_SUCCESS on success, otherwise MAPI error.

References mapi_context::ldb_ctx, mapi_context::mem_ctx, and OPENCHANGE_RETVAL_IF.

Referenced by DuplicateProfile().

_PUBLIC_ enum MAPISTATUS CreateProfile ( struct mapi_context mapi_ctx,
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
mapi_ctxpointer to the MAPI context
profilethe name of the profile
usernamethe username of the profile
passwordthe password for the profile (if used)
flagthe 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_context::ldb_ctx, mapi_profile_add_string_attr(), mapi_context::mem_ctx, OC_PROFILE_NOPASSWORD, and OPENCHANGE_RETVAL_IF.

_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
profiledbthe absolute path to the profile database intended to be created
ldif_paththe 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

References OPENCHANGE_RETVAL_ERR, and OPENCHANGE_RETVAL_IF.

_PUBLIC_ enum MAPISTATUS DeleteProfile ( struct mapi_context mapi_ctx,
const char *  profile 
)

Delete a profile from the MAPI profile database

Parameters
mapi_ctxpointer to the MAPI context
profilethe 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

References mapi_context::ldb_ctx, mapi_context::mem_ctx, and OPENCHANGE_RETVAL_IF.

_PUBLIC_ enum MAPISTATUS DuplicateProfile ( struct mapi_context mapi_ctx,
const char *  profile_src,
const char *  profile_dst,
const char *  username 
)

Duplicate an existing profile.

The username specified in parameter is used to customize the new profile. This function should only be used in environments where users are within the same administrative group, storage group, server etc. Otherwise this will create an invalid profile and may cause unpredictable results.

Parameters
mapi_ctxpointer to the MAPI context
profile_srcthe source profile to duplicate from
profile_dstthe destination profile to duplicate to
usernamethe username to replace within the destination profile
Returns
MAPI_E_SUCCESS on success, otherwise MAPI error

References CopyProfile(), mapi_provider::ctx, GetLastError(), GetProfileAttr(), mapi_session::mapi_ctx, mapi_errstr(), mapi_profile_delete_string_attr(), mapi_profile_modify_string_attr(), MAPIFreeBuffer(), MapiLogonProvider(), mapi_context::mem_ctx, mapi_session::nspi, nspi_GetMatches(), nspi_GetSpecialTable(), OPENCHANGE_RETVAL_IF, OpenProfile(), PR_ANR_UNICODE, PR_EMAIL_ADDRESS, PROVIDER_ID_NSPI, RES_PROPERTY, mapi_context::session, and set_SPropTagArray().

_PUBLIC_ enum MAPISTATUS FindProfileAttr ( struct mapi_profile profile,
const char *  attribute,
const char *  value 
)

Search the value of an attribute within a given profile

Parameters
profilepointer to the MAPI profile
attributepointer to the attribute name
valuepointer to the attribute value
Returns
MAPI_E_SUCCESS on success, otherwise MAPI error

References mapi_context::ldb_ctx, mapi_profile::mapi_ctx, OPENCHANGE_RETVAL_IF, and mapi_profile::profname.

_PUBLIC_ enum MAPISTATUS GetDefaultProfile ( struct mapi_context mapi_ctx,
char **  profname 
)

Get the default profile from the database

Parameters
mapi_ctxpointer to the MAPI context
profnamethe 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 get_SPropValue_SRow(), GetProfileTable(), mapi_context::mem_ctx, OPENCHANGE_RETVAL_ERR, OPENCHANGE_RETVAL_IF, PR_DEFAULT_PROFILE, and PR_DISPLAY_NAME.

_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
profilethe name of the profile to retrieve attributes from
attributethe attribute(s) to search for
countthe number of results
valuethe 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

References mapi_context::ldb_ctx, mapi_profile::mapi_ctx, OPENCHANGE_RETVAL_IF, and mapi_profile::profname.

Referenced by DuplicateProfile().

_PUBLIC_ enum MAPISTATUS GetProfileTable ( struct mapi_context mapi_ctx,
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
mapi_ctxpointer to the MAPI context
proftablethe 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

References mapi_context::ldb_ctx, mapi_context::mem_ctx, OPENCHANGE_RETVAL_IF, PR_DEFAULT_PROFILE, and PR_DISPLAY_NAME.

Referenced by GetDefaultProfile(), and RenameProfile().

_PUBLIC_ enum MAPISTATUS LoadProfile ( struct mapi_context mapi_ctx,
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.

Parameters
mapi_ctxpointer to the MAPI context
profilepointer to the MAPI 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 is not initialized
  • MAPI_E_NOT_ENOUGH_RESOURCES: MAPI subsystem failed to allocate the necessary resources to perform the operation
See Also
OpenProfile, GetLastError

References mapi_profile::credentials, mapi_profile::domain, mapi_profile::kerberos, mapi_context::lp_ctx, OPENCHANGE_RETVAL_IF, mapi_profile::password, mapi_profile::realm, mapi_context::session, mapi_profile::username, and mapi_profile::workstation.

Referenced by MapiLogonProvider().

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

Add an attribute to the profile

Parameters
mapi_ctxpointer to the MAPI context
profilepointer to the profile name
attrthe name of the atribute
valuethe value of the attribute

References mapi_context::ldb_ctx, mapi_context::mem_ctx, and OPENCHANGE_RETVAL_IF.

Referenced by CreateProfile(), and ProcessNetworkProfile().

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

Delete an attribute

Parameters
mapi_ctxpointer to the MAPI context
profnamethe name of the profile
attrthe name of the attribute
valuethe value of the attribute

References mapi_context::ldb_ctx, mapi_context::mem_ctx, and OPENCHANGE_RETVAL_IF.

Referenced by DuplicateProfile().

_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 ( struct mapi_context mapi_ctx,
const char *  profname,
const char *  attr,
const char *  value 
)

Modify an attribute

Parameters
mapi_ctxpointer to the MAPI context
profnamethe name of the profile
attrthe name of the attribute
valuethe value of the attribute

References mapi_context::ldb_ctx, mapi_context::mem_ctx, and OPENCHANGE_RETVAL_IF.

Referenced by ChangeProfilePassword(), DuplicateProfile(), and SetDefaultProfile().

_PUBLIC_ enum MAPISTATUS OpenProfile ( struct mapi_context mapi_ctx,
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
mapi_ctxpointer to the MAPI context
profilethe resulting profile
profnamethe name of the profile to open
passwordthe password to use with the profile
Returns
MAPI_E_SUCCESS on success, otherwise MAPI error.
Note
profile must be talloced because it used as talloc subcontext for data members. 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

References mapi_context::ldb_ctx, mapi_profile::mapi_ctx, and OPENCHANGE_RETVAL_IF.

Referenced by DuplicateProfile(), and MapiLogonProvider().

enum MAPISTATUS OpenProfileStore ( TALLOC_CTX *  mem_ctx,
struct ldb_context **  ldb_ctx,
const char *  profiledb 
)

Referenced by MAPIInitialize().

_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
sessionthe session context
usernamethe username for the network profile
callbackfunction pointer callback function
private_datacontext 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 nspi_context::cred, mapi_provider::ctx, get_PropertyValue_PropertyRowSet(), mapi_session::mapi_ctx, mapi_profile_add_string_attr(), MAPIFreeBuffer(), mapi_session::nspi, nspi_DNToMId(), nspi_GetMatches(), nspi_GetProps(), nspi_GetSpecialTable(), nspi_QueryRows(), OPENCHANGE_RETVAL_IF, nspi_context::org, ORG, nspi_context::org_unit, ORG_UNIT, PR_ACCOUNT, PR_ADDRTYPE, PR_ANR_UNICODE, PR_ATTACH_NUM, PR_COMPANY_NAME, PR_DISPLAY_NAME, PR_DISPLAY_TYPE, PR_EMAIL_ADDRESS, PR_EMS_AB_HOME_MDB, PR_EMS_AB_NETWORK_ADDRESS, PR_EMS_AB_PROXY_ADDRESSES, PR_ENTRYID, PR_INSTANCE_KEY, PR_OBJECT_TYPE, PR_OFFICE_LOCATION, PR_OFFICE_TELEPHONE_NUMBER, PR_PROFILE_HOME_SERVER_ADDRS, PR_TITLE, mapi_session::profile, mapi_profile::profname, nspi_context::pStat, RES_PROPERTY, SERVER_DN, nspi_context::servername, set_SPropTagArray(), x500_get_dn_element(), and x500_get_servername().

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

Rename a profile

Parameters
mapi_ctxpointer to the MAPI context
old_profileold profile name
profilenew profile name
Returns
MAPI_E_SUCCESS on success, otherwise MAPI error.

References get_SPropValue_SRow(), GetProfileTable(), mapi_context::ldb_ctx, nspi_context::mem_ctx, mapi_context::mem_ctx, OPENCHANGE_RETVAL_IF, and PR_DISPLAY_NAME.

_PUBLIC_ enum MAPISTATUS SetDefaultProfile ( struct mapi_context mapi_ctx,
const char *  profname 
)

Set a default profile for the database

Parameters
mapi_ctxpointer to the MAPI context
profnamethe 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_context::ldb_ctx, mapi_profile_modify_string_attr(), mapi_context::mem_ctx, and OPENCHANGE_RETVAL_IF.

_PUBLIC_ enum MAPISTATUS ShutDown ( struct mapi_profile profile)

Release a profile

This function releases the credentials associated with the profile.

Parameters
profilethe 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

References mapi_profile::credentials, and OPENCHANGE_RETVAL_IF.


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/