Un handle de documento no nulo con conteo de páginas cero es lo que FPDFAvail_GetDocument puede devolver cuando se lo llama sobre un PDF que nunca fue linearizado, incluso después de que FPDFAvail_IsDocAvail reportó PDF_DATA_AVAIL. El handle parece abierto, nada se queja, y el visor muestra un documento vacío. La API de disponibilidad de PDFium lee el layout linearizado del Anexo F de ISO 32000-1; cualquier otro archivo tiene que estar completo y abrirse por el camino ordinario de documento custom. Esa decisión de routing es la mitad de lo que implica abrir un PDF durante la descarga. La otra mitad es el usuario que cierra la pestaña a un cuarto del archivo y vuelve a abrir el mismo enlace un momento después
El bucle de disponibilidad detrás de TPdfProgressiveDocument
En el PDFium Component toda la sesión vive en TPdfProgressiveDocument, una subclase de TPdf que mantiene vivo un proveedor de disponibilidad de PDFium mientras un stream de acceso aleatorio se llena. BeginProgressiveLoad(AStream, AFileSize, AOwnsStream, AInitialAvailableByteCount) toma el stream de respaldo y el tamaño lógico del archivo remoto (el Content-Length, no el largo actual de su store local), cablea un callback IsDataAvail y un callback AddSegment, y llama a FPDFAvail_Create. Una vez que OpenProgressiveDocument tiene éxito, el objeto se comporta como cualquier otro TPdf activo: páginas, texto, renderizado y guardado funcionan todos por los miembros de siempre
Cada paso de parseo es una pregunta a su código. Cuando PDFium quiere un rango, el componente responde que sí si el rango cae dentro del prefijo contiguo descrito por AvailableByteCount, o dentro de un rango ya completado a través del scheduler RangeRequests. Un handler OnDataAvailable tiene entonces la última palabra, que es como una caché dispersa responde por rangos que ninguno de los dos puede describir. CheckDocumentAvailability devuelve uno de tres valores TPdfDataAvailability (pdaAvailable, pdaNotAvailable, pdaError) y entrega los rangos de bytes que PDFium pidió como un array TPdfDownloadRanges ordenado y fusionado. Esos rangos ya están en cola en el scheduler con prioridad rrpImmediate para cuando usted los ve, así que el array de hints es para logging y muestra de progreso; la cola de trabajo es RangeRequests
// FetchRange es su transporte (HTTP Range GET, socket, lector de blob):
// escribe Size bytes en Offset dentro de Store y devuelve cuántos llegaron
function FetchRange(Store: TStream; Offset, Size: UInt64): UInt64; forward;
procedure OpenWhileDownloading(Pdf: TPdfProgressiveDocument; Store: TStream;
RemoteSize: UInt64);
const
MaxRounds = 64;
var
Hints: TPdfDownloadRanges;
State: TPdfDataAvailability;
Request: TPdfRangeRequest;
Round: Integer;
begin
Pdf.BeginProgressiveLoad(Store, RemoteSize, False);
State := pdaNotAvailable;
for Round := 1 to MaxRounds do
begin
State := Pdf.CheckDocumentAvailability(Hints);
if State <> pdaNotAvailable then
Break;
// Los hints ya están en cola; escriba primero los bytes, después complete
while Pdf.RangeRequests.TryDequeue(Request) do
Pdf.RangeRequests.CompleteRequest(Request,
FetchRange(Store, Request.Offset, Request.Size));
end;
if State <> pdaAvailable then
raise EPdfError.Create('The document could not be discovered');
Pdf.OpenProgressiveDocument;
end;
Dos detalles de ese bucle cargan peso. El tope de rondas existe porque un enlace muerto hace que CheckDocumentAvailability pida los mismos rangos en cada llamada, y un bucle sin tope convierte una falla de red en una UI colgada. El orden importa porque el scheduler serializa su propio estado con una critical section pero no hace nada por TStream.Position del store de respaldo. Un hilo de transporte tiene que escribir los bytes de la respuesta en el stream antes de llamar a CompleteRequest, porque PDFium puede leer el rango en el momento en que la completion se publica. Los escritores concurrentes necesitan I/O posicionado o un lock propio
¿Por qué AvailableByteCount se niega a retroceder?
AvailableByteCount solo crece. Asignarle un valor menor lanza un EPdfError con «Available byte count cannot move backwards», porque una vez que el callback de disponibilidad le dijo a PDFium que un rango existe, el parser ya pudo haber leído y cacheado objetos de él. Quitar esos bytes después dejaría a PDFium sosteniendo objetos cuya fuente las respuestas de disponibilidad ahora niegan. El mismo setter rechaza valores mayores que LogicalFileSize y lanza «No progressive load is active» fuera de una sesión
Ese último chequeo decide dónde pertenecen los bytes que usted ya tiene. Si una visita anterior dejó los primeros 300 KB del archivo en una caché, pase ese conteo como AInitialAvailableByteCount; el componente lo registra antes de que corra FPDFAvail_Create, así que la primera mirada de PDFium al header ya lo ve. Con un conteo inicial de cero, Linearization se lee plnUnknown hasta que PDFium ha visto el header; ese es el estado inicial normal
Subir el prefijo también cancela trabajo. Cualquier request en vuelo que se superponga con los bytes recién anunciados queda redundante, así que el scheduler lo bota y dispara OnCancelRequest para él; un CompleteRequest tardío para ese request devuelve False. Un store que se llena fuera de orden no debería intentar expresarse por el prefijo para nada. Complete los rangos a través del scheduler, o responda por rango en OnDataAvailable. Una excepción lanzada dentro de ese handler no puede cruzar la frontera del callback C, así que el componente la atrapa y reporta el rango como ausente, y PDFium simplemente pregunta de nuevo en el próximo chequeo
¿Cuándo puede abrirse de verdad un PDF descargado a medias?
Solo un PDF linearizado abre antes de que llegue el archivo completo. OpenProgressiveDocument chequea la propiedad Linearization (plnUnknown, plnNotLinearized, plnLinearized) y elige el loader. Un archivo linearizado abre a través de FPDFAvail_GetDocument apenas están presentes la sección de primera página y las tablas de hints. Un archivo no linearizado va por FPDF_LoadCustomDocument sobre el mismo record de acceso a archivo, y para un archivo así PDFium solo reporta el documento como disponible cuando cada byte está ahí. Ese routing es lo que mantiene fuera de su visor el handle de cero páginas del párrafo inicial
Así que el archivo en el servidor decide qué tan rápido aparece la primera página. Si el tiempo hasta el primer pintado importa y usted controla el lado de publicación, linearice los archivos ahí. TPdf.SaveAsLinearized escribe el layout del Anexo F desde el componente mismo, y el recorrido de Fast Web View y tablas de hints cubre lo que ese layout contiene. Para archivos que usted no controla, un PDF no linearizado igual carga a través del mismo bucle; solo llega a pdaAvailable al 100 por ciento en lugar de temprano
LoadAvailablePage toma un número de página base 1 y conserva el orden que PDFium espera. Antes del primer chequeo de página corre CheckFormAvailability, que envuelve a FPDFAvail_IsFormAvail, y solo después llama a FPDFAvail_IsPageAvail. Un resultado pfaNotPresent es la respuesta normal para un documento sin AcroForm y no bloquea nada. Cuando la página está lista, LoadAvailablePage la vuelve la página activa, así que un visor puede renderizar la página 1 de un folleto linearizado mientras las páginas restantes siguen en tránsito. La espera de página tiene la misma forma que el primer listado: llame a LoadAvailablePage, drene RangeRequests en pdaNotAvailable, deténgase en pdaAvailable o pdaError, y mantenga un tope de rondas. FirstAvailablePageNumber reporta la página que el diccionario de linearización designa como primera, ya convertida del índice base cero de PDFium. Para un archivo no linearizado cada página reporta pdaAvailable de inmediato, porque el documento solo pudo abrirse una vez que el archivo estaba completo
Reintentos, lecturas cortas y prioridades en el scheduler de rangos
La API FPDFAvail_* en sí no sabe nada de redes. Dice qué bytes necesita el parser ahora mismo y pregunta de nuevo después; no existe la noción de request, reintento o cancel. TPdfRangeRequestScheduler suministra esas cosas, y cuatro de sus reglas moldean cómo usted escribe el transporte
- Una respuesta corta se trata como progreso.
CompleteRequest(Request, BytesReceived)con menos bytes de los pedidos publica el prefijo y pone en cola el resto. La respuesta corta también cuenta como intento fallido, así que el resto sigue atado porMaxRetryCounty se abandona cuando se agota; cero bytes es un intento fallido a secas MaxRetryCountviene en 2, así que un rango recibe tres intentos en total.FailRequestdevuelveTruecuando re-encoló el rango yFalseuna vez que el rango se abandona;Statistics.AbandonedRequestCountrastrea cuántos se rindieronMaxRequestSizeparte los rangos grandes en chunks al momento de dequear, yMergeGapdeja que dos rangos pendientes se fusionen a través de un hueco desconocido pequeño, pero nunca a través de bytes ya completados o en vuelo- Los hints de
CheckDocumentAvailabilityy deLoadAvailablePagellegan enrrpImmediate. Los hints de form de una llamada directa aCheckFormAvailabilityllegan enrrpNormal; cuandoLoadAvailablePagecorre ese chequeo por sí mismo y la data del form falta, los hints se encolan enrrpImmediate.TryDequeuesiempre sirve primero la prioridad más alta y el offset más bajo dentro de una prioridad
La regla de prioridad rinde cuando usted hace prefetch. Ponga en cola el archivo completo en rrpBackground justo después de que el documento abre, y el scheduler resta todo lo ya completado o en vuelo, así que solo los bytes faltantes van al cable. Cuando el usuario después salta a la página 40 y el hint de esa página se superpone con un chunk de fondo que ya está bajando, el scheduler jala el request de fondo, dispara OnCancelRequest para él, devuelve las colas no superpuestas a prioridad de fondo sin cobrarles un reintento, y encola la superposición como trabajo inmediato fresco. El salto gana la conexión. Sin eso, el request de página esperaría detrás de un chunk de 256 KB que no le importa
procedure TDownloadForm.QueueRestOfFile;
var
Whole: TPdfDownloadRanges;
begin
FPdf.RangeRequests.MaxRequestSize := 256 * 1024; // el tamaño de chunk lo decide usted
SetLength(Whole, 1);
Whole[0].Offset := 0;
Whole[0].Size := FPdf.LogicalFileSize;
FPdf.RangeRequests.EnqueueHints(Whole, rrpBackground);
end;
// Se llama en un hilo worker cuando una respuesta HTTP Range termina.
// WriteAt es su propia escritura posicionada dentro del store de respaldo
procedure TDownloadForm.RangeFinished(const Request: TPdfRangeRequest;
const Body: TBytes; Succeeded: Boolean);
begin
if Succeeded and (Length(Body) > 0) then
begin
WriteAt(FStore, Request.Offset, Body); // primero los bytes
FPdf.RangeRequests.CompleteRequest(Request, Length(Body));
end
else if not FPdf.RangeRequests.FailRequest(Request) then
TThread.Queue(nil, ShowRangeGaveUp); // abandonado, o de una sesión cancelada
end;
Tanto CompleteRequest como FailRequest son seguros de llamar desde el hilo worker; el scheduler toma su propio lock. Un request que fue reemplazado o pertenece a una sesión cancelada vuelve como False sin tocar nada, así que el worker no necesita saber por qué su rango quedó viejo
¿Qué libera CancelProgressiveLoad, y en qué orden?
CancelProgressiveLoad desarma una sesión en cuatro pasos, siempre en el mismo orden: cancelar el scheduler de rangos, cerrar el documento, destruir el handle de disponibilidad con FPDFAvail_Destroy, y luego liberar los records de callback y el stream adapter. Cancelar primero el scheduler avanza su contador de generación, suelta todo request pendiente y en vuelo, y dispara OnCancelRequest por cada uno en vuelo. Una completion de transporte que aterrice después carga la generación vieja, y CompleteRequest devuelve False. El documento se cierra antes de que se vayan el handle de disponibilidad y el stream adapter porque PDFium todavía puede leer a través del proveedor de acceso a archivo mientras cierra un documento
procedure TDownloadForm.FormCreate(Sender: TObject);
begin
FPdf := TPdfProgressiveDocument.Create(nil);
// El scheduler vive tanto como FPdf, así que cablee una sola vez
FPdf.RangeRequests.OnCancelRequest := RangeCancelled;
end;
procedure TDownloadForm.RangeCancelled(Sender: TObject; RequestId: UInt64;
Attempt: Cardinal);
begin
FTransport.Abort(RequestId); // código suyo: cierre ese socket o request
end;
procedure TDownloadForm.CancelButtonClick(Sender: TObject);
begin
FPdf.CancelProgressiveLoad;
// ProgressiveLoading = False, Active = False, AvailableByteCount = 0
end;
El método es idempotente y sirve como el único camino de limpieza para tres situaciones: un BeginProgressiveLoad que falla a mitad de construcción, un cancel explícito del usuario, y el destructor. BeginProgressiveLoad también lo llama, así que reiniciar el mismo objeto sobre una URL nueva está bien mientras la sesión anterior nunca llegó a abrir. Una vez que OpenProgressiveDocument ha tenido éxito el objeto está activo, y BeginProgressiveLoad lanza el error de siempre «Cannot perform this operation on an active»; llame primero a CancelProgressiveLoad. OnCancelRequest es además el único lugar donde sus sockets se cierran, porque el scheduler no tiene idea de qué es un socket. Las excepciones lanzadas dentro de él se tragan por request, así que un abort que falle no puede bloquear al resto
Quien escribe el store decide quién lo posee. Con un hilo worker escribiendo en el stream de respaldo, pase AOwnsStream = False y libere el stream usted mismo después de que el worker se haya detenido. Entregar la propiedad significa que el cancel libera el stream mientras una escritura ya en curso puede seguir en camino. Conserve la propiedad siempre que un hilo distinto al llamador toque el store; AOwnsStream = True solo le queda bien a un transporte completamente síncrono como el primer listado
Funciones que esperan el archivo completo
Algunas funciones necesitan los bytes del archivo original, no el documento parseado, y se rehúsan de plano a una fuente progresiva incompleta. ReadXmpPacket lanza «PDF/A metadata is unavailable until progressive loading completes». ValidatePades devuelve un resultado cuyo SourceStatus es pvssIncomplete, y ValidatePdfMac reporta no soportado con un mensaje pidiendo la fuente completa. BeginIncrementalSave falla también, porque una actualización incremental tiene que agregar a los bytes exactos que se cargaron
El test de completitud detrás de todas ellas es AvailableByteCount alcanzando LogicalFileSize. Un transporte que entrega todo a través del scheduler puede entonces sostener cada byte y aun así que le digan que la fuente está incompleta, porque el prefijo contiguo nunca se movió. Publique el prefijo una vez que el scheduler confirma cobertura completa:
procedure TDownloadForm.CheckSignaturesWhenComplete;
var
Report: TPadesValidationResult;
begin
if FPdf.RangeRequests.IsRangeAvailable(0, FPdf.LogicalFileSize) then
FPdf.AvailableByteCount := FPdf.LogicalFileSize;
Report := FPdf.ValidatePades;
if Report.SourceStatus = pvssIncomplete then
LabelStatus.Caption := 'Signatures are checked when the download finishes'
else
ShowSignatureReport(Report); // su UI
end;
Un límite de tamaño aplica antes de que cualquiera de estas cosas arranque. En Windows FPDF_FILEACCESS guarda el largo del archivo en un campo de 32 bits, así que BeginProgressiveLoad rechaza un tamaño lógico por encima de 4 GiB con un EPdfError en lugar de dejar que PDFium parsee un largo truncado
Para cargar un archivo local completo a demanda a través de un stream adapter, vea hacer streaming de PDFs grandes a demanda con PDFium; para un PDF que está dentro de un buffer mayor, vea carga por byte range para PDFs incrustados. Detener un render lento de una página que ya llegó es un mecanismo aparte, cubierto en renderizado progresivo de páginas cancelable. TPdfProgressiveDocument, su scheduler de rangos y SaveAsLinearized son parte del PDFium Component para Delphi y C++Builder