Undocumented MAPI

It has come to our attention that a handful of functions exposed in the MAPI Stub Library don’t have documentation in the Outlook 2010 MAPI Reference. We’re working on correcting that, but in the meantime, here are the functions and some basic documentation of what they do.

Update: All of these now have articles in the MSDN:

• LpValFindProp
• GetTnefStreamCodepage
• FtAdcFt
• HrAddColumns
• IsBadBoundedStringPtr

LpValFindProp

Searches for a specified property in a property set.

 LPSPropValue LpValFindProp(

  ULONG ulPropTag,

  ULONG cValues,

  LPSPropValue lpPropArray

);

Parameters

ulPropTag

[in] Property tag for the property to search for in the property set indicated by the lpPropArray parameter.

cValues

[in] Count of properties in the property set indicated by the lpPropArray parameter.

lpPropArray

[in] Array of SPropValue structures that define the properties to be searched.

Return Value

LpValFindProp returns an SPropValue structure defining the property that matches the input propert tag, and NULL if there is no match.

Remarks

LpValFindProp is functionally identical to PpropFindProp.

GetTnefStreamCodepage

Determines the code page for a TNEF stream.

 HRESULT GetTnefStreamCodepage ( 

  LPSTREAM lpStream, 

  ULONG FAR * lpulCodepage, 

  ULONG FAR * lpulSubCodepage); 

Parameters

• lpStream
  [in] Pointer to a storage stream object OLE IStream interface providing a source for a TNEF stream message.
• lpulCodepage
  [out] Pointer to the code page of the stream
• lpulSubCodepage
  [out] Pointer to the sub code page of the stream.

Return Value

• S_OK
  The call succeeded and has returned the expected value or values.
• MAPI_E_NOT_ENOUGH_DISK
  There was an error reading an attribute in the TNEF stream.
• MAPI_E_CORRUPT_DATA
  Either the stream was not a TNEF stream or there was an error reading the attOemCodepage attribute.

Remarks

GetTnefStreamCodepage reads the attOemCodepage attribute of the TNEF stream to determine the code page and sub code page. If attOemCodepage is not found, will return a code page of 437 and a subcodepage of 0.

FtAdcFt

Adds one unsigned 64-bit integer to another, optionally using a carry flag.

 FILETIME FtAdcFt( 

  FILETIME ft1, 

  FILETIME ft2, 

  WORD FAR *pwCarry); 

Parameters

• ft1
  [in] A FILETIME structure that contains the first unsigned 64-bit integer to be added.
• ft2
  [in] A FILETIME structure that contains the second unsigned 64-bit integer to be added.
• pwCarry
  [in, out, optional] On input, a pointer to the incoming carry flag. On output, a pointer to the carry result for the addition. This parameter can be NULL if the carry result is not required.

Return Value

The FtAdcFt function returns a FILETIME structure that contains the sum of the two integers. The two input parameters remain unchanged. If pwCarry is non-NULL, it will contain the carry result for the sum, either 0 or 1.

Remarks

FtAdcFt is functionally identical to FtAddFt when pwCarry is NULL. If pwCarry is non-NULL and points to 0, FtAdcFt will return the same FILETIME value which FtAddFt would return.

HrAddColumns

Adds or moves columns to the beginning of an existing table.

 HRESULT HrAddColumns( 

  LPMAPITABLE lptbl, 

  LPSPropTagArray lpproptagColumnsNew, 

  LPALLOCATEBUFFER lpAllocateBuffer, 

  LPFREEBUFFER lpFreeBuffer); 

Parameters

• lptbl
  [in] Pointer to the MAPI table affected.
• lpproptagColumnsNew
  [in] Pointer to an SPropTagArray structure that contains an array of property tags for the properties to be added or moved to the beginning of the table.
• lpAllocateBuffer
  [in] Pointer to the MAPIAllocateBuffer function, to be used to allocate memory.
• lpFreeBuffer
  [in] Pointer to the MAPIFreeBuffer function, to be used to free memory.

Return Value

• S_OK
  The call succeeded and the specified columns were moved or added.

Remarks

HrAddColumns is functionally equivalent to HrAddColumnsEx with lpfnFilterColumns set to NULL.

IsBadBoundedStringPtr

Verifies that the calling process has read access to the specified range of memory.

 BOOL IsBadBoundedStringPtr( 

  const void FAR* lpsz, 

  UINT cchMax); 

Parameters

• lpsz
  [in] A pointer to a null-terminated ASCII string.
• cchMax
  [in] The maximum size of the string, in CHARs. The function checks for read access in all characters up to the string's terminating null character or up to the number of characters specified by this parameter, whichever is smaller. If this parameter is zero, the return value is zero.

Return Value

If the calling process has read access to all characters up to the string's terminating null character or up to the number of characters specified by cchMax, the return value is zero.

If the calling process does not have read access to all characters up to the string's terminating null character or up to the number of characters specified by cchMax, the return value is nonzero.

Remarks

IsBadBoundedStringPtr is functionally equivalent to IsBadStringPtr.

Enjoy!