Pro الإصدارالاستقرار: تجريبي

معاينة C2PA — مرجع متعمّق

لمحة سريعة

هذه الصفحة هي المرجع على مستوى العقد لسطح معاينة ⁨C2PA⁩ (اعتمادات المحتوى) في ⁨NextPDF Pro⁩. وهي تغطّي خمسة رموز عامة في NextPDF\Pro\Compliance\C2pa: واجهة ⁨SPI⁩ الخاصة بـ C2paManifestEmbedder، وكائن القيمة ManifestStore، والمُحلّل JumbfBoxParser، وواصف الحالة C2paCapabilityStatus، والمُضمِّن المُقيَّد Experimental\ExperimentalC2paEmbedder. كما توثّق بوابة Feature::PREVIEW_C2PA_DRAFT ومتغيّر بيئتها NEXTPDF_FEATURE_PREVIEW_C2PA_DRAFT.

هذا السطح تجريبي ومقسوم إلى طبقتين. الوصلة المستقرة — ManifestStore وC2paManifestEmbedder وJumbfBoxParser — متاحة دائمًا وتحمل بايتات ⁨Manifest Store⁩ في الاتجاهين. أما توليد بيان المسودّة فيوجد حصريًا في ExperimentalC2paEmbedder وهو مُعطَّل افتراضيًا. لم يُنهِ فريق العمل ملف تعريف ⁨C2PA-PDF⁩ بعد؛ والتنسيق السلكي المُولَّد مُثبَّت على التزام مسودّة. لا يُقدَّم أي ادعاء بالمطابقة، ولا يوجد مسار للتحقّق، ولا يمكن لتفعيل علامة المعاينة أن يُنشئ أيًّا منهما. تجد العرض المُوجَّه نحو المهام في صفحة القدرة.

التوفّر والترخيص

تُشحَن هذه القدرة ضمن ⁨NextPDF⁩ Pro (nextpdf/pro) وتُفعَّل بمظروف ترخيص من فئة ⁨Pro⁩. أي نشر لا يمتلك هذا الاستحقاق لا يُحمّل أصناف هذه القدرة. قارن الإصدارات واحصل على ترخيص.

يُفعّل الترخيص سطح مطابقة ⁨Pro⁩ ككل. ويبقى سطح ⁨C2PA⁩ داخله معاينةً بغضّ النظر عن فئة الترخيص. ويتطلّب توليد المسودّة إضافةً إلى ذلك بوابة العملية المُوثَّقة هنا؛ ولا يُفعّله ترخيص ⁨Pro⁩ وحده أبدًا.

سطح واجهة برمجة التطبيقات العامة

