libmapi/IStream.c File Reference

Functions for operating on Streams on MAPI objects. More...

#include <libmapi/libmapi.h>

Functions

_PUBLIC_ enum MAPISTATUS CloneStream (mapi_object_t *obj_src, mapi_object_t *obj_dst)
_PUBLIC_ enum MAPISTATUS CommitStream (mapi_object_t *obj_stream)
_PUBLIC_ enum MAPISTATUS CopyToStream (mapi_object_t *obj_src, mapi_object_t *obj_dst, uint64_t ByteCount, uint64_t *ReadByteCount, uint64_t *WrittenByteCount)
_PUBLIC_ enum MAPISTATUS GetStreamSize (mapi_object_t *obj_stream, uint32_t *StreamSize)
_PUBLIC_ enum MAPISTATUS LockRegionStream (mapi_object_t *obj_stream, uint64_t RegionOffset, uint64_t RegionSize, uint32_t LockFlags)
_PUBLIC_ enum MAPISTATUS OpenStream (mapi_object_t *obj_related, enum MAPITAGS PropertyTag, enum OpenStream_OpenModeFlags OpenModeFlags, mapi_object_t *obj_stream)
_PUBLIC_ enum MAPISTATUS ReadStream (mapi_object_t *obj_stream, unsigned char *buf_data, uint16_t ByteCount, uint16_t *ByteRead)
_PUBLIC_ enum MAPISTATUS SeekStream (mapi_object_t *obj_stream, uint8_t Origin, uint64_t Offset, uint64_t *NewPosition)
_PUBLIC_ enum MAPISTATUS SetStreamSize (mapi_object_t *obj_stream, uint64_t SizeStream)
_PUBLIC_ enum MAPISTATUS UnlockRegionStream (mapi_object_t *obj_stream, uint64_t RegionOffset, uint64_t RegionSize, uint32_t LockFlags)
_PUBLIC_ enum MAPISTATUS WriteAndCommitStream (mapi_object_t *obj_stream, DATA_BLOB *blob, uint16_t *WrittenSize)
_PUBLIC_ enum MAPISTATUS WriteStream (mapi_object_t *obj_stream, DATA_BLOB *blob, uint16_t *WrittenSize)

Detailed Description

Functions for operating on Streams on MAPI objects.


Function Documentation

_PUBLIC_ enum MAPISTATUS CloneStream ( mapi_object_t obj_src,
mapi_object_t obj_dst 
)

Clone a source stream to another stream

Parameters:
obj_src the source stream object
obj_dst the destination stream object
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: source or destination streams are not valid.
  • MAPI_E_CALL_FAILED: A network problem was encountered during the transaction
See also:
OpenStream

References mapi_provider::ctx, mapi_session::emsmdb, emsmdb_transaction(), global_mapi_ctx, mapi_object_get_handle(), mapi_object_get_logon_id(), mapi_object_get_session(), mapi_object_set_handle(), mapi_object_set_logon_id(), mapi_object_set_session(), and OPENCHANGE_RETVAL_IF.

_PUBLIC_ enum MAPISTATUS CommitStream ( mapi_object_t obj_stream  ) 

Commits stream operations

Parameters:
obj_stream the stream object to commit
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 the network stream or session context are not valid.
  • MAPI_E_CALL_FAILED: A network problem was encountered during the transaction
See also:
OpenStream, ReadStream, WriteStream

References mapi_provider::ctx, mapi_session::emsmdb, emsmdb_transaction(), global_mapi_ctx, mapi_object_get_handle(), mapi_object_get_logon_id(), mapi_object_get_session(), OPENCHANGE_CHECK_NOTIFICATION, and OPENCHANGE_RETVAL_IF.

_PUBLIC_ enum MAPISTATUS CopyToStream ( mapi_object_t obj_src,
mapi_object_t obj_dst,
uint64_t  ByteCount,
uint64_t *  ReadByteCount,
uint64_t *  WrittenByteCount 
)

Copy a number of bytes from a source stream to another stream

Parameters:
obj_src the source stream object
obj_dst the destination stream object
ByteCount the number of bytes to copy
ReadByteCount pointer on the number of bytes read from the source object
WrittenByteCount pointer on the number of bytes written to the destination object
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_BOOKMARK: the bookmark specified is invalid or beyond the last row requested.
  • MAPI_E_CALL_FAILED: A network problem was encountered during the transaction
See also:
OpenStream

References mapi_provider::ctx, mapi_session::emsmdb, emsmdb_transaction(), global_mapi_ctx, mapi_object_get_handle(), mapi_object_get_logon_id(), mapi_object_get_session(), OPENCHANGE_CHECK_NOTIFICATION, and OPENCHANGE_RETVAL_IF.

_PUBLIC_ enum MAPISTATUS GetStreamSize ( mapi_object_t obj_stream,
uint32_t *  StreamSize 
)

