Copper PDF ドキュメント

.NETドライバはC#で書かれており、C#, VB.NETなどから利用することができます。ストリーム（System.IO.Stream）からストリームへの変換に対応しており、巨大な文書も容易に変換することができます。

また、ASP.NETで利用する際は、ASP.NETからの出力をキャプチャしながら、変換結果を送り出すことができます。これにより、PDFの出力も普通のウェブページと同様にASP.NETにより作ることができます。

ドライバの準備

.NET用ドライバはGitHubの https://github.com/zamasoftnet/cti.net で公開されており、NuGetパッケージ（Zamasoft.CTI）として提供されています。 .NET Standard 2.0以降（.NET Framework 4.6.1以降、.NET Core 2.0以降、.NET 5～9）に対応しています。

dotnet add package Zamasoft.CTI

またはプロジェクトファイルに直接追加することもできます（バージョンはNuGetのページで最新版を確認してください）。

NuGetを使わない場合は、GitHubのリリースページからソースアーカイブをダウンロードし、 CTI/CTI.sln をVisual Studioまたは dotnet build でビルドすることもできます。

ドライバの窓口となるクラスはCTI.DriverManagerです。例えばlocalhostの8099番ポートで起動しているcopperdに、ユーザーID"user"、パスワード"kappa"で接続するには、以下のようにします。

using System;
using CTI;
...

using (Session session = DriverManager.getSession(new Uri("ctip://localhost:8099/"), "user", "kappa"))
{
//各種操作
...
}
...

タイムアウトの設定

.NET版ドライバ2.0.1以降から、一定時間通信がない状態で自動的に通信を切断するタイムアウトに対応しています。

以下のようにURLパラメータで、timeoutをミリ秒単位で指定できます。

APIの概要

サーバーへの接続・認証

サーバー情報の取得

メッセージハンドラ・プログレスリスナの設定

出力先の設定

プロパティの設定

ソースリゾルバの設定

リソースの送信

本体の送信・変換

複数の結果の結合

処理の中断・リセット・通信の終了

サンプル

次の例は、サーバー側からネットワーク上のウェブページアクセスしてPDFに変換します。


    /// サーバー側からインターネット上の文書にアクセスして変換します。
    /// 
    class ServerResource
    {
        static void Main(string[] args)
        {
            using (Session session = DriverManager.getSession(new Uri("ctip://localhost:8099/"), "user", "kappa"))
            {
                // test.pdfに結果を出力する
                Utils.SetResultFile(session, "test.pdf");

                // https://copper-pdf.com/以下にあるリソースへのアクセスを許可する
                session.Property("input.include", "https://copper-pdf.com/**");

                // ウェブページを変換
                session.Transcode("https://copper-pdf.com/");
            }
        }
    }
}
]]>


''' サーバー側からインターネット上の文書にアクセスして変換します。
''' 
Module ServerResource

    Sub Main()
        Using session As Session = DriverManager.getSession(New Uri("ctip://localhost:8099/"), "user", "kappa")
            ' test.pdfに結果を出力する
            Utils.SetResultFile(session, "test.pdf")

            ' https://copper-pdf.com/以下にあるリソースへのアクセスを許可する
            session.Property("input.include", "https://copper-pdf.com/**")

            ' ウェブページを変換
            session.Transcode("https://copper-pdf.com/")
        End Using
    End Sub

End Module
]]>

.NET版ドライバの特徴は、ASP.NETをPDF出力のためのテンプレートとして利用できるようになることです。前準備として、以下のクラスを用意しておきます。

ASP.NETにより生成したPDFを直接ブラウザに送る場合、HTTPレスポンスのContent-Typeヘッダに"application/pdf"を設定し、 Content-LengthヘッダにPDFファイルのサイズを設定する必要があります。上記のContentLengthSenderは、そのためのもので、親クラスのBuilderからPDFのMIME型(Info.MimeType)、ファイルサイズ(length)を得ています。

ASP.NETで、他のページをPDFのテンプレートとして利用するには、以下のようにします。

上記の例ではPDFTemplate.aspxを実行した結果をCopper PDFに送り、変換した結果をブラウザに送信しています。 PDFTemplate.aspxは普通のASP.NETページなので、例えばPDF上にカレンダーを印刷するためにカレンダーコントロールを利用するといったことができます。

他のサンプルはドライバのCTIディレクトリに収められています。

プログラミングのポイント

Utilsの利用

結果の出力先、リソースの送信、ファイルの変換等のよく使われる操作が、 Zammasoft.CTI.Utils のstatic(Shared)メソッドにまとめられています。

例えば、事前に関連するCSSを送信してHTMLファイルを変換する処理は、次のように簡単に書けます。

...
Utils.SendResourceFile(session, "test.css", "text/css", "UTF-8");
Utils.TranscodeFile(session, "test.html", "text/html", "UTF-8");
...

...
Utils.SendResourceFile(session, "test.css", "text/css", "UTF-8")
Utils.TranscodeFile(session, "test.html", "text/html", "UTF-8")
...

繰り返し処理

出力先を変え、Transcodeメソッドを繰り返し呼び出すことで、同じセッションで何度もドキュメントを変換することができます。送信済みのリソース、設定済みのプロパティは同じセッションで維持されます。同じセッションのまま初期状態に戻すには Reset を呼び出してください。

出力先(Results)の設定