الرمز	المعاملات	السلوك الافتراضي	القيمة المُعادة	يرمي أو يفشل بـ	ملاحظات
`C2paManifestEmbedder`	—	واجهة SPI للتضمين/الاستخراج بالبايتات فقط؛ دون إدخال/إخراج؛ دون توليد ادعاءات	—	—	واجهة وصلة مُجمَّدة ومحايدة تجاه المورّدين.
`C2paManifestEmbedder::embed()`	`string $pdfBytes`، `ManifestStore $store`	يُضمِّن `$store->toBytes()` في الموضع المُعلَن في الملف التعريفي؛ وقد يمرّ Store الفارغ ذهابًا وإيابًا كعملية لا أثر لها	`string` بايتات PDF جديدة	`C2paException` عند أي فشل في التضمين (Store مفرط الحجم، PDF غير صالح، تصادم في موضع الملف التعريفي)	لا تُعدّل التطبيقات بايتات الإدخال ولا تحتفظ بها أبدًا.
`C2paManifestEmbedder::extract()`	`string $pdfBytes`	مسبار كشف زهيد التكلفة؛ حالة عدم وجود Store لا تُخصّص شيئًا يُذكر	`?ManifestStore` (`null` عند عدم العثور)	صنف فرعي من `C2paException` عندما يكون Store موجودًا لكنه ينتهك ثابتًا من ثوابت التحصين	أي Store غير فارغ (non-null) يكون قد اجتاز بالفعل تحصين `JumbfBoxParser`.
`ManifestStore::fromBoxes()`	`array $boxes` (`list<JumbfBox>`)	يُغلّف قائمة صناديق مُرتَّبة تحقّق منها المُحلّل	`self`	لا يرمي بذاته؛ يفرض إنشاء `JumbfBox` يدويًا التحصين نفسه	المُنشئ خاص؛ وترتيب الصناديق حمّال معنى لمساواة الذهاب والإياب.
`ManifestStore::empty()`	لا شيء	Store بلا صناديق جذرية	`self`	لا يرمي	ناتج `toBytes()` لـ Store فارغ هو السلسلة الفارغة.
`ManifestStore::isEmpty()`	لا شيء	يختبر خلوّه من الصناديق الجذرية	`bool`	لا يرمي	—
`ManifestStore::toBytes()`	لا شيء	يُسلسل تسلسلات الصناديق الجذرية	`string`	لا يرمي	هذا التسلسل من البايتات هو ما يكتبه المُضمِّن.
`ManifestStore::size()`	لا شيء	طول `toBytes()` بالبايتات	`int` (>= 0)	لا يرمي	—
`JumbfBoxParser::__construct()`	ثلاثة تجاوزات اختيارية للحدود	حدود الإنتاج: 64 MiB لكل صندوق، 128 MiB إجمالًا، 4096 عنصرًا فرعيًا لكل superbox	`JumbfBoxParser`	لا يرمي	حدّ العمق مثبَّت عند `MAX_DEPTH` (8) وغير قابل للضبط عبر المُنشئ.
`JumbfBoxParser::parse()`	`string $bytes`	يتحقّق من الصناديق الجذرية ويُجسّدها؛ الإدخال الفارغ يُنتج `[]`	`list<JumbfBox>`	`JumbfBombException`، `JumbfCycleDetectedException`، `JumbfDepthExceededException`، `MalformedJumbfException`	عديم الحالة؛ لا يُعيد رسمًا بيانيًا جزئيًا أبدًا؛ والاستدعاءات المتزامنة على مثيل واحد آمنة.
`C2paCapabilityStatus::__construct()`	ستة حقول readonly مُسمّاة	يبني مثيل واصف عشوائي	`C2paCapabilityStatus`	لا يرمي	`current()` هو المُنشئ المعياري.
`C2paCapabilityStatus::current()`	لا شيء	يقرأ البوابة مباشرةً؛ ويُثبّت قيم الادعاء المنطقية في الشيفرة	`C2paCapabilityStatus`	لا يرمي	`generallyAvailable` و`conformanceClaimed` دائمًا `false`.
`C2paCapabilityStatus::summary()`	لا شيء	نص حالة من سطر واحد	`string`	لا يرمي	مُصاغ بحيث لا يحمل أي ادعاء بالإتاحة العامة (GA) أو المطابقة.
`Feature`	تعداد مدعوم بسلسلة، حالة واحدة	حالة واحدة `PREVIEW_C2PA_DRAFT`؛ وثابت `ENV_PREVIEW_C2PA_DRAFT`	حالة تعداد	لا شيء عند الوصول إلى الحالة	بوابة استقرار محدودة النطاق؛ متمايزة عن استحقاق الترخيص.
`Feature::isEnabled()`	لا شيء	يقرأ `getenv()` مباشرةً؛ مقارنة صارمة مقابل السلسلة `1`	`bool`	لا يرمي	المتغيّر الغائب أو أي قيمة أخرى، بما في ذلك `0` و`true` و`yes`، يعني الإيقاف.
`ExperimentalC2paEmbedder::__construct()`	لا شيء	فحص بوابة يفشل مُغلقًا وقت الإنشاء	`ExperimentalC2paEmbedder`	`LogicException` عندما تكون `Feature::PREVIEW_C2PA_DRAFT` مُعطَّلة	لا يوجد أي احتياط صامت.
`ExperimentalC2paEmbedder::buildManifestStore()`	`string $sourceBytes`، `string $producer` (غير فارغ)	يبني Store بهيئة مسودّة يربط `$sourceBytes` عبر SHA-256	`ManifestStore`	`\JsonException` عند فشل ترميز الحمولة؛ وأصناف فرعية من `C2paException` من إنشاء الصناديق	يُغفل صندوق توقيع الادعاء `c2cs`؛ والمُخرَج غير موقَّع بحكم بنيته.