Gets the size of a stream

Parameters:
obj_stream the stream object we retrieve size from
StreamSize pointer on the stream size
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: obj_stream is not initialized, or there was a problem obtaining the session context
  • MAPI_E_CALL_FAILED: A network problem was encountered during the transaction
See also:
OpenStream, ReadStream

References mapi_provider::ctx, mapi_session::emsmdb, emsmdb_transaction(), global_mapi_ctx, mapi_object_get_handle(), mapi_object_get_logon_id(), mapi_object_get_session(), OPENCHANGE_CHECK_NOTIFICATION, and OPENCHANGE_RETVAL_IF.

_PUBLIC_ enum MAPISTATUS LockRegionStream ( mapi_object_t obj_stream,
uint64_t  RegionOffset,
uint64_t  RegionSize,
uint32_t  LockFlags 
)

Lock a range of bytes within the stream

Parameters:
obj_stream the stream object
RegionOffset starting point for the range
RegionSize length of the range
LockFlags type of locking to apply

Setting LockFlags to 0x00000001 will provide a write lock (i.e. one writer, any number of readers). Setting LockFlags to any other value will provide a read-write lock (one reader/writer, no other readers or writers).

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: obj_stream is not valid
  • MAPI_E_CALL_FAILED: A network problem was encountered during the transaction
See also:
UnlockRegionStream

References mapi_provider::ctx, mapi_session::emsmdb, emsmdb_transaction(), global_mapi_ctx, mapi_object_get_handle(), mapi_object_get_logon_id(), mapi_object_get_session(), and OPENCHANGE_RETVAL_IF.

_PUBLIC_ enum MAPISTATUS OpenStream ( mapi_object_t obj_related,
enum MAPITAGS  PropertyTag,
enum OpenStream_OpenModeFlags  OpenModeFlags,
mapi_object_t obj_stream 
)

Open a stream

This function opens a stream on the property prop set in obj_related with access flags set to access_flags and returns an object obj_stream.

Parameters:
obj_related the object to open.
PropertyTag the property name for the object to create a stream for.
OpenModeFlags sets the access mode for the stream and is one of the following values: 0x0: ReadOnly 0x1: ReadWrite 0x2: Create 0x3: BestAccess
obj_stream the resulting stream object.
Returns:
MAPI_E_SUCCESS on success, otherwise MAPI error. Possible MAPI error codes are:
  • MAPI_E_NOT_INITIALIZED: MAPI subsystem has not been initialized
  • MAPI_E_INVALID_PARAMETER: A problem occured obtaining the session context
  • MAPI_E_CALL_FAILED: A network problem was encountered during the transaction
Note:
Developers may also call GetLastError() to retrieve the last MAPI error code.
See also:
ReadStream, WriteStream, GetLastError

References mapi_provider::ctx, mapi_session::emsmdb, emsmdb_transaction(), global_mapi_ctx, mapi_object_get_handle(), mapi_object_get_logon_id(), mapi_object_get_session(), mapi_object_set_handle(), mapi_object_set_logon_id(), mapi_object_set_session(), OPENCHANGE_CHECK_NOTIFICATION, and OPENCHANGE_RETVAL_IF.

_PUBLIC_ enum MAPISTATUS ReadStream ( mapi_object_t obj_stream,
unsigned char *  buf_data,
uint16_t  ByteCount,
uint16_t *  ByteRead 
)

Read buffer from a stream

This function reads from an open data stream. It will read up to ByteCount bytes from the stream, and return the data in data_buf. ByteRead is set to the number of bytes actually read.

Parameters:
obj_stream the opened stream object
buf_data the buffer where data read from the stream will be stored
ByteCount the number of bytes requested to be read from the stream
ByteRead the number of bytes read from the stream
Returns:
MAPI_E_SUCCESS on success, otherwise MAPI error. Possible MAPI error codes are:
  • MAPI_E_NOT_INITIALIZED: MAPI subsystem has not been initialized
  • MAPI_E_INVALID_PARAMETER: A problem occured obtaining the session context
  • MAPI_E_CALL_FAILED: A network problem was encountered during the transaction
Note:
Developers may also call GetLastError() to retrieve the last MAPI error code.
The data size intended to be read from the stream shouldn't extend a maximum size each time you call ReadStream. This size depends on Exchange server version. However 0x1000 is known to be a reliable read size value.
See also:
OpenStream, WriteStream, GetLastError

References mapi_provider::ctx, mapi_session::emsmdb, emsmdb_transaction(), global_mapi_ctx, mapi_object_get_handle(), mapi_object_get_logon_id(), mapi_object_get_session(), OPENCHANGE_CHECK_NOTIFICATION, and OPENCHANGE_RETVAL_IF.

Referenced by WrapCompressedRTFStream().

