Un handle de documento no nulo con recuento de páginas cero es lo que FPDFAvail_GetDocument puede devolver cuando se le llama sobre un PDF que nunca fue linealizado, incluso después de que FPDFAvail_IsDocAvail haya reportado PDF_DATA_AVAIL. El handle parece abierto, nadie se queja, y el visor muestra un documento vacío. La API de disponibilidad de PDFium lee la disposición linealizada del Anexo F de ISO 32000-1; cualquier otro archivo tiene que estar completo y abrirse por el camino ordinario de documento personalizado. Esa decisión de enrutado es la mitad de lo que implica abrir un PDF durante la descarga. La otra mitad es el usuario que cierra la pestaña con un cuarto del archivo y abre 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) recibe el stream de fondo y el tamaño lógico del archivo remoto (el Content-Length, no la longitud actual de su almacén local), cablea un callback IsDataAvail y un callback AddSegment, y llama a FPDFAvail_Create. Cuando 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 está dentro del prefijo contiguo descrito por AvailableByteCount, o dentro de un rango ya completado a través del planificador RangeRequests. Un handler OnDataAvailable recibe 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 de 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 encolados en el planificador a prioridad rrpImmediate para cuando usted los ve, así que el array de pistas es para logging y visualización de progreso; la cola de trabajo es RangeRequests
// FetchRange es tu transporte (HTTP Range GET, socket, lector de blobs):
// 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;
// Las pistas ya están encoladas; escribe primero los bytes, y luego completa
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 pesan. El tope de rondas existe porque un enlace muerto hace que CheckDocumentAvailability pida los mismos rangos en cada llamada, y un bucle sin límite convierte un fallo de red en una UI colgada. El orden importa porque el planificador serializa su propio estado con una sección crítica pero no hace nada por TStream.Position del almacén de fondo. 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 finalización se publica. Los escritores concurrentes necesitan E/S posicionada o un lock propio
¿Por qué AvailableByteCount se niega a retroceder?
AvailableByteCount solo crece. Asignar un valor menor lanza EPdfError con «Available byte count cannot move backwards», porque una vez que el callback de disponibilidad ha dicho a PDFium que un rango existe, el parser puede haber leído y cacheado objetos de él. Quitarle 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
Esa última comprobación 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 recuento como AInitialAvailableByteCount; el componente lo registra antes de que FPDFAvail_Create corra, así que la primera mirada de PDFium a la cabecera ya lo ve. Con un recuento inicial de cero, Linearization lee plnUnknown hasta que PDFium ha visto la cabecera; ese es el estado inicial normal
Subir el prefijo también cancela trabajo. Cualquier petición en vuelo que se solape con los bytes recién anunciados ahora es redundante, así que el planificador la suelta y dispara OnCancelRequest para ella; un CompleteRequest tardío para esa petición devuelve False. Un almacén que se llena fuera de orden no debería intentar expresarse a través del prefijo. Complete los rangos a través del planificador, 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 captura y reporta el rango como faltante, y PDFium simplemente vuelve a preguntar en la siguiente comprobación
¿Cuándo puede abrirse realmente un PDF descargado a medias?
Solo un PDF linealizado abre antes de que llegue el archivo entero. OpenProgressiveDocument consulta la propiedad Linearization (plnUnknown, plnNotLinearized, plnLinearized) y elige el loader. Un archivo linealizado abre a través de FPDFAvail_GetDocument en cuanto están la sección de primera página y las tablas de pistas. Un archivo no linealizado va por FPDF_LoadCustomDocument sobre el mismo registro de acceso a archivo, y para tal archivo PDFium solo reporta el documento como disponible cuando está cada byte. Ese enrutado 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 lo rápido que aparece la primera página. Si el tiempo hasta el primer pintado le importa y usted controla el lado de publicación, linealice los archivos allí. TPdf.SaveAsLinearized escribe la disposición del Anexo F desde el propio componente, y el recorrido de Fast Web View y tablas de pistas cubre lo que esa disposición contiene. Para archivos que usted no controla, un PDF no linealizado igual carga por el mismo bucle; solo que alcanza pdaAvailable al 100 por ciento en lugar de pronto
LoadAvailablePage recibe un número de página 1-based y mantiene el orden que PDFium espera. Antes de la primera comprobación de página corre CheckFormAvailability, que envuelve a FPDFAvail_IsFormAvail, y solo entonces 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 linealizado mientras las páginas posteriores 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 linealización designa como primera, ya convertida del índice zero-based de PDFium. Para un archivo no linealizado cada página reporta pdaAvailable de inmediato, porque el documento solo pudo abrirse cuando el archivo estuvo completo
Reintentos, lecturas cortas y prioridades en el planificador de rangos
La API FPDFAvail_* en sí no sabe nada de redes. Dice qué bytes necesita el parser ahora mismo y vuelve a preguntar más tarde; no hay noción de petición, reintento ni cancel. TPdfRangeRequestScheduler suministra eso, 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 encola el resto. La respuesta corta cuenta además como un intento fallido, así que el resto sigue atado aMaxRetryCounty se abandona cuando se agota; cero bytes es un intento fallido a secas MaxRetryCounttoma 2 por defecto, así que un rango recibe tres intentos en total.FailRequestdevuelveTruecuando re-encoló el rango yFalseuna vez el rango se abandona;Statistics.AbandonedRequestCountrastrea cuántos se rindieronMaxRequestSizeparte los rangos grandes en chunks en el momento del dequeue, yMergeGapdeja que dos rangos pendientes se fusionen a través de un pequeño hueco desconocido, pero nunca a través de bytes ya completados o en vuelo- Las pistas de
CheckDocumentAvailabilityyLoadAvailablePagellegan arrpImmediate. Las pistas de form de una llamada directa aCheckFormAvailabilityllegan arrpNormal; cuandoLoadAvailablePagehace esa comprobación por su cuenta y faltan los datos del form, las pistas se encolan arrpImmediate.TryDequeuesiempre atiende primero la prioridad más alta y el offset más bajo dentro de una prioridad
La regla de prioridad rinde cuando hace prefetch. Encole el archivo entero a rrpBackground justo después de que el documento abra, y el planificador resta todo lo ya completado o en vuelo, así que solo los bytes que faltan van al cable. Cuando el usuario salta luego a la página 40 y la pista de esa página se solapa con un chunk de fondo ya descargándose, el planificador retira la petición de fondo, dispara OnCancelRequest para ella, devuelve las colas no solapadas a prioridad de fondo sin cobrarles un reintento, y encola el solape como trabajo inmediato fresco. El salto gana la conexión. Sin eso, la petición 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 al almacén de fondo
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); // abandonada, o de una sesión cancelada
end;
Tanto CompleteRequest como FailRequest son seguros de llamar desde el hilo worker; el planificador toma su propio lock. Una petición que fue superada 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ó obsoleto
¿Qué libera CancelProgressiveLoad, y en qué orden?
CancelProgressiveLoad desmonta una sesión en cuatro pasos, siempre en el mismo orden: cancelar el planificador de rangos, cerrar el documento, destruir el handle de disponibilidad con FPDFAvail_Destroy, y luego liberar los registros de callbacks y el adaptador de stream. Cancelar el planificador primero avanza su contador de generación, suelta cada petición pendiente y en vuelo, y dispara OnCancelRequest por cada una en vuelo. Una finalización de transporte que aterriza después lleva la generación vieja, y CompleteRequest devuelve False. El documento se cierra antes de que se vayan el handle de disponibilidad y el adaptador de stream porque PDFium puede seguir leyendo a través del proveedor de acceso a archivo mientras cierra un documento
procedure TDownloadForm.FormCreate(Sender: TObject);
begin
FPdf := TPdfProgressiveDocument.Create(nil);
// El planificador vive lo mismo que FPdf, así que cablea una vez
FPdf.RangeRequests.OnCancelRequest := RangeCancelled;
end;
procedure TDownloadForm.RangeCancelled(Sender: TObject; RequestId: UInt64;
Attempt: Cardinal);
begin
FTransport.Abort(RequestId); // tu código: cierra ese socket o petición
end;
procedure TDownloadForm.CancelButtonClick(Sender: TObject);
begin
FPdf.CancelProgressiveLoad;
// ProgressiveLoading = False, Active = False, AvailableByteCount = 0
end;
El método es idempotente y sirve como ú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 va bien mientras la sesión anterior no llegó a abrirse. Una vez 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 sitio donde se cierran sus sockets, porque el planificador no tiene idea de qué es un socket. Las excepciones lanzadas dentro se tragan por petición, así que un abort fallido no puede bloquear al resto
Quien escribe el almacén decide quién lo posee. Con un hilo worker escribiendo en el stream de fondo, pase AOwnsStream = False y libere usted el stream después de que el worker se haya detenido. Entregar la propiedad significa que el cancel libera el stream mientras una escritura ya en marcha puede seguir en camino. Conserve la propiedad siempre que un hilo distinto del llamador toque el almacén; AOwnsStream = True solo encaja en un transporte totalmente síncrono como el primer listado
Funciones que esperan al archivo completo
Algunas funciones necesitan los bytes originales del archivo, no el documento parseado, y rechazan de plano 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 que pide la fuente completa. BeginIncrementalSave falla también, porque una actualización incremental tiene que añadirse sobre los bytes exactos que se cargaron
La prueba de completitud detrás de todas ellas es AvailableByteCount alcanzando LogicalFileSize. Un transporte que entrega todo a través del planificador puede por tanto sostener cada byte y aun así que le digan que la fuente está incompleta, porque el prefijo contiguo nunca se movió. Publique el prefijo cuando el planificador confirme 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 se aplica antes de que nada de esto arranque. En Windows FPDF_FILEACCESS guarda la longitud 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 una longitud truncada
Para cargar un archivo local completo bajo demanda a través de un adaptador de stream, vea streaming de PDFs grandes bajo demanda con PDFium; para un PDF que está dentro de un buffer mayor, vea carga por byte range de PDFs incrustados. Detener un render lento de una página que ya llegó es un mecanismo distinto, cubierto en renderizado progresivo de páginas cancelable. TPdfProgressiveDocument, su planificador de rangos y SaveAsLinearized forman parte del PDFium Component para Delphi y C++Builder