interface C2paManifestEmbedder

public function embed(string $pdfBytes, ManifestStore $store): string;
public function extract(string $pdfBytes): ?ManifestStore;

final readonly class ManifestStore

public static function fromBoxes(array $boxes): self
public static function empty(): self
public function isEmpty(): bool
public function toBytes(): string
public function size(): int

final class JumbfBoxParser

public const int MAX_DEPTH = 8;
public const int MAX_PER_BOX_BYTES = 64 * 1024 * 1024;
public const int MAX_TOTAL_BYTES = 128 * 1024 * 1024;
public const int MAX_CHILDREN_PER_SUPERBOX = 4096;
public const array SUPERBOX_TBOXES = ['jumb', 'c2pa', 'c2ma', 'c2as', 'c2cl', 'c2cs', 'c2vc'];

public function __construct(
    private readonly int $maxPerBoxBytes = self::MAX_PER_BOX_BYTES,
    private readonly int $maxTotalBytes = self::MAX_TOTAL_BYTES,
    private readonly int $maxChildrenPerSuperbox = self::MAX_CHILDREN_PER_SUPERBOX,
)

public function parse(string $bytes): array

final readonly class C2paCapabilityStatus

public const string MATURITY_PREVIEW_DRAFT = 'preview-draft';

public function __construct(
    public bool $previewEnabled,
    public bool $generallyAvailable,
    public bool $conformanceClaimed,
    public string $maturity,
    public string $specPin,
    public string $envGate,
)

public static function current(): self
public function summary(): string

enum Feature: string

case PREVIEW_C2PA_DRAFT = 'preview_c2pa_draft';

public const string ENV_PREVIEW_C2PA_DRAFT = 'NEXTPDF_FEATURE_PREVIEW_C2PA_DRAFT';

public function isEnabled(): bool

final class ExperimentalC2paEmbedder

public const string SPEC_PIN_SHA = '4e2afed8f3ace20d41317e2e386c9340d2959d55';
public const string SPEC_PIN_DATE = '2026-04-26';

public function __construct()

public function buildManifestStore(string $sourceBytes, string $producer): ManifestStore

عقد السلوك

