MAPIClientLibraries 2.0 API Documentation

- Main Page
- Related Pages
- Data Structures
- Files
- Examples

- File List
- Globals

Functions
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)
_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_ctx | pointer to the MAPI context
  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 CopyProfile | ( | struct mapi_context * | mapi_ctx,
|  | const char * | profile_src,
|  | const char * | profile_dst
| ) |  |

Copy a profile

Parameters

  mapi_ctx | pointer to the MAPI context
  profile_src | the source profile to copy from
  profile_dst | the destination profile to copy to

Returns
  MAPI_E_SUCCESS on success, otherwise MAPI error.

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_ctx | pointer to the MAPI context
  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 | ( | struct mapi_context * | mapi_ctx,
|  | const char * | profile
| ) |  |

Delete a profile from the MAPI profile database

Parameters

  mapi_ctx | pointer to the MAPI context
  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 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_ctx | pointer to the MAPI context
  profile_src | the source profile to duplicate from
  profile_dst | the destination profile to duplicate to
  username | the username to replace within the destination profile

Returns
  MAPI_E_SUCCESS on success, otherwise MAPI error

References CopyProfile(), GetLastError(), GetProfileAttr(), mapi_profile_delete_string_attr(), mapi_profile_modify_string_attr(), MAPIFreeBuffer(), MapiLogonProvider(), nspi_GetMatches(), nspi_GetSpecialTable(), OpenProfile(), 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

  profile | pointer to the MAPI profile
  attribute | pointer to the attribute name
  value | pointer to the attribute value

Returns
  MAPI_E_SUCCESS on success, otherwise MAPI error

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

Get the default profile from the database

Parameters

  mapi_ctx | pointer to the MAPI context
  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

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_ctx | pointer to the MAPI context
  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_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_ctx | pointer to the MAPI context
  profile | pointer 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

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_ctx | pointer to the MAPI context
  profile | pointer to the profile name
  attr | the name of the atribute
  value | the value of the attribute

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_ctx | pointer to the MAPI context
  profname | the name of the profile
  attr | the name of the attribute
  value | the value of the attribute

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_ctx | pointer to the MAPI context
  profname | the name of the profile
  attr | the name of the attribute
  value | the value of the attribute

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_ctx | pointer to the MAPI context
  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
  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

Referenced by DuplicateProfile(), and 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(), nspi_QueryRows(), and set_SPropTagArray().

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

Rename a profile

Parameters

  mapi_ctx | pointer to the MAPI context
  old_profile | old profile name
  profile | new profile name

Returns
  MAPI_E_SUCCESS on success, otherwise MAPI error.

References GetProfileTable().

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

Set a default profile for the database

Parameters

  mapi_ctx | pointer to the MAPI context
  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

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