_PUBLIC_ enum MAPISTATUS SeekStream ( mapi_object_t obj_stream,
uint8_t  Origin,
uint64_t  Offset,
uint64_t *  NewPosition 
)

Seek a specific position within the stream

Parameters:
obj_stream the stream object
Origin origin location for the seek operation
Offset the seek offset
NewPosition pointer on the new position after the operation

Origin can either take one of the following values:

0x0 The new seek pointer is an offset relative to the beginning of the stream. 0x1 The new seek pointer is an offset relative to the current seek pointer location. 0x2 The new seek pointer is an offset relative to the end of the stream.

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: obj_stream is not valid, Origin is out of limits, or NewPosition is null.
  • MAPI_E_CALL_FAILED: A network problem was encountered during the transaction
See also:
OpenStream, ReadStream

References mapi_provider::ctx, mapi_session::emsmdb, emsmdb_transaction(), global_mapi_ctx, mapi_object_get_handle(), mapi_object_get_logon_id(), mapi_object_get_session(), OPENCHANGE_CHECK_NOTIFICATION, and OPENCHANGE_RETVAL_IF.

_PUBLIC_ enum MAPISTATUS SetStreamSize ( mapi_object_t obj_stream,
uint64_t  SizeStream 
)

Set the stream size

Parameters:
obj_stream the stream object
SizeStream the size of the stream
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: obj_stream is not valid
  • MAPI_E_CALL_FAILED: A network problem was encountered during the transaction
See also:
OpenStream, GetStreamSize

References mapi_provider::ctx, mapi_session::emsmdb, emsmdb_transaction(), global_mapi_ctx, mapi_object_get_handle(), mapi_object_get_logon_id(), mapi_object_get_session(), OPENCHANGE_CHECK_NOTIFICATION, and OPENCHANGE_RETVAL_IF.

_PUBLIC_ enum MAPISTATUS UnlockRegionStream ( mapi_object_t obj_stream,
uint64_t  RegionOffset,
uint64_t  RegionSize,
uint32_t  LockFlags 
)

Unlock a range of bytes within the stream

Parameters:
obj_stream the stream object
RegionOffset starting point for the range
RegionSize length of the range
LockFlags type of locking

LockFlags used in unlocking must match the LockFlags used in locking.

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: obj_stream is not valid
  • MAPI_E_CALL_FAILED: A network problem was encountered during the transaction
See also:
UnlockRegionStream

References mapi_provider::ctx, mapi_session::emsmdb, emsmdb_transaction(), global_mapi_ctx, mapi_object_get_handle(), mapi_object_get_logon_id(), mapi_object_get_session(), and OPENCHANGE_RETVAL_IF.

_PUBLIC_ enum MAPISTATUS WriteAndCommitStream ( mapi_object_t obj_stream,
DATA_BLOB *  blob,
uint16_t *  WrittenSize 
)

Write and commit a buffer to the stream

This function writes and commits the contents of a DATA_BLOB to the stream obj_stream.

Parameters:
obj_stream the opened stream object
blob the DATA_BLOB to write to the stream
WrittenSize the actual number of bytes written to the stream
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: A problem occured obtaining the session context, or the stream or blob were null.
  • MAPI_E_CALL_FAILED: A network problem was encountered during the transaction
  • MAPI_E_TOO_BIG: the data blob was too large to process
The data size intended to be written to the stream should not exceed a maximum size each time you call WriteStream. This size depends on Exchange server version. However 0x1000 is known to be a reliable write size value.
See also:
WriteStream, CommitStream

References mapi_provider::ctx, mapi_session::emsmdb, emsmdb_transaction(), global_mapi_ctx, mapi_object_get_handle(), mapi_object_get_logon_id(), mapi_object_get_session(), and OPENCHANGE_RETVAL_IF.

_PUBLIC_ enum MAPISTATUS WriteStream ( mapi_object_t obj_stream,
DATA_BLOB *  blob,
uint16_t *  WrittenSize 
)

Write buffer to the stream

This function writes the stream specified as a DATA_BLOB in data to the stream obj_stream.

Parameters:
obj_stream the opened stream object
blob the DATA_BLOB to write to the stream
WrittenSize the actual number of bytes written to the stream
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: A problem occured obtaining the session context, or blob was null.
  • MAPI_E_CALL_FAILED: A network problem was encountered during the transaction
  • MAPI_E_TOO_BIG: the data blob was too large to process
The data size intended to be written to the stream should not exceed a maximum size each time you call WriteStream. This size depends on Exchange server version. However 0x1000 is known to be a reliable write size value.
See also:
OpenStream, ReadStream, GetLastError

References mapi_provider::ctx, mapi_session::emsmdb, emsmdb_transaction(), global_mapi_ctx, mapi_object_get_handle(), mapi_object_get_logon_id(), mapi_object_get_session(), OPENCHANGE_CHECK_NOTIFICATION, 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/