انقسام إلى طبقتين. الوصلة المستقرة (ManifestStore وC2paManifestEmbedder وJumbfBoxParser) متاحة دائمًا. ولا يوجد توليد المسودّة إلا في NextPDF\Pro\Compliance\C2pa\Experimental\ExperimentalC2paEmbedder خلف البوابة المُعطَّلة افتراضيًا. لا يتطلّب الاستخراج ونقل البايتات البوابةَ أبدًا؛ بينما يتطلّبها التوليد دائمًا.
ثوابت الوصلة. عقد C2paManifestEmbedder قائم على البايتات فقط: لا تعبر أي كائنات ⁨PDF⁩ في الذاكرة الوصلةَ، ولا تُجري التطبيقات أي إدخال/إخراج شبكي أو نظام ملفات، ولا تُجمّع الوصلة ادعاءات بذاتها أبدًا. تُعيد extract() القيمة null للإشارة إلى الغياب؛ ولا ترمي أبدًا بسبب الغياب.
دلالات ⁨Store⁩. إن ManifestStore قائمة مُرتَّبة غير قابلة للتغيير من مثيلات JumbfBox الجذرية، وفق نموذج ⁨Manifest Store⁩ في ⁨C2PA 2.1 §11.1.1⁩: حاوية ⁨JUMBF⁩ واحدة تُجمِّع بيانًا واحدًا أو أكثر، ويمكن معالجتها عبر ⁨URI⁩. وهي لا تكشف أي وسائل وصول على مستوى الادعاء. ويُحفظ ترتيب الصناديق وهو حمّال معنى لمساواة الذهاب والإياب.
حدود التحصين. يرفض JumbfBoxParser دون قيد وشرط أي إدخال يتجاوز أي حدّ: حجم لكل صندوق يفوق ⁨64 MiB⁩، أو مخزن تراكمي يفوق ⁨128 MiB⁩، أو تداخل أعمق من 8 مستويات، أو أكثر من 4096 عنصرًا فرعيًا في ⁨superbox⁩ واحد. لا توجد أي علامة سياسة تُعطّل هذه الحدود. والحدود الأضيق قابلة للحقن عبر المُنشئ للعمليات المحدودة الذاكرة.
الرفض البنيوي. يرفض المُحلّل أيضًا، بالفشل المُغلق: LBox = 0 (⁨BMFF⁩ حتى نهاية الملف)، وLBox = 1 (⁨XLBox⁩ بطول 64-bit)، وLBox أصغر من ترويسة 8 بايتات، والاقتطاع بعد الإدخال المتبقّي، وبايتات ⁨TBox⁩ خارج ⁨ASCII⁩ القابل للطباعة (⁨0x20–0x7E⁩)، وإعادة الدخول عبر الإزاحة (الدورات)، والتبليط غير الدقيق للعناصر الفرعية لحمولة ⁨superbox⁩. ولا يُعيد أبدًا رسمًا بيانيًا مُنشأً جزئيًا.
توجيه ⁨superbox⁩. تُحلَّل قيم ⁨TBox⁩ الموجودة في SUPERBOX_TBOXES تحليلًا تعاوديًا كتسلسلات فرعية؛ وكل قيمة ⁨TBox⁩ أخرى هي ورقة بحمولة معتمة. ويُعامَل cbor عمدًا كورقة من أجل سلامة المُحلّل؛ وتُعيد الطبقات الأعلى تحليل حمولته عند الحاجة.
بوابة العملية. Feature::PREVIEW_C2PA_DRAFT مُعطَّلة افتراضيًا. تُعيد isEnabled() القيمة true فقط عندما يساوي NEXTPDF_FEATURE_PREVIEW_C2PA_DRAFT السلسلة 1 تمامًا. والقراءة مباشرة في كل استدعاء؛ ولا شيء يُحفظ في الذاكرة المؤقتة.
إنشاء يفشل مُغلقًا. يرمي new ExperimentalC2paEmbedder() استثناء LogicException عندما تكون البوابة مُعطَّلة. وتُسمّي الرسالة العلامة، ومتغيّر البيئة، وقيمة ⁨SHA⁩ المسودّة المُثبَّتة وتاريخها. ولا يمكن لأي مُستدعٍ أن يبلغ توليد المسودّة عرضًا.
هيئة التوليد. تُصدر buildManifestStore() ⁨superbox⁩ من نوع c2pa يحتوي بيان c2ma واحدًا، يضمّ مخزن ادعاءات c2as (ادعاء c2pa.hash.data واحد) وادعاء c2cl. ويسجّل الادعاء تأكيد تجزئة ⁨SHA-256⁩ على $sourceBytes؛ ولأن صندوق توقيع الادعاء c2cs مُغفَل والمُخرَج غير موقَّع، فإن هذا ليس ربطًا صلبًا في ⁨C2PA⁩ ولا حكمًا على المصدرية — بل يتّبع فحسب الهيئة البنيوية التي يصفها ⁨§9.1⁩. وتحمل حمولات صناديق الوصف مُعرِّف نوع ⁨UUID⁩، ومفاتيح تبديل 0x03، وتسمية ⁨UTF-8⁩ منتهية بصفر، وفق ⁨C2PA 2.1 §11.1.4.1.1–11.1.4.1.2⁩.
لا توقيع ادعاء. صندوق c2cs — الذي هو، وفق ⁨C2PA 2.1 §11.1.4.4⁩، صندوق محتوى ⁨CBOR⁩ واحد مُعنون c2pa.signature — مُغفَل عمدًا من ⁨Store⁩ المُولَّد. والمُخرَج غير موقَّع بحكم بنيته. وهذه هي منطقة الملف التعريفي المُقدَّر أنها الأكثر عرضةً للانحراف قبل تجميد فريق العمل.
تثبيت المسودّة، دون ضمان توافق خلفي. التنسيق السلكي المُولَّد مُثبَّت على SPEC_PIN_SHA (4e2afed8… بتاريخ 2026-04-26) من c2pa-org/specifications. وقد يتغيّر دون إشعار ولا يحمل أي ضمان توافق خلفي.
ثابت الصدق. يُثبّت C2paCapabilityStatus::current() قيمتي generallyAvailable وconformanceClaimed في الشيفرة على false. ولا تُقلّب أي علامة إعداد أو بيئة أيًّا من هاتين القيمتين المنطقيتين. ويعكس previewEnabled وحده البوابةَ؛ وmaturity هو الرمز غير المُدَّعِي preview-draft.

