IMAPIProp::SetProps

The IMAPIProp::SetProps method updates one or more properties.

Quick Info

HRESULT SetProps(
  ULONG cValues,                         
  LPSPropValue lpPropArray,              
  LPSPropProblemArray FAR * lppProblems  
);

Parameters

cValues: [in] Count of property values pointed to by the lpPropArray parameter. The cValues parameter must not be zero.
lpPropArray: [in] Pointer to an array of SPropValue structures holding property values to be updated.
lppProblems: [in, out] On input, can be NULL, indicating no need for error information, or a pointer to a pointer to an SPropProblemArray structure. If lppProblems is a valid pointer on input, SetProps returns detailed information about errors in updating one or more properties.

Return Values

S_OK: The properties were successfully updated.

The following values can be returned in the SPropProblemArray structure, but not as return values for SetProps:

MAPI_E_BAD_CHARWIDTH: Either the MAPI_UNICODE flag was set and the implementation does not support Unicode, or MAPI_UNICODE was not set and the implementation only supports Unicode.
MAPI_E_COMPUTED: The property cannot be updated because it is read-only, computed by the service provider responsible for the object.
MAPI_E_INVALID_TYPE: The property type is invalid.
MAPI_E_NO_ACCESS: An attempt was made to modify a read-only object or to access an object for which the user has insufficient permissions.
MAPI_E_NOT_ENOUGH_MEMORY: The property cannot be updated because it is larger than the RPC buffer size.
MAPI_E_UNEXPECTED_TYPE: The property type is not the type expected by the calling implementation.

Notes to Implementers

Ignore the PR_NULL property tag and all properties with a type of PT_ERROR; make no changes and report no problems in the SPropProblemArray structure.

Return MAPI_E_INVALID_PARAMETER if a property of type PT_OBJECT is included in the property value array. Also return this error if a multivalued property is included in the array and its cValues member is set to zero.

If the call succeeds overall but there are problems with setting some of the properties, return S_OK and place information about the problems in the appropriate entry of the SPropProblemArray structure pointed to by the lppProblems parameter.

Notes to Callers

Depending on the service provider, you might also be able to change the property type by passing a property tag containing a different type than was previously used with a given property identifier.

If you include a property tag for a property that is unsupported by the object and the implementation of SetProps allows the creation of new properties, the property is added to the object. Any previous value stored with the property identifier used for the new property is discarded.

Note that the S_OK return value does not guarantee that all of the properties were successfully updated. Some providers cache SetProps calls until they receive a call that requires provider intervention, such as IMAPIProp::SaveChanges or IMAPIProp::GetProps. Therefore, it is possible to receive error values relating to the SetProps call with the later calls.

If SetProps returns S_OK, check the SPropProblemArray structure pointed to by lppProblems for problems updating individual properties. If SetProps returns an error, do not check the property problem array. Instead, call the object's IMAPIProp::GetLastError method.

When updating large properties, SetProps can fail and return MAPI_E_NOT_ENOUGH_MEMORY. There is no maximum size for properties, and different objects can have different limits. If you deal with potentially large properties be prepared to call IMAPIProp::OpenProperty with IID_IStream as the interface identifier if SetProps returns this error value.

Call the MAPIFreeBuffer function to free the SPropProblemArray structure.