ISyncChangeBatchBase2::SerializeWithOptions
Serializa los datos de objeto de lote de cambios en una matriz de bytes basada en la versión especificada y en las opciones de serialización.
HRESULT SerializeWithOptions(
SYNC_SERIALIZATION_VERSION targetFormatVersion,
DWORD dwFlags,
BYTE * pbBuffer,
DWORD * pdwSerializedSize);
Parámetros
Término |
Definición |
targetFormatVersion |
[in] Lote de cambios serializado que es compatible con esta versión. |
dwFlags |
[in] Reservado. Debe ser 0. |
pbBuffer |
[in, out, unique, size_is(*pdwSerializedSize)] Búfer donde se serializa el objeto de lote de cambios serializado. |
pdwSerializedSize |
[in, out] Especifica el número de bytes de pBuffer. Devuelve el número de bytes necesarios para serializar los datos del lote de cambios si pBuffer es demasiado pequeño o bien el número de bytes escritos. |
Valor devuelto
S_OK.
E_INVALIDARG si dwFlags no es 0 o si la versión que se especifica a través de targetFormatVersion no es compatible con los datos de objeto de lote de cambios.
E_OUTOFMEMORY.
E_POINTER.
HRESULT_FROM_WIN32(ERROR_MORE_DATA) si pBuffer es demasiado pequeño. En esta situación, el número necesario de bytes se devuelve en pdwSerializedSize.
SYNC_E_INVALID_OPERATION si el lote de cambios contiene un grupo que se inició pero no finalizó.
SYNC_E_INVALID_VERSION cuando el valor de targetFormatVersion es mayor que la versión del objeto o cuando el objeto contiene elementos que no son compatibles con targetFormatVersion.
Notas
El valor de targetFormatVersion determina el formato de los datos del lote de cambios serializados. Cuando se especifica SYNC_SERIALIZATION_VERSION_V1, el formato serializado es compatible con componentes de Sync Framework 1.0 y versiones posteriores. Cuando se especifica SYNC_SERIALIZATION_VERSION_V2, el formato serializado es compatible con los componentes de Sync Framework 2.0. Si se especifica SYNC_SERIALIZATION_VERSION_V2 cuando el objeto del lote de cambios contiene elementos que no son compatibles con Sync Framework 1.0, se devuelve E_INVALIDARG o SYNC_E_INVALID_OPERATION.
Nota
La serialización en el formato de Sync Framework 1.0 es menos eficaz que en el formato de Sync Framework 2.0. A menos que exista una necesidad concreta para usar el formato de Sync Framework 1.0, se debe utilizar el formato de Sync Framework 2.0.
Formato de serialización
El lote de cambios serializado incluido en pbBuffer se almacena con un formato compacto, sin margen y en orden de byte "big-endian". El conocimiento del lote de cambios contiene los elementos siguientes, en el orden que se describe a continuación.
Una sección de encabezado. La sección de encabezado contiene los elementos siguientes.
Tipo de datos Longitud en bytes Descripción ULONGLONG
8
Versión del formato de serialización del lote de cambios. Este valor es 3 si targetFormatVersion es SYNC_SERIALIZATION_VERSION_V1, 4 si targetFormatVersion es SYNC_SERIALIZATION_VERSION_V2 y 5 si targetFormatVersion es SYNC_SERIALIZATION_VERSION_V3.
Una sección de información de filtro si targetFormatVersion es SYNC_SERIALIZATION_VERSION_V2 y la información del filtro se encuentra en el lote de cambios. La sección de información de filtro contiene los elementos siguientes.
Tipo de datos Longitud en bytes Descripción ULONG
4
Longitud, en bytes, de la sección de información del filtro.
El resto de la sección de información del filtro está en el formato descrito en ISyncFilterInfo::Serialize.
Una sección de conocimiento de destino. La sección de conocimiento de destino contiene los elementos siguientes.
Tipo de datos Longitud en bytes Descripción ULONG
4
Longitud, en bytes, de la sección de conocimiento de destino. Esta longitud puede ser 0, en cuyo caso no existe conocimiento de destino posterior.
Secuencia de bytes
Longitud especificada en el elemento ULONG anterior.
Si targetFormatVersion es SYNC_SERIALIZATION_VERSION_V1, el conocimiento de destino está en el formato que describe ISyncKnowledge::Serialize. De lo contrario, el conocimiento de destino está en el formato que describe ISyncKnowledge2::SerializeWithOptions. El conocimiento de destino serializado siempre contiene el mapa de claves de réplica serializado.
Una sección de conocimiento olvidado de origen. La sección de conocimiento olvidado de origen contiene los elementos siguientes.
Tipo de datos Longitud en bytes Descripción ULONG
4
Longitud, en bytes, de la sección de conocimiento olvidado de origen. Esta longitud puede ser 0, en cuyo caso no existe conocimiento olvidado de origen posterior.
Secuencia de bytes
Longitud especificada en el elemento ULONG anterior.
Si targetFormatVersion es SYNC_SERIALIZATION_VERSION_V1, el conocimiento olvidado de origen está en el formato que describe ISyncKnowledge::Serialize. Por otra parte, el conocimiento olvidado de origen está en el formato que describe ISyncKnowledge2::SerializeWithOptions. El conocimiento olvidado de origen serializado siempre contiene el mapa de claves de réplica serializado.
Una sección de mapa de claves de filtro de origen si targetFormatVersion es SYNC_SERIALIZATION_VERSION_V3 y la información del mapa de claves de filtro de origen existe. La sección de mapa de claves de filtro de origen contiene los elementos siguientes.
Tipo de datos Longitud en bytes Descripción ULONG
4
Longitud, en bytes, de la sección de mapa de claves de filtro de origen. Esta longitud puede ser 0, en cuyo caso no existe mapa de claves de filtro de origen.
USHORT
2
Versión del formato de serialización del mapa de claves de filtro. Este valor es SYNC_SERIALIZATION_VERSION_V3.
ULONG
4
Número de filtros en el mapa de claves de filtro.
Cada filtro del mapa de claves de filtro contiene los elementos siguientes.
Tipo de datos Longitud en bytes Descripción ULONG
4
Longitud en bytes del filtro.
Secuencia de bytes
Longitud especificada en el elemento ULONG anterior.
Datos de filtro serializados que el método ISyncFilter::Serialize escribió en la secuencia.
Una sección de conocimiento que da origen. La sección de conocimiento que da origen contiene los elementos siguientes.
Tipo de datos Longitud en bytes Descripción ULONG
4
Número de objetos de conocimiento que da origen que contienen los datos serializados. Este número puede ser 0, en cuyo caso no existe conocimiento que da origen posterior.
Cada conocimiento que da origen contiene los elementos siguientes.
Tipo de datos Longitud en bytes Descripción ULONG
4
Longitud, en bytes, del conocimiento que da origen.
Secuencia de bytes
Longitud especificada en el elemento ULONG anterior.
Si targetFormatVersion es SYNC_SERIALIZATION_VERSION_V1, el conocimiento que da origen está en el formato que describe ISyncKnowledge::Serialize. De lo contrario, el conocimiento que da origen está en el formato que describe ISyncKnowledge2::SerializeWithOptions. El conocimiento que da origen serializado siempre contiene el mapa de claves de réplica serializado.
Una sección del conjunto de cambios. La sección del conjunto de cambios contiene los elementos siguientes.
Tipo de datos Longitud en bytes Descripción ULONG
4
El número de objetos de cambio que contienen los datos serializados. Este número puede ser 0, en cuyo caso no existen cambios posteriores.
Cada cambio contiene los elementos siguientes.
Tipo de datos Longitud en bytes Descripción ULONG
4
Longitud, en bytes, de los datos de cambio.
ULONGLONG
8
La firma del formato de serialización del objeto de cambios. Este valor es 5 si targetFormatVersion es SYNC_SERIALIZATION_VERSION_V1 o SYNC_SERIALIZATION_VERSION_V2 y 6 si targetFormatVersion es SYNC_SERIALIZATION_VERSION_V3.
Si los identificadores de réplica son de longitud fija.
Tipo de datos Longitud en bytes Descripción Secuencia de bytes
Longitud especificada en el formato del identificador de réplica.
Identificador de réplica de longitud fija.
O bien, si los identificadores de réplica son de longitud variable.
Tipo de datos Longitud en bytes Descripción USHORT
2
Longitud, en bytes, del identificador de longitud variable. Esta longitud incluye los dos bytes del elemento USHORT que contiene la longitud, además de los bytes que contienen el identificador real.
Secuencia de bytes
Longitud especificada en el elemento USHORT anterior.
Identificador de réplica de longitud variable.
Cada cambio contiene los elementos adicionales siguientes.
Tipo de datos Longitud en bytes Descripción ULONG
4
Clave de réplica que identifica a la réplica que efectuó este cambio.
ULONGLONG
8
Contador de la réplica que efectuó este cambio.
ULONG
4
Reservado. Este valor se puede ignorar.
ULONGLONG
8
Reservado. Este valor se puede ignorar.
ULONG
4
Clave de réplica que identifica a la réplica que creó este elemento.
ULONGLONG
8
Contador de la réplica que creó este elemento.
Si los identificadores de elemento son de longitud fija.
Tipo de datos Longitud en bytes Descripción Secuencia de bytes
Longitud especificada en el formato del identificador de elemento.
Identificador de elemento de longitud fija.
O bien, si los identificadores de elemento son de longitud variable.
Tipo de datos Longitud en bytes Descripción USHORT
2
Longitud, en bytes, del identificador de longitud variable. Esta longitud incluye los dos bytes del elemento USHORT que contiene la longitud, además de los bytes que contienen el identificador real.
Secuencia de bytes
Longitud especificada en el elemento USHORT anterior.
Identificador de elemento de longitud variable.
Si targetFormatVersion es SYNC_SERIALIZATION_VERSION_V3 o posterior, cada cambio contiene los elementos adicionales siguientes.
Tipo de datos Longitud en bytes Descripción BOOL
1
Indica si existe un identificador ganador en los datos serializados. Un valor de 0 indica que no existen identificadores ganadores posteriores. Un valor de 1 indica que existe un identificador ganador posterior.
Si los identificadores de elemento son de longitud fija.
Tipo de datos Longitud en bytes Descripción Secuencia de bytes
Longitud especificada en el formato del identificador de elemento.
Identificador ganador de longitud fija.
O bien, si los identificadores de elemento son de longitud variable.
Tipo de datos Longitud en bytes Descripción USHORT
2
Longitud, en bytes, del identificador de longitud variable. Esta longitud incluye los dos bytes del elemento USHORT que contiene la longitud, además de los bytes que contienen el identificador real.
Secuencia de bytes
Longitud especificada en el elemento USHORT anterior.
Identificador ganador de longitud variable.
Cada cambio contiene los elementos adicionales siguientes.
Tipo de datos Longitud en bytes Descripción ULONG
4
Marcas asociadas al cambio. Este valor es una combinación de las marcas SYNC_CHANGE_FLAG.
ULONG
4
Estimación de trabajo para el cambio.
USHORT
2
Reservado. Este valor siempre es 0.
BYTE
1
Indica si el conocimiento aprendido que está asociado a este cambio se proyecta en este elemento. Un valor de 0 indica que el conocimiento aprendido no se proyecta. Un valor de 1 indica que se proyecta el conocimiento aprendido.
ULONG
4
Un índice en la lista de conocimiento que da origen que se incluye en estos datos serializados. Este valor puede ser 0, que indica que un conocimiento que da origen no está asociado a este cambio.
ULONG
4
El número de unidades de cambio que contiene este cambio. Este valor puede ser 0, en cuyo caso no existen unidades de cambio posteriores.
El cambio contiene una lista de unidades de cambio, con un número de unidades de cambio igual al valor contenido en el ULONG anterior.
Cada unidad de cambio contiene los elementos siguientes.
Si los identificadores de unidad de cambio son de longitud fija.
Tipo de datos Longitud en bytes Descripción Secuencia de bytes
Longitud especificada en el formato del identificador de unidad de cambio.
Identificador de unidad de cambio de longitud fija.
O bien, si los identificadores de unidad de cambio son de longitud variable.
Tipo de datos Longitud en bytes Descripción USHORT
2
Longitud, en bytes, del identificador de longitud variable. Esta longitud incluye los dos bytes del elemento USHORT que contiene la longitud, además de los bytes que contienen el identificador real.
Secuencia de bytes
Longitud especificada en el elemento USHORT anterior.
Identificador de unidad de cambio de longitud variable.
Cada unidad de cambio contiene los elementos adicionales siguientes.
Tipo de datos Longitud en bytes Descripción ULONG
4
Clave de réplica que identifica la réplica que efectuó este cambio.
ULONGLONG
8
Contador de la réplica que efectuó este cambio.
ULONG
4
Reservado. Este valor siempre es 0.
ULONGLONG
8
Reservado. Este valor siempre es 0.
Una sección de sincronización de recuperación. La sección de sincronización de recuperación contiene los elementos siguientes.
Tipo de datos Longitud en bytes Descripción ULONG
4
Longitud, en bytes, de la sección de sincronización de recuperación. Cuando este valor es 0, no existen secciones de sincronización de recuperación posteriores.
Si los identificadores de elemento son de longitud fija.
Tipo de datos Longitud en bytes Descripción Secuencia de bytes
Longitud especificada en el formato del identificador de elemento.
Identificador de elemento de longitud fija que representa el límite inferior de los cambios en este lote de cambios, cuando el lote de cambios forma parte de una sincronización de recuperación.
O bien, si los identificadores de elemento son de longitud variable.
Tipo de datos Longitud en bytes Descripción USHORT
2
Longitud, en bytes, del identificador de longitud variable. Esta longitud incluye los dos bytes del elemento USHORT que contiene la longitud, además de los bytes que contienen el identificador real.
Secuencia de bytes
Longitud especificada en el elemento USHORT anterior.
Identificador de elemento de longitud variable que representa el límite inferior de los cambios en este lote de cambios, cuando el lote de cambios forma parte de una sincronización de recuperación.
Una sección de estimación de trabajo. La sección de estimación de trabajo contiene los elementos siguientes.
Tipo de datos Longitud en bytes Descripción ULONG
4
Estimación de trabajo para la sesión de sincronización.
ULONG
4
Estimación de trabajo total para este lote de cambios.
Una sección de marcas. La sección de marcas contiene los elementos siguientes.
Tipo de datos Longitud en bytes Descripción BYTE
1
Indica si este lote de cambios es el último que envía el proveedor de origen. Un valor de 0 indica que este no es el último lote de cambios. Un valor de 1 indica que este es el último lote de cambios.
BYTE
1
Indica si este lote de cambios forma parte de una sincronización de recuperación. Un valor de 0 indica que este lote de cambios no forma parte de una sincronización de recuperación. Un valor de 1 indica que este lote de cambios forma parte de una sincronización de recuperación.
BYTE
1
Indica si se filtra este lote de cambios. Un valor de 0 indica que este lote de cambios no se ha filtrado. Un valor de 1 indica que se ha filtrado este lote de cambios.