الحالات الحدّية وأنماط الفشل

ضبط متغيّر البوابة على 0 أو true أو yes أو on أو سلسلة فارغة يُبقي البوابة مُعطَّلة. والسلسلة 1 بالضبط وحدها تُفعّلها.
تأخذ تغييرات putenv() مفعولها في استدعاء isEnabled() التالي لأن القراءة مباشرة. والبوابة المُبدَّلة أثناء العملية تُلاحَظ فورًا.
تُميّز extract() بين نتيجتين: null حين لا يوجد أي ⁨Store⁩ (زهيدة وخالية من الاستثناءات)، وصنف فرعي مرميّ من C2paException حين يوجد ⁨Store⁩ لكنه عدائي أو مُشوَّه. الغياب ليس خطأً أبدًا؛ والوجود مع التشوّه خطأ دائمًا.
يُعيد JumbfBoxParser::parse('') القائمة الفارغة. أما ManifestStore الفارغ لكن الموجود فيمرّ ذهابًا وإيابًا إلى ذاته؛ ولا تُقلّصه الوصلة إلى null.
قد يُعيد تضمين ⁨Store⁩ فارغ الإدخالَ دون تغيير. يسمح عقد الوصلة بهذه العملية عديمة الأثر لكنه لا يفرضها.
تُجري الرسوم البيانية لـ JumbfBox المبنية يدويًا التحصينَ نفسه وقت الإنشاء: فحوص طول ⁨TBox⁩ و⁨ASCII⁩، وحدّ العمق، وثابت عمق العناصر الفرعية، وقاعدة الحصر بين الحمولة أو العناصر الفرعية، وحدّ الحجم لكل صندوق. فالقنبلة المبنية يدويًا تفشل عند الإنشاء لا وقت التضمين.
يحمل كل استثناء من المُحلّل حقولًا مُهيكلة — capKind/observed/cap، وoffset، أو kind — بحيث لا يضطر القياس عن بُعد إلى تحليل سلاسل الرسائل. وترث كل الأصناف الفرعية C2paException (وهو ذاته RuntimeException)، وهو نوع الالتقاط الجامع.
يمنع تعليق التوثيق (⁨docblock⁩) للمُحلّل ابتلاع هذه الاستثناءات بصمت؛ فالمستهلكون إمّا يُظهرونها أو يُعيدون تعيينها عن قصد.
تُرمّز buildManifestStore() حمولات ⁨JSON⁩ باستخدام JSON_THROW_ON_ERROR؛ وسلسلة $producer غير الصالحة كـ ⁨UTF-8⁩ تفشل بـ \JsonException قبل بناء أي صندوق.
نتيجة extract() جيّدة التكوين هي بيان بنيوي فحسب. لا يوجد أي تحقّق من الادعاءات، ولا تحقّق من التواقيع، ولا تقييم للثقة في أي مكان على هذا السطح. فالتعرّف ليس حكمًا على المصدرية.
لا يعالج هذا السطح أي مفتاح توقيع أو شهادة أو بنية ⁨COSE⁩. والعملية التشفيرية الوحيدة هي تجزئة محتوى ⁨SHA-256⁩ داخل مسار التوليد المُقيَّد بالبوابة.

المطابقة

الادعاء	المعيار	البند
تتسلسل البيانات إلى مخزن JUMBF واحد يحمل بيانات متعددة، يمكن معالجته عبر URI.	C2PA 2.1	§11.1.1 (p63.b)
تسميات صناديق الوصف هي UTF-8 منتهية بصفر مع نطاقات مستبعَدة؛ ومفاتيح التبديل معرَّفة لكل صناديق الوصف.	C2PA 2.1	§11.1.4.1.1–11.1.4.1.2 (p63.a)
صندوق توقيع الادعاء مُعنون `c2pa.signature`، ونوعه `c2cs`، ويحمل صندوق محتوى CBOR واحدًا.	C2PA 2.1	§11.1.4.4 (p63.c)
يربط الربط الصلب البيانَ بأصله تعمّيًا ويكشف التعديل — وتأكيد التجزئة غير الموقَّع في المعاينة لا يستوفي هذا الحدّ.	C2PA 2.1	§9.1 (p57)

