IMAPIProp::SetProps

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

Quick Info

See IMAPIProp : IUnknownHP08HX.

HRESULT SetProps(

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 SPropValue81C9._8 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.R6Y64 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.

Remarks

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

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.R6Y64 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::GetLastError6IMPBE 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::OpenPropertyLFSSYS with IID_IStream as the interface identifier if SetProps returns this error value.

Call the MAPIFreeBuffer16U06F function to free the SPropProblemArray structure.

See Also