Share via

ISyncFilterInfo::Serialize

  • Article

Serializes the filter data to an array of bytes.

HRESULT Serialize( 
  BYTE *pbBuffer,
  DWORD *pcbBuffer);

Parameters

  • pbBuffer
    [in, out, size_is(*pcbBuffer)] Returns the serialized filter information. Set this value to NULL to request the required size of the buffer.
  • pcbBuffer
    [in, out] Specifies the number of bytes in pbBuffer. Returns the number of bytes required to serialize the filter when pcbBuffer is too small, or the number of bytes written.

Return Value

  • S_OK.

  • E_INVALIDARG.

  • 0x800700EA (HRESULT_FROM_WIN32(ERROR_MORE_DATA)) when pbBuffer is NULL or pcbBuffer is too small. In this case, the number of bytes required to serialize the filter is returned in pcbBuffer.

Serialization Format

The serialized filter information that is contained in pbBuffer is stored in compact form, with no padding, in big-endian byte order. The serialized filter information contains the following elements, in the following order.

  1. One header section. The header section contains the following elements.

    Data type Length in bytes Description

    ULONGLONG

    8

    The version of the serialization format of the filter information. This value is 2 when the filter is an item filter or a change unit filter. This value is 3 when the filter is a custom filter or a combined filter.

    ULONG

    4

    The flags associated with the filter information. This contains values from the set of SYNC_FILTER_INFO_FLAG flags.

  2. When the flags include SYNC_FILTER_INFO_FLAG_ITEM_LIST or SYNC_FILTER_INFO_FLAG_CHANGE_UNIT_LIST, the following filter data is serialized.

    Data type Length in bytes Description

    BOOL

    1

    Indicates whether change unit IDs that are contained in the filter information are fixed length or variable length. This value is 0 if the IDs are fixed length; or 1 if the IDs are variable length.

    USHORT

    2

    The length, in bytes, of change unit IDs for fixed-length IDs, or the maximum length of the ID for variable-length IDs.

    ULONG

    4

    The number of change unit IDs that are contained in the filter information.

    The filter information contains a list of change unit IDs with the length of the list equal to the value contained in the previous ULONG.

    Each change unit ID contains the following elements.

    When change unit IDs are fixed length.

    Data type Length in bytes Description

    Sequence of bytes

    The length specified in the change unit ID format.

    The fixed-length change unit ID.

    Or, when change unit IDs are variable length.

    Data type Length in bytes Description

    USHORT

    2

    The length, in bytes, of the variable-length ID. This length includes the two bytes for the USHORT that contains the length, plus the bytes that contain the actual ID.

    Sequence of bytes

    The length specified in the previous USHORT.

    The variable-length change unit ID.

  3. When the flags include SYNC_FILTER_INFO_FLAG_CUSTOM, the following filter data is serialized.

    Data type Length in bytes Description

    Sequence of bytes

    Determined by the custom filter.

    The serialized filter data that was written to the stream by the ISyncFilter::Serialize method.

  4. When the flags include SYNC_FILTER_INFO_COMBINED, the following filter data is serialized.

    Data type Length in bytes Description

    ULONG

    4

    The length, in bytes, of the first filter information object in the combination.

    Sequence of bytes

    The length specified in the previous ULONG.

    The serialized filter information of the first filter, in the format specified by this document.

    ULONG

    4

    The length, in bytes, of the second filter information object in the combination.

    Sequence of bytes

    The length specified in the previous ULONG.

    The serialized filter information of the second filter, in the format specified by this document.

See Also

Reference

ISyncFilterInfo Interface