Registo de filtros de fluxo personalizados

O HotPDF consegue descodificar filtros de stream PDF definidos pela aplicação dentro do mesmo pipeline delimitado que usa para os decoders Flate, LZW, ASCII85, ASCIIHex e RunLength incorporados

Register push or pull filters

Implemente IHPDFCustomStreamFilter, escolha csfmPush ou csfmPull e registe a interface através de THotPDF.RegisterCustomStreamFilter

Os nomes são comparados sem distinção de maiúsculas e minúsculas e sem barra inicial, o registo duplicado é explícito, os nomes incorporados não podem ser substituídos e cada documento aceita no máximo 64 nomes personalizados

As consultas ao registo retêm um snapshot da interface durante uma secção crítica curta; os callbacks do filtro e a destruição da interface correm fora do lock do registo

One budget across every stage

A saída personalizada consome DecodeBudgetBytes e DocumentDecodeBudgetBytes através do tracker agregado existente, pelo que uma cadeia mista de filtros personalizados e incorporados não consegue repor a contabilização da expansão entre etapas

THPDFCustomStreamFilterRequest.MaxOutputBytes reporta a quota restante por cadeia, e zero significa que o orçamento configurado por cadeia é ilimitado

O pedido fornece ainda o nome do filtro PDF descodificado, o índice da etapa (a partir de zero), a profundidade do pipeline, o tamanho da entrada quando disponível e o cancellation token de quem chama

Cancellation and seek contracts

O overload de DecodeLoadedStreamToStream com suporte a cancelamento verifica antes e depois da execução personalizada e durante a transferência do pull stream

Custom implementations should check Request.CancellationToken inside long push loops or blocking external work

csscSeekable declara que a entrada emprestada, o destino push ou o pull stream devolvido têm de suportar seek; as violações do contrato produzem dpsSeekContractViolation

Failure isolation

Cada etapa personalizada escreve para um THPDFAdaptiveTempStream delimitado antes de qualquer byte ser publicado para a etapa seguinte ou para o destino de quem chama

Um resultado false, uma exceção, um cancelamento, uma violação de seek ou uma falha de orçamento descartam essa saída temporária e devolvem um estado de pipeline tipado, sem deixar escapar uma exceção personalizada através da fronteira pública de descodificação

Um pull filter bem-sucedido transfere para o HotPDF a posse do stream que devolve; devolver a entrada emprestada ou um stream nil é rejeitado

Telemetry

GetCustomStreamFilterStatistics reporta os nomes registados, as tentativas push e pull, as contagens de sucessos, falhas, cancelamentos e violações de seek, os bytes agregados de entrada e produzidos, e ainda o último nome e diagnóstico

THPDFDecodePipelineInfo.CustomFilterCount e CustomFilterFailureCount describe the current chain

Exemplo

Filter := TApplicationFilter.Create;
PDF.RegisterCustomStreamFilter(Filter);
try
  if not PDF.DecodeLoadedStreamToStream(StreamObject, Output,
    CancellationToken, Info) then
    HandleDecodeFailure(Info.Status, Info.Diagnostic);
finally
  PDF.UnregisterCustomStreamFilter(Filter.FilterName);
end;

APIs relacionadas