出力先が単一のファイルやストリームの場合は、Utilsの SetResultFile か、 SetResultStream を使ってください。これらのメソッドは内部的にZamasoft.CTI.Result.SingleResultクラスを使用しています。

Zamasoft.CTI.Result.Resultsインターフェースは、複数の出力結果を受け取るためのインターフェースです。 SessionのResultsプロパティにセットします。

複数の結果をファイルとして出力する場合は、 Zamasoft.CTI.Result.FileResults を使用してください。このクラスは、指定したディレクトリに、1から開始する連番の前後に指定した文字列をくっつけたファイル名で結果を出力します。次の例では変換結果の各ページを、resultsディレクトリ内に"image[通し番号].jpeg"という名前で別々のJPEG画像として出力します。

...
session.Property("output.type", "image/jpeg");
session.Results = new FileResults("results/image", ".jpeg"));
...

...
session.Property("output.type", "image/jpeg")
session.Results = New FileResults("results/image", ".jpeg"))
...

さらに複雑な処理が必要な場合は、Resultsインターフェースを実装するクラスを用意する必要があります。 Resultsインターフェースを実装したクラスでは、 Zamasoft.CTI.Result.Builder を使ってストリームやファイルにデータを出力してください。

サーバーから要求されたリソースの送信(SourceResolver)

SessionのSourceResolverプロパティにソースリゾルバ(Zamasoft.CTI.Source.SourceResolver) を設定すると、サーバーから要求されたリソースを都度送信できるようになります。

次の例のように、SourceResolverを実装すると、クライアント側のファイル、あるいはクライアント側からウェブにアクセスして取得したデータをサーバーに送ることができます。

    class MySourceResolver : SourceResolver
    {
        public Stream Resolve(string _uri, ref SourceInfo info)
        {
            Uri uri = new Uri(_uri);
            if (uri.IsFile)
            {
                string file = uri.AbsolutePath;
                if (!File.Exists(file))
                {
                    return null;
                }
                info = new SourceInfo(_uri);
                return new FileStream(file, FileMode.Open, FileAccess.Read);
            }
            else if (uri.Scheme == "http")
            {
                WebRequest req = WebRequest.Create(uri);
                WebResponse resp = req.GetResponse();
                info = new SourceInfo(_uri);
                info.MimeType = resp.Headers.Get("Content-Type");
                return resp.GetResponseStream();
            }
            return null;
        }
    }

    Class MySourceResolver
        Implements SourceResolver

        Function Resolve(_uri As String, ByRef info As SourceInfo) As Stream Implements SourceResolver.Resolve
            Dim uri As New Uri(_uri)
            If uri.IsFile Then
                Dim file As String = uri.AbsolutePath
                If Not System.IO.File.Exists(file) Then
                    Return Nothing
                End If
                info = New SourceInfo(_uri)
                Return New FileStream(file, FileMode.Open, FileAccess.Read)
            ElseIf uri.Scheme = "http" Then
                Dim req As WebRequest = WebRequest.Create(uri)
                Dim resp As WebResponse = req.GetResponse()
                info = New SourceInfo(_uri)
                info.MimeType = resp.Headers.Get("Content-Type")
                Return resp.GetResponseStream()
            End If

            Return Nothing
        End Function
    End Class

SourceInfo

Sessionの Resource, Transcode メソッド等では、データの仮想URI、MIME型、キャラクタ・エンコーディング、予測されるデータサイズ。 SourceInfo クラスにより渡します。

複数の結果の結合

複数の結果を結合したものを得るためには、 Continuous プロパティにtrueを設定した後、Transcodeを複数回呼び出し、最後に Join を呼び出してください。

...
session.Continuous = true;
Utils.SendResourceFile(session, "test.css", "text/css", "UTF-8");
Utils.TranscodeFile(session, "test.html", "text/html", "UTF-8");
session.Transcode("https://copper-pdf.com/");
session.Join();
...

...
session.Continuous = true
Utils.SendResourceFile(session, "test.css", "text/css", "UTF-8")
Utils.TranscodeFile(session, "test.html", "text/html", "UTF-8")
session.Transcode("http://copper-pdf.com/")
session.Join()
...

Abortによる中断

SessionのAbort メソッドは文書の変換処理を中断しますが、Transcodeメソッドは処理の間ブロックするため、別スレッドからAbortを呼び出す必要があります。 Abortは引数によって、強制的に中断するモードと、きりのよいところまで処理して、一応利用可能な結果を出力するモードの２つがあります。後者のモードは、例えば大きなPDFファイルを出力中に処理を中断して、途中までの出力結果を見たい場合に有用です。ただし、１ページ目を出力される前に中断してしまった場合など、読み込み可能なデータが出力できないことも起こり得ます。

.NETドライバ

概要

ドライバの準備

タイムアウトの設定

APIの概要

サーバーへの接続・認証

サーバー情報の取得

メッセージハンドラ・プログレスリスナの設定

出力先の設定

プロパティの設定

ソースリゾルバの設定

リソースの送信

本体の送信・変換

複数の結果の結合

処理の中断・リセット・通信の終了

サンプル

プログラミングのポイント

Utilsの利用

繰り返し処理

出力先(Results)の設定

サーバーから要求されたリソースの送信(SourceResolver)

SourceInfo

複数の結果の結合

Abortによる中断

ソースコード