페이지 수 0짜리 null 아닌 문서 핸들은 선형화된 적 없는 PDF에 FPDFAvail_IsDocAvail이 PDF_DATA_AVAIL을 보고한 뒤에도 FPDFAvail_GetDocument가 돌려줄 수 있는 것입니다. 핸들은 열린 것처럼 보이고 아무도 불평하지 않으며 뷰어는 빈 문서를 보여 줍니다. PDFium의 가용성 API는 ISO 32000-1 부록 F의 선형화 배치를 읽고, 그 밖의 파일은 완전해야 하며 평범한 커스텀 문서 경로로 열어야 합니다. 그 라우팅 결정이 다운로드 중 PDF 여는 일의 절반입니다. 나머지 절반은 파일 4분의 1에서 탭을 닫았다가 잠시 뒤 같은 링크를 다시 여는 사용자입니다
TPdfProgressiveDocument 뒤의 가용성 루프
PDFium Component에서 세션 전체는 TPdfProgressiveDocument, 즉 무작위 접근 스트림이 차오르는 동안 PDFium 가용성 공급자를 살려 두는 TPdf 서브클래스에 삽니다. BeginProgressiveLoad(AStream, AFileSize, AOwnsStream, AInitialAvailableByteCount)는 백킹 스트림과 원격 파일의 논리 크기(로컬 저장소의 현재 길이가 아니라 Content-Length)를 받아 IsDataAvail 콜백과 AddSegment 콜백을 물리고 FPDFAvail_Create를 부릅니다. OpenProgressiveDocument가 성공하면 객체는 다른 살아 있는 TPdf처럼 동작합니다. 페이지, 텍스트, 렌더링, 저장이 모두 평범한 멤버로 동작합니다
모든 파싱 단계는 여러분 코드에 하는 질문입니다. PDFium이 범위를 원하면 컴포넌트는 그 범위가 AvailableByteCount가 서술하는 연속 접두부 안에 있거나 RangeRequests 스케줄러를 통해 이미 완료된 범위 안에 있을 때 예스라고 답합니다. OnDataAvailable 핸들러가 그다음 최종 결정권을 갖는데, 희소 캐시가 그 둘로 서술할 수 없는 범위에 답하는 방법이 바로 이것입니다. CheckDocumentAvailability는 세 TPdfDataAvailability 값(pdaAvailable, pdaNotAvailable, pdaError) 중 하나를 반환하고 PDFium이 요청한 바이트 범위를 정렬·병합된 TPdfDownloadRanges 배열로 건네줍니다. 그 범위는 여러분이 보는 시점에 이미 스케줄러에 rrpImmediate 우선순위로 큐에 들어가 있으므로, 힌트 배열은 로깅과 진행 표시용이고 작업 큐는 RangeRequests입니다
// FetchRange는 여러분의 전송 계층입니다(HTTP Range GET, 소켓, blob 리더):
// Store의 Offset에 Size바이트를 쓰고 도착한 개수를 반환합니다
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;
// 힌트는 이미 큐에 있습니다. 바이트를 먼저 쓰고 완료하세요
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;
그 루프에는 무게 있는 세부 사항이 둘 있습니다. 라운드 상한이 있는 이유는 죽은 링크가 CheckDocumentAvailability로 하여금 매 호출 같은 범위를 요구하게 만들고, 상한 없는 루프는 네트워크 실패를 멈춘 UI로 바꾸기 때문입니다. 순서가 중요한 이유는 스케줄러가 임계 구역으로 자기 상태를 직렬화하지만 백킹 스토어의 TStream.Position에 대해서는 아무것도 하지 않기 때문입니다. 전송 스레드는 CompleteRequest를 부르기 전에 응답 바이트를 스트림에 써야 합니다. 완료가 공개되는 순간 PDFium이 그 범위를 읽을 수 있기 때문입니다. 동시에 쓰는 자들은 positioned I/O나 자체 락이 필요합니다
AvailableByteCount는 왜 뒤로 가기를 거부할까?
AvailableByteCount는 커지기만 합니다. 더 작은 값을 할당하면 "Available byte count cannot move backwards" 메시지의 EPdfError가 발생하는데, 가용성 콜백이 어떤 범위의 존재를 PDFium에 알린 뒤에는 파서가 이미 그 안에서 객체를 읽고 캐시했을 수 있기 때문입니다. 그 뒤로 바이트를 빼앗으면 PDFium이 쥔 객체의 출처를 가용성 답변이 부인하는 꼴이 됩니다. 같은 세터는 LogicalFileSize보다 큰 값을 거부하고 세션 밖에서는 "No progressive load is active"를 발생시킵니다
마지막 검사가 이미 쥔 바이트의 소속을 정합니다. 이전 방문이 파일의 첫 300 KB를 캐시에 남겨 뒀다면 그 개수를 AInitialAvailableByteCount로 넘기세요. 컴포넌트는 FPDFAvail_Create가 돌기 전에 이를 기록하므로 PDFium의 헤더 첫 참조에 이미 보입니다. 초기 개수 0에서는 PDFium이 헤더를 보기 전까지 Linearization이 plnUnknown을 읽습니다. 정상적인 출발 상태입니다
접두부를 올리면 작업도 취소됩니다. 새로 알려진 바이트와 겹치는 진행 중 요청은 이제 잉여이므로 스케줄러가 버리고 그에 대해 OnCancelRequest를 발화하며, 그 요청의 늦은 CompleteRequest는 False를 돌려줍니다. 순서가 어그러져 차오르는 스토어는 접두부로 자신을 표현하려 하지 말아야 합니다. 범위는 스케줄러로 완료하거나 OnDataAvailable에서 범위별로 답하세요. 그 핸들러 안에서 던져진 예외는 C 콜백 경계를 넘을 수 없으므로 컴포넌트가 잡아 그 범위를 없는 것으로 보고하고, PDFium은 다음 검사에서 그냥 다시 묻습니다
부분 다운로드된 PDF는 실제로 언제 열릴까?
파일 전체가 도착하기 전에 열리는 것은 선형화된 PDF뿐입니다. OpenProgressiveDocument는 Linearization 프로퍼티(plnUnknown, plnNotLinearized, plnLinearized)를 검사해 로더를 고릅니다. 선형화된 파일은 첫 페이지 섹션과 힌트 테이블이 존재하는 순간 FPDFAvail_GetDocument로 열립니다. 선형화되지 않은 파일은 같은 파일 접근 레코드로 FPDF_LoadCustomDocument를 통과하고, 그런 파일에 대해 PDFium은 모든 바이트가 있어야만 문서를 가용하다고 보고합니다. 그 라우팅이 서두의 0페이지 핸들이 여러분 뷰어에 들어오지 않게 지키는 장치입니다
그래서 서버의 파일이 첫 페이지가 얼마나 빨리 보이는지를 결정합니다. 첫 그리기까지의 시간이 중요하고 배포 쪽을 통제한다면 그곳에서 파일을 선형화하세요. TPdf.SaveAsLinearized는 컴포넌트 자체로 부록 F 배치를 기록하고, Fast Web View와 힌트 테이블 워크스루가 그 배치의 내용을 다룹니다. 통제하지 못하는 파일이라도 선형화되지 않은 PDF는 같은 루프로 적재됩니다. 일찍 대신 100퍼센트에 pdaAvailable에 닿을 뿐입니다
LoadAvailablePage는 1 기반 페이지 번호를 받아 PDFium이 기대하는 순서를 지킵니다. 첫 페이지 검사 전에 FPDFAvail_IsFormAvail을 감싼 CheckFormAvailability를 돌리고, 그다음에야 FPDFAvail_IsPageAvail을 부릅니다. pfaNotPresent 결과는 AcroForm 없는 문서의 정상적인 답이고 아무것도 막지 않습니다. 페이지가 준비되면 LoadAvailablePage는 그것을 활성 페이지로 만드므로, 뷰어는 나중 페이지들이 전송 중인 동안에도 선형화된 브로슈어의 1페이지를 렌더링할 수 있습니다. 페이지 대기는 첫 목록과 같은 모양입니다. LoadAvailablePage를 부르고, pdaNotAvailable에서 RangeRequests를 배출하고, pdaAvailable이나 pdaError에서 멈추고, 라운드 상한을 유지합니다. FirstAvailablePageNumber는 선형화 딕셔너리가 첫 페이지로 지목한 페이지를 PDFium의 0 기반 인덱스에서 이미 변환해 보고합니다. 선형화되지 않은 파일의 모든 페이지는 곧장 pdaAvailable을 보고하는데, 문서는 파일이 완전해야만 열렸으니까요
범위 스케줄러의 재시도, 부분 읽기, 우선순위
FPDFAvail_* API 자체는 네트워크를 모릅니다. 파서가 지금 필요한 바이트를 말하고 나중에 다시 묻을 뿐이며, 요청이나 재시도, 취소의 개념이 없습니다. TPdfRangeRequestScheduler가 그것들을 공급하고 그 네 규칙이 전송 계층 작성 방식을 빚습니다
- 짧은 응답은 진행으로 쳐 줍니다. 요청보다 적은 바이트의
CompleteRequest(Request, BytesReceived)는 접두부를 공개하고 나머지를 큐에 넣습니다. 짧은 응답은 실패한 시도로도 세어 나머지는MaxRetryCount의 구속을 받고 소진되면 버려집니다. 0바이트는 그냥 실패한 시도입니다 MaxRetryCount기본값은 2라 한 범위가 총 세 번 시도됩니다.FailRequest는 범위를 다시 큐에 넣으면True, 버려지면False를 반환하고Statistics.AbandonedRequestCount가 포기한 개수를 셉니다MaxRequestSize는 큰 범위를 dequeue 시점에 청크로 쪼개고,MergeGap은 대기 중인 두 범위가 작은 미지 간격을 건너 병합하게 하지만 이미 완료되었거나 진행 중인 바이트를 건너서는 절대 병합하지 않습니다CheckDocumentAvailability와LoadAvailablePage의 힌트는rrpImmediate로 도착합니다. 직접CheckFormAvailability호출의 폼 힌트는rrpNormal로 오고,LoadAvailablePage가 그 검사를 스스로 돌렸는데 폼 데이터가 없으면 힌트는rrpImmediate로 큐에 들어갑니다.TryDequeue는 언제나 최고 우선순위를 먼저, 같은 우선순위 안에서는 가장 낮은 오프셋을 먼저 내줍니다
우선순위 규칙이 보상하는 순간은 프리페치입니다. 문서가 열리자마자 파일 전체를 rrpBackground로 큐에 넣으면 스케줄러가 이미 완료되었거나 진행 중인 것을 빼고 없는 바이트만 회선에 올립니다. 그러다 사용자가 40페이지로 뛰고 그 페이지의 힌트가 다운로드 중인 백그라운드 청크와 겹치면, 스케줄러는 백그라운드 요청을 끌어내 그에 대한 OnCancelRequest를 발화하고, 겹치지 않는 꼬리들은 재시도로 세지 않고 백그라운드 우선순위로 되돌려 놓으며, 겹침은 새 immediate 작업으로 큐에 넣습니다. 점프가 회선을 이깁니다. 그게 없으면 페이지 요청은 자기가 관심 없는 256 KB 청크 뒤에서 기다립니다
procedure TDownloadForm.QueueRestOfFile;
var
Whole: TPdfDownloadRanges;
begin
FPdf.RangeRequests.MaxRequestSize := 256 * 1024; // 청크 크기는 여러분이 정합니다
SetLength(Whole, 1);
Whole[0].Offset := 0;
Whole[0].Size := FPdf.LogicalFileSize;
FPdf.RangeRequests.EnqueueHints(Whole, rrpBackground);
end;
// HTTP Range 응답 하나가 끝났을 때 워커 스레드에서 호출됩니다.
// WriteAt은 백킹 스토어에 대한 자체 위치 지정 쓰기입니다
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); // 바이트 먼저
FPdf.RangeRequests.CompleteRequest(Request, Length(Body));
end
else if not FPdf.RangeRequests.FailRequest(Request) then
TThread.Queue(nil, ShowRangeGaveUp); // 버려졌거나 취소된 세션에서 온 것
end;
CompleteRequest와 FailRequest는 워커 스레드에서 불러도 안전합니다. 스케줄러가 자기 락을 잡습니다. 대체됐거나 취소된 세션 소속인 요청은 아무것도 건드리지 않고 False로 돌아오므로, 워커는 자기 범위가 왜 낡았는지 알 필요가 없습니다
CancelProgressiveLoad은 무엇을 어떤 순서로 반납할까?
CancelProgressiveLoad는 네 단계로, 언제나 같은 순서로 세션을 해체합니다. 범위 스케줄러 취소, 문서 닫기, FPDFAvail_Destroy로 가용성 핸들 파괴, 그다음 콜백 레코드와 스트림 어댑터 반납입니다. 스케줄러를 먼저 취소하면 세대 카운터가 전진하고 대기와 진행 중인 모든 요청이 버려지며 진행 중인 것들마다 OnCancelRequest가 발화합니다. 그 뒤에 도착하는 전송 완료는 옛 세대를 달고 오고 CompleteRequest는 False를 반환합니다. 문서가 가용성 핸들과 스트림 어댑터보다 먼저 닫히는 이유는 PDFium이 문서를 닫는 동안에도 파일 접근 공급자를 통해 읽을 수 있기 때문입니다
procedure TDownloadForm.FormCreate(Sender: TObject);
begin
FPdf := TPdfProgressiveDocument.Create(nil);
// 스케줄러는 FPdf와 수명을 같이하므로 한 번만 물립니다
FPdf.RangeRequests.OnCancelRequest := RangeCancelled;
end;
procedure TDownloadForm.RangeCancelled(Sender: TObject; RequestId: UInt64;
Attempt: Cardinal);
begin
FTransport.Abort(RequestId); // 여러분의 코드: 그 소켓이나 요청을 닫습니다
end;
procedure TDownloadForm.CancelButtonClick(Sender: TObject);
begin
FPdf.CancelProgressiveLoad;
// ProgressiveLoading = False, Active = False, AvailableByteCount = 0
end;
이 메서드는 멱등하고 세 상황의 유일한 정리 경로로 쓰입니다. 구성 도중 실패한 BeginProgressiveLoad, 명시적 사용자 취소, 소멸자입니다. BeginProgressiveLoad도 이를 부르므로, 이전 세션이 열기까지 못 갔고만 하면 같은 객체를 새 URL로 다시 시작해도 됩니다. OpenProgressiveDocument가 성공한 뒤에는 객체가 살아 있고 BeginProgressiveLoad는 익숙한 "Cannot perform this operation on an active" 오류를 발생시키니, 먼저 CancelProgressiveLoad를 부르세요. OnCancelRequest는 여러분 소켓이 닫히는 유일한 장소이기도 합니다. 스케줄러는 소켓이 뭔지 모르니까요. 그 안에서 던져진 예외는 요청별로 삼켜지므로 하나의 실패한 abort가 나머지를 막지 못합니다
스토어에 쓰는 자가 소유자를 정합니다. 워커 스레드가 백킹 스트림에 쓴다면 AOwnsStream = False로 넘기고 워커가 멈춘 뒤 직접 스트림을 해제하세요. 소유권을 넘기면 취소가 스트림을 해제하는데 이미 진행 중인 쓰기가 아직 가는 중일 수 있습니다. 호출자 외의 스레드가 스토어를 만지는 한 소유권을 지키세요. AOwnsStream = True는 첫 목록 같은 완전 동기 전송에만 맞습니다
파일 전체를 기다리는 기능들
어떤 기능들은 파싱된 문서가 아니라 원본 파일 바이트를 필요로 하며 불완전한 진행 소스를 곧장 거부합니다. ReadXmpPacket은 "PDF/A metadata is unavailable until progressive loading completes"를 발생시킵니다. ValidatePades는 SourceStatus가 pvssIncomplete인 결과를 반환하고, ValidatePdfMac은 완전한 소스를 달라는 메시지와 함께 미지원을 보고합니다. BeginIncrementalSave도 실패하는데, 증분 업데이트는 적재된 그 바이트들에 이어 붙어야 하기 때문입니다
이들 모두 뒤의 완전성 검사는 AvailableByteCount가 LogicalFileSize에 닿는 것입니다. 따라서 스케줄러로 전부 전달한 전송이라도 모든 바이트를 쥔 채 소스가 불완전하다는 말을 들을 수 있는데, 연속 접두부가 움직이지 않았기 때문입니다. 스케줄러가 전체 커버리지를 확인하면 접두부를 공개하세요:
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); // 자체 UI
end;
이 모든 것 시작 전에 크기 한도 하나가 적용됩니다. Windows의 FPDF_FILEACCESS는 파일 길이를 32비트 필드에 담으므로, BeginProgressiveLoad는 4 GiB를 넘는 논리 크기를 PDFium이 잘린 길이를 파싱하게 두는 대신 EPdfError로 거부합니다
스트림 어댑터로 완전한 로컬 파일을 주문형 적재하는 것은 PDFium으로 큰 PDF를 주문형 스트리밍하기를, 더 큰 버퍼 안에 앉아 있는 PDF는 임베디드 PDF의 바이트 범위 적재를 보세요. 이미 도착한 페이지의 느린 렌더링을 멈추는 것은 다른 메커니즘으로 취소 가능한 점진 페이지 렌더링에서 다룹니다. TPdfProgressiveDocument와 그 범위 스케줄러, SaveAsLinearized는 Delphi와 C++Builder용 PDFium Component의 일부입니다