كل البنود مُعاد صياغتها. ولا يُعيد ⁨NextPDF⁩ إنتاج النص المعياري. لا يمتلك ⁨NextPDF⁩ أي اعتماد ولا يمنح أيًّا منه. والبيانات أعلاه هي بيانات مواءمة بنيوية حول تخطيط الصناديق والتسميات والروابط — وهي ليست نتائج اختبار مطابقة، ولا شهادات طرف ثالث، ولا ادعاء مطابقة لـ ⁨C2PA⁩ أو ⁨ISO⁩. ولم يُنهَ ملف تعريف ⁨C2PA-PDF⁩ بعد؛ والتنسيق السلكي المُولَّد يتتبّع التزام مسودّة مُثبَّتًا. ويُرمّز C2paCapabilityStatus هذا الموقف في الشيفرة: generallyAvailable وconformanceClaimed قيمتهما false في كل إعداد. والمُخرَج من هذا السطح ليس ⁨Content Credential⁩ قابلًا للتحقّق، ولا يوجد أي مسار للتحقّق في ⁨NextPDF⁩.

ملاحظات التطوير

تتبع قواعد صناديق ⁨JUMBF⁩ التي يُطبّقها المُحلّل (⁨LBox⁩ بطول 4 بايتات كبير النهاية، و⁨TBox⁩ بطول 4 بايتات ⁨ASCII⁩، ثم الحمولة؛ وتُداخل ⁨superboxes⁩ الصناديق الفرعية) المعيارَ ⁨ISO 19566-5⁩؛ وهذا المعيار خارج المجموعة المُستشهَد بها، لذا فإن سلوك المُحلّل مُؤسَّس من مصدر المنتج لا من استشهاد بالمواصفة.
أبقِ البوابة مُعطَّلة في الإنتاج. لا يضيف توليد المسودّة أي قدرة دائمة؛ والبايتات المُصدَرة عابرة وينبغي إعادة تضمينها بمجرد شحن مُحوِّل مستقر.
تحقّق من ExperimentalC2paEmbedder::SPEC_PIN_SHA مقابل التزام المسودّة الذي يتوقّعه خطّ الأنابيب لديك. وشغّل composer c2pa:draft-status في ⁨CI⁩ (خروج 0 حديث، و1 تحذير ليّن، و2 فشل صارم) لاكتشاف تقادم التثبيت.
عامِل C2paCapabilityStatus::current() بوصفه المصدر الوحيد للحقيقة عند إظهار حالة ⁨C2PA⁩ في الأدوات أو واجهة المستخدم. ولا تُعِد ذكر قيمه المنطقية يدويًا؛ فإن summary() آمنة للسجلّات ونقاط نهاية الحالة.
التقط C2paException بوصفه النوع الجامع عند استهلاك extract() أو parse(). واربط الأصناف الفرعية الأربعة بعدّادات قياس عن بُعد متمايزة باستخدام حقولها المُهيكلة.
احقن حدودًا أضيق عبر مُنشئ JumbfBoxParser لعمليات التحقّق المحدودة الذاكرة؛ فالقيم الافتراضية حدود إنتاج سخيّة.
إن C2paCapabilityStatus::__construct() عام، لذا يمكن لمثيل مبنيّ يدويًا أن يحمل قيمًا منطقية عشوائية. ومثل هذا المثيل ليس إلا كائن قيمة؛ فهو لا يغيّر أي سلوك.

اطّلع أيضًا

حدود النشر

توثّق هذه الصفحة السلوكَ القابل للملاحظة خارجيًا وسطح واجهة برمجة التطبيقات العامة المدعوم فقط. أما مسارات مساحات الأسماء الداخلية، والأصناف المساعِدة، وجداول الآليات، وأسماء ملفات كتيّبات التشغيل، وبادئات التذاكر فخارجة عن النطاق.