Debian Codegraph @

qt5/src/poppler-form.h

raw
1 /* poppler-form.h: qt interface to poppler
2 * Copyright (C) 2007-2008, Pino Toscano <[email protected]>
3 * Copyright (C) 2008, 2011, 2016, 2017, 2019-2022, Albert Astals Cid <[email protected]>
4 * Copyright (C) 2012, Adam Reichold <[email protected]>
5 * Copyright (C) 2016, Hanno Meyer-Thurow <[email protected]>
6 * Copyright (C) 2017, Hans-Ulrich Jüttner <[email protected]>
7 * Copyright (C) 2017, Tobias C. Berner <[email protected]>
8 * Copyright (C) 2018, Andre Heinecke <[email protected]>
9 * Copyright (C) 2018, Chinmoy Ranjan Pradhan <[email protected]>
10 * Copyright (C) 2018, Oliver Sander <[email protected]>
11 * Copyright (C) 2019 João Netto <[email protected]>
12 * Copyright (C) 2019, Adrian Johnson <[email protected]>
13 * Copyright (C) 2020, Thorsten Behrens <[email protected]>
14 * Copyright (C) 2020, Klarälvdalens Datakonsult AB, a KDAB Group company, <[email protected]>. Work sponsored by Technische Universität Dresden
15 * Copyright (C) 2021, Theofilos Intzoglou <[email protected]>
16 * Copyright (C) 2023-2025, g10 Code GmbH, Author: Sune Stolborg Vuorela <[email protected]>
17 * Copyright (C) 2024, Pratham Gandhi <[email protected]>
18 *
19 * This program is free software; you can redistribute it and/or modify
20 * it under the terms of the GNU General Public License as published by
21 * the Free Software Foundation; either version 2, or (at your option)
22 * any later version.
23 *
24 * This program is distributed in the hope that it will be useful,
25 * but WITHOUT ANY WARRANTY; without even the implied warranty of
26 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
27 * GNU General Public License for more details.
28 *
29 * You should have received a copy of the GNU General Public License
30 * along with this program; if not, write to the Free Software
31 * Foundation, Inc., 51 Franklin Street - Fifth Floor, Boston, MA 02110-1301, USA.
32 */
33
34 #ifndef _POPPLER_QT5_FORM_H_
35 #define _POPPLER_QT5_FORM_H_
36
37 #include <functional>
38 #include <memory>
39 #include <ctime>
40 #include <optional>
41 #include <QtCore/QDateTime>
42 #include <QtCore/QVector>
43 #include <QtCore/QList>
44 #include <QtCore/QRectF>
45 #include <QtCore/QStringList>
46 #include <QtCore/QSharedPointer>
47 #include "poppler-export.h"
48 #include "poppler-annotation.h"
49 #include "poppler-qt5.h"
50
51 class Object;
52 class Page;
53 class FormWidget;
54 class FormWidgetButton;
55 class FormWidgetText;
56 class FormWidgetChoice;
57 class FormWidgetSignature;
58
59 namespace Poppler {
60
61 class DocumentData;
62 class Link;
63
64 class FormFieldData;
65 class FormFieldIconData;
66
67 /**
68 The class containing the appearance information
69
70 \since 0.79
71 */
72
73 class POPPLER_QT5_EXPORT FormFieldIcon
74 {
75
76 friend class FormFieldIconData;
77
78 public:
79 explicit FormFieldIcon(FormFieldIconData *data);
80 FormFieldIcon(const FormFieldIcon &ffIcon);
81 ~FormFieldIcon();
82
83 FormFieldIcon &operator=(const FormFieldIcon &ffIcon);
84
85 private:
86 FormFieldIconData *d_ptr;
87 };
88 /**
89 The base class representing a form field.
90
91 \since 0.6
92 */
93 class POPPLER_QT5_EXPORT FormField
94 {
95
96 friend class FormFieldData;
97
98 public:
99 /**
100 The different types of form field.
101 */
102 enum FormType
103 {
104 FormButton, ///< A button field. See \ref Poppler::FormFieldButton::ButtonType "ButtonType"
105 FormText, ///< A text field. See \ref Poppler::FormFieldText::TextType "TextType"
106 FormChoice, ///< A single choice field. See \ref Poppler::FormFieldChoice::ChoiceType "ChoiceType"
107 FormSignature ///< A signature field.
108 };
109
110 virtual ~FormField();
111
112 /**
113 The type of the field.
114 */
115 virtual FormType type() const = 0;
116
117 /**
118 \return The size of the field, in normalized coordinates, i.e.
119 [0..1] with regard to the dimensions (cropbox) of the page
120 */
121 QRectF rect() const;
122
123 /**
124 The ID of the field.
125 */
126 int id() const;
127
128 /**
129 The internal name (T) of the field.
130 */
131 QString name() const;
132
133 /**
134 Sets the internal name (T) of the field.
135 \since 0.51
136 */
137 void setName(const QString &name) const;
138
139 /**
140 The internal fully qualified name of the field.
141 \since 0.18
142 */
143 QString fullyQualifiedName() const;
144
145 /**
146 The name of the field to be used in user interface (eg messages to
147 the user).
148 */
149 QString uiName() const;
150
151 /**
152 Whether this form field is read-only.
153 */
154 bool isReadOnly() const;
155
156 /**
157 Set whether this form field is read-only.
158 \since 0.64
159 */
160 void setReadOnly(bool value);
161
162 /**
163 Whether this form field is visible.
164 */
165 bool isVisible() const;
166
167 /**
168 Set whether this form field is visible.
169 \since 0.64
170 */
171 void setVisible(bool value);
172
173 /**
174 Whether this field is printable.
175 \since 0.79
176 */
177 bool isPrintable() const;
178
179 /**
180 Set whether this field is printable.
181 \since 0.79
182 */
183 void setPrintable(bool value);
184
185 /**
186 The activation action of this form field.
187
188 \note It may be null.
189 */
190 Link *activationAction() const;
191
192 /**
193 * Describes the flags from the form 'AA' dictionary.
194 *
195 * \since 0.53
196 */
197 enum AdditionalActionType
198 {
199 FieldModified, ///< A JavaScript action to be performed when the user modifies the field
200 FormatField, ///< A JavaScript action to be performed before the field is formatted to display its value
201 ValidateField, ///< A JavaScript action to be performed when the field value changes
202 CalculateField, ///< A JavaScript action to be performed when the field needs to be recalculated
203 };
204 /**
205 * Returns a given form additional action
206 *
207 * \since 0.53
208 */
209 Link *additionalAction(AdditionalActionType type) const;
210
211 /**
212 * Returns a given widget annotation additional action
213 *
214 * \since 0.65
215 */
216 Link *additionalAction(Annotation::AdditionalActionType type) const;
217
218 protected:
219 /// \cond PRIVATE
220 explicit FormField(std::unique_ptr<FormFieldData> dd);
221
222 std::unique_ptr<FormFieldData> m_formData;
223 /// \endcond
224
225 private:
226 Q_DISABLE_COPY(FormField)
227 };
228
229 /**
230 A form field that represents a "button".
231
232 \since 0.8
233 */
234 class POPPLER_QT5_EXPORT FormFieldButton : public FormField
235 {
236 public:
237 /**
238 * The types of button field.
239 */
240 enum ButtonType
241 {
242 Push, ///< A simple push button.
243 CheckBox, ///< A check box.
244 Radio ///< A radio button.
245 };
246
247 /// \cond PRIVATE
248 FormFieldButton(DocumentData *doc, ::Page *p, ::FormWidgetButton *w);
249 /// \endcond
250 ~FormFieldButton() override;
251
252 FormType type() const override;
253
254 /**
255 The particular type of the button field.
256 */
257 ButtonType buttonType() const;
258
259 /**
260 * The caption to be used for the button.
261 */
262 QString caption() const;
263
264 /**
265 * Gets the icon used by the button
266 *
267 * \since 0.79
268 */
269 FormFieldIcon icon() const;
270
271 /**
272 * Sets a new icon for the button, it has to be a icon
273 * returned by FormFieldButton::icon.
274 *
275 * \since 0.79
276 */
277 void setIcon(const FormFieldIcon &icon);
278
279 /**
280 The state of the button.
281 */
282 bool state() const;
283
284 /**
285 Sets the state of the button to the new \p state .
286 */
287 void setState(bool state);
288
289 /**
290 The list with the IDs of siblings (ie, buttons belonging to the same
291 group as the current one.
292
293 Valid only for \ref Radio buttons, an empty list otherwise.
294 */
295 QList<int> siblings() const;
296
297 private:
298 Q_DISABLE_COPY(FormFieldButton)
299 };
300
301 /**
302 A form field that represents a text input.
303
304 \since 0.6
305 */
306 class POPPLER_QT5_EXPORT FormFieldText : public FormField
307 {
308 public:
309 /**
310 The particular type of this text field.
311 */
312 enum TextType
313 {
314 Normal, ///< A simple singleline text field.
315 Multiline, ///< A multiline text field.
316 FileSelect ///< An input field to select the path of a file on disk.
317 };
318
319 /// \cond PRIVATE
320 FormFieldText(DocumentData *doc, ::Page *p, ::FormWidgetText *w);
321 /// \endcond
322 ~FormFieldText() override;
323
324 FormType type() const override;
325
326 /**
327 The text type of the text field.
328 */
329 TextType textType() const;
330
331 /**
332 The text associated with the text field.
333 */
334 QString text() const;
335
336 /**
337 Sets the text associated with the text field to the specified
338 \p text.
339 */
340 void setText(const QString &text);
341
342 /**
343 Sets the text inside the Appearance Stream to the specified
344 \p text
345 \since 0.80
346 */
347 void setAppearanceText(const QString &text);
348
349 /**
350 Whether this text field is a password input, eg its text \b must be
351 replaced with asterisks.
352
353 Always false for \ref FileSelect text fields.
354 */
355 bool isPassword() const;
356
357 /**
358 Whether this text field should allow rich text.
359 */
360 bool isRichText() const;
361
362 /**
363 The maximum length for the text of this field, or -1 if not set.
364 */
365 int maximumLength() const;
366
367 /**
368 The horizontal alignment for the text of this text field.
369 */
370 Qt::Alignment textAlignment() const;
371
372 /**
373 Whether the text inserted manually in the field (where possible)
374 can be spell-checked.
375 */
376 bool canBeSpellChecked() const;
377
378 /**
379 The font size of the text in the form field
380 */
381 double getFontSize() const;
382
383 /**
384 Set the font size of the text in the form field (currently only as integer)
385 */
386 void setFontSize(int fontSize);
387
388 private:
389 Q_DISABLE_COPY(FormFieldText)
390 };
391
392 /**
393 A form field that represents a choice field.
394
395 \since 0.6
396 */
397 class POPPLER_QT5_EXPORT FormFieldChoice : public FormField
398 {
399 public:
400 /**
401 The particular type of this choice field.
402 */
403 enum ChoiceType
404 {
405 ComboBox, ///< A simple singleline text field.
406 ListBox ///< A multiline text field.
407 };
408
409 /// \cond PRIVATE
410 FormFieldChoice(DocumentData *doc, ::Page *p, ::FormWidgetChoice *w);
411 /// \endcond
412 ~FormFieldChoice() override;
413
414 FormType type() const override;
415
416 /**
417 The choice type of the choice field.
418 */
419 ChoiceType choiceType() const;
420
421 /**
422 The possible choices of the choice field.
423 */
424 QStringList choices() const;
425
426 /**
427 The possible choices of the choice field.
428 The first value of the pair is the display name of the choice,
429 The second value is the export value (i.e. for use in javascript, etc) of the choice
430 @since 0.87
431 */
432 QVector<QPair<QString, QString>> choicesWithExportValues() const;
433
434 /**
435 Whether this FormFieldChoice::ComboBox is editable, i.e. the user
436 can type in a custom value.
437
438 Always false for the other types of choices.
439 */
440 bool isEditable() const;
441
442 /**
443 Whether more than one choice of this FormFieldChoice::ListBox
444 can be selected at the same time.
445
446 Always false for the other types of choices.
447 */
448 bool multiSelect() const;
449
450 /**
451 The currently selected choices.
452 */
453 QList<int> currentChoices() const;
454
455 /**
456 Sets the selected choices to \p choice.
457 */
458 void setCurrentChoices(const QList<int> &choice);
459
460 /**
461 The text entered into an editable combo box choice field. Otherwise a null string.
462
463 \since 0.22
464 */
465 QString editChoice() const;
466
467 /**
468 Sets the text entered into an editable combo box choice field. Otherwise does nothing.
469
470 \since 0.22
471 */
472 void setEditChoice(const QString &text);
473
474 /**
475 The horizontal alignment for the text of this text field.
476 */
477 Qt::Alignment textAlignment() const;
478
479 /**
480 Whether the text inserted manually in the field (where possible)
481 can be spell-checked.
482
483 Returns false if the field is not an editable text field.
484 */
485 bool canBeSpellChecked() const;
486
487 /**
488 Sets the text inside the Appearance Stream to the specified
489 \p text
490
491 \since 24.08
492 */
493 void setAppearanceChoiceText(const QString &text);
494
495 private:
496 Q_DISABLE_COPY(FormFieldChoice)
497 };
498
499 /**
500 A helper class to store x509 certificate information.
501
502 \since 0.73
503 */
504 class CertificateInfoPrivate;
505 class POPPLER_QT5_EXPORT CertificateInfo
506 {
507 public:
508 /**
509 The algorithm of public key.
510 */
511 enum PublicKeyType
512 {
513 RsaKey,
514 DsaKey,
515 EcKey,
516 OtherKey
517 };
518
519 /**
520 Certificate key usage extensions.
521 */
522 enum KeyUsageExtension
523 {
524 KuDigitalSignature = 0x80,
525 KuNonRepudiation = 0x40,
526 KuKeyEncipherment = 0x20,
527 KuDataEncipherment = 0x10,
528 KuKeyAgreement = 0x08,
529 KuKeyCertSign = 0x04,
530 KuClrSign = 0x02,
531 KuEncipherOnly = 0x01,
532 KuNone = 0x00
533 };
534 Q_DECLARE_FLAGS(KeyUsageExtensions, KeyUsageExtension)
535
536 /**
537 * The type of the certificate
538 *
539 * \since 25.03
540 */
541 enum class CertificateType
542 {
543 X509,
544 PGP
545 };
546
547 /**
548 Predefined keys for elements in an entity's distinguished name.
549 */
550 enum EntityInfoKey
551 {
552 CommonName,
553 DistinguishedName,
554 EmailAddress,
555 Organization,
556 };
557
558 /** A signing key can be located in different places
559 sometimes. For the user, it might be easier to pick
560 the key located on a card if it has some visual
561 indicator that it is somehow removable.
562
563 \note a keylocation for a certificate without a private
564 key (cannot be used for signing) will likely be "Unknown"
565
566 \since 23.09
567 */
568 enum class KeyLocation
569 {
570 Unknown, /** We don't know the location */
571 Other, /** We know the location, but it is somehow not covered by this enum */
572 Computer, /** The key is on this computer */
573 HardwareToken /** The key is on a dedicated hardware token, either a smartcard or a dedicated usb token (e.g. gnuk, nitrokey or yubikey) */
574 };
575
576 CertificateInfo();
577 explicit CertificateInfo(CertificateInfoPrivate *priv);
578 ~CertificateInfo();
579
580 /**
581 Returns true if certificate has no contents; otherwise returns false
582 */
583 bool isNull() const;
584
585 /**
586 The certificate version string.
587 */
588 int version() const;
589
590 /**
591 The certificate serial number.
592 */
593 QByteArray serialNumber() const;
594
595 /**
596 Information about the issuer.
597 */
598 QString issuerInfo(EntityInfoKey key) const;
599
600 /**
601 Information about the subject
602 */
603 QString subjectInfo(EntityInfoKey key) const;
604
605 /**
606 The certificate internal database nickname
607
608 \since 21.01
609 */
610 QString nickName() const;
611
612 /**
613 The date-time when certificate becomes valid.
614 */
615 QDateTime validityStart() const;
616
617 /**
618 The date-time when certificate expires.
619 */
620 QDateTime validityEnd() const;
621
622 /**
623 The uses allowed for the certificate.
624 */
625 KeyUsageExtensions keyUsageExtensions() const;
626
627 /**
628 The public key value.
629 */
630 QByteArray publicKey() const;
631
632 /**
633 The public key type.
634 */
635 PublicKeyType publicKeyType() const;
636
637 /**
638 The strength of public key in bits.
639 */
640 int publicKeyStrength() const;
641
642 /**
643 Returns true if certificate is self-signed otherwise returns false.
644 */
645 bool isSelfSigned() const;
646
647 /**
648 * \return certificate type
649 *
650 * \since 25.03
651 */
652 CertificateType certificateType() const;
653
654 /**
655 The DER encoded certificate.
656 */
657 QByteArray certificateData() const;
658
659 /**
660 Checks if the given password is the correct one for this certificate
661
662 \since 21.01
663 */
664 bool checkPassword(const QString &password) const;
665
666 /**
667 The storage location for this key
668
669 \since 23.09
670 */
671 KeyLocation keyLocation() const;
672
673 CertificateInfo(const CertificateInfo &other);
674 CertificateInfo &operator=(const CertificateInfo &other);
675
676 private:
677 Q_DECLARE_PRIVATE(CertificateInfo)
678
679 QSharedPointer<CertificateInfoPrivate> d_ptr;
680 };
681 Q_DECLARE_OPERATORS_FOR_FLAGS(CertificateInfo::KeyUsageExtensions)
682
683 /**
684 A signature validation info helper class.
685
686 \since 0.51
687 */
688 class SignatureValidationInfoPrivate;
689 class POPPLER_QT5_EXPORT SignatureValidationInfo
690 {
691 public:
692 /**
693 The verification result of the signature.
694 */
695 enum SignatureStatus
696 {
697 SignatureValid, ///< The signature is cryptographically valid.
698 SignatureInvalid, ///< The signature is cryptographically invalid.
699 SignatureDigestMismatch, ///< The document content was changed after the signature was applied.
700 SignatureDecodingError, ///< The signature CMS/PKCS7 structure is malformed.
701 SignatureGenericError, ///< The signature could not be verified.
702 SignatureNotFound, ///< The requested signature is not present in the document.
703 SignatureNotVerified ///< The signature is not yet verified.
704 };
705
706 /**
707 The verification result of the certificate.
708 */
709 enum CertificateStatus
710 {
711 CertificateTrusted, ///< The certificate is considered trusted.
712 CertificateUntrustedIssuer, ///< The issuer of this certificate has been marked as untrusted by the user.
713 CertificateUnknownIssuer, ///< The certificate trust chain has not finished in a trusted root certificate.
714 CertificateRevoked, ///< The certificate was revoked by the issuing certificate authority.
715 CertificateExpired, ///< The signing time is outside the validity bounds of this certificate.
716 CertificateGenericError, ///< The certificate could not be verified.
717 CertificateNotVerified, ///< The certificate is not yet verified.
718 CertificateVerificationInProgress ///< The certificate is not yet verified but is in progress in the background. See \ref validateAsync \since 24.05
719 };
720
721 /**
722 The hash algorithm of the signature
723 \since 0.58
724 */
725 enum HashAlgorithm
726 {
727 HashAlgorithmUnknown,
728 HashAlgorithmMd2,
729 HashAlgorithmMd5,
730 HashAlgorithmSha1,
731 HashAlgorithmSha256,
732 HashAlgorithmSha384,
733 HashAlgorithmSha512,
734 HashAlgorithmSha224
735 };
736
737 /// \cond PRIVATE
738 explicit SignatureValidationInfo(SignatureValidationInfoPrivate *priv);
739 /// \endcond
740 ~SignatureValidationInfo();
741
742 /**
743 The signature status of the signature.
744 */
745 SignatureStatus signatureStatus() const;
746
747 /**
748 The certificate status of the signature.
749 */
750 CertificateStatus certificateStatus() const;
751
752 /**
753 The signer name associated with the signature.
754 */
755 QString signerName() const;
756
757 /**
758 The signer subject distinguished name associated with the signature.
759 \since 0.58
760 */
761 QString signerSubjectDN() const;
762
763 /**
764 Get signing location.
765 \since 0.68
766 */
767 QString location() const;
768
769 /**
770 Get signing reason.
771 \since 0.68
772 */
773 QString reason() const;
774
775 /**
776 The hash algorithm used for the signature.
777 \since 0.58
778 */
779 HashAlgorithm hashAlgorithm() const;
780
781 /**
782 The signing time associated with the signature.
783 */
784 time_t signingTime() const;
785
786 /**
787 Get the signature binary data.
788 \since 0.58
789 */
790 QByteArray signature() const;
791
792 /**
793 Get the bounds of the ranges of the document which are signed.
794 \since 0.58
795 */
796 QList<qint64> signedRangeBounds() const;
797
798 /**
799 Checks whether the signature authenticates the total document
800 except for the signature itself.
801 \since 0.58
802 */
803 bool signsTotalDocument() const;
804
805 /**
806 The signer certificate info.
807 \since 0.73
808 */
809 CertificateInfo certificateInfo() const;
810
811 SignatureValidationInfo(const SignatureValidationInfo &other);
812 SignatureValidationInfo &operator=(const SignatureValidationInfo &other);
813
814 private:
815 Q_DECLARE_PRIVATE(SignatureValidationInfo)
816 friend class FormFieldSignature;
817 QSharedPointer<SignatureValidationInfoPrivate> d_ptr;
818 };
819
820 /**
821 * Object help waiting for some async event
822 *
823 * \since 24.05
824 */
825 class AsyncObjectPrivate;
826 class POPPLER_QT5_EXPORT AsyncObject : public QObject // clazy:exclude=ctor-missing-parent-argument
827 {
828 Q_OBJECT
829 public:
830 /* Constructor. On purpose not having a QObject parameter
831 It will be returned by shared_ptr or unique_ptr
832 */
833 AsyncObject();
834 ~AsyncObject() override;
835 Q_SIGNALS:
836 void done();
837
838 private:
839 std::unique_ptr<AsyncObjectPrivate> d;
840 };
841
842 /**
843 A form field that represents a signature.
844
845 \since 0.51
846 */
847 class POPPLER_QT5_EXPORT FormFieldSignature : public FormField
848 {
849 public:
850 /**
851 The types of signature fields.
852 \since 0.58
853 */
854 enum SignatureType
855 {
856 AdbePkcs7sha1,
857 AdbePkcs7detached,
858 EtsiCAdESdetached,
859 UnknownSignatureType, ///< \since 0.90
860 UnsignedSignature, ///< \since 22.02
861 G10cPgpSignatureDetached, ///< non standard signature type \since 25.01
862 };
863
864 /**
865 The validation options of this signature.
866 */
867 enum ValidateOptions
868 {
869 ValidateVerifyCertificate = 1, ///< Validate the certificate.
870 ValidateForceRevalidation = 2, ///< Force revalidation of the certificate.
871 ValidateWithoutOCSPRevocationCheck = 4, ///< Do not contact OCSP servers to check for certificate revocation status \since 21.10
872 ValidateUseAIACertFetch = 8 ///< Use the AIA extension for certificate fetching \since 21.10
873 };
874
875 /// \cond PRIVATE
876 FormFieldSignature(DocumentData *doc, ::Page *p, ::FormWidgetSignature *w);
877 /// \endcond
878 ~FormFieldSignature() override;
879
880 FormType type() const override;
881
882 /**
883 The signature type
884 \since 0.58
885 */
886 SignatureType signatureType() const;
887
888 /**
889 Validate the signature with now as validation time.
890
891 Reset signature validatation info of scoped instance.
892
893 \note depending on the backend, some options are only
894 partially respected. In case of the NSS backend, the two options
895 requiring network access, AIAFetch and OCSP,
896 can be toggled individually. In case of the GPG backend, if either
897 OCSP is used or AIAFetch is used, the other one is also used.
898
899 \deprecated Please rewrite to the async version, that allows the network traffic part of fetching to happen in the background
900 */
901 POPPLER_QT5_DEPRECATED SignatureValidationInfo validate(ValidateOptions opt) const;
902
903 /**
904 Validate the signature with @p validationTime as validation time.
905
906 Reset signature validatation info of scoped instance.
907
908 \since 0.58
909
910 \note depending on the backend, some options are only
911 partially respected. In case of the NSS backend, the two options
912 requiring network access, AIAFetch and OCSP,
913 can be toggled individually. In case of the GPG backend, if either
914 OCSP is used or AIAFetch is used, the other one is also used.
915
916 \deprecated Please rewrite to the async version, that allows the network traffic part of fetching to happen in the background
917 */
918 POPPLER_QT5_DEPRECATED SignatureValidationInfo validate(int opt, const QDateTime &validationTime) const;
919
920 /**
921 Validate the signature with @p validationTime as validation time.
922
923 Reset signature validatation info of scoped instance.
924
925 \since 24.05
926
927 \note depending on the backend, some options are only
928 partially respected. In case of the NSS backend, the two options
929 requiring network access, AIAFetch and OCSP,
930 can be toggled individually. In case of the GPG backend, if either
931 OCSP is used or AIAFetch is used, the other one is also used.
932
933 \note certificate validation will have started when this function return. See \ref validateResult on how to get certifcate validation
934 \note connections to \ref AsyncObject must happen by the caller
935 before returning control to the event loop, else signals is not guaranteed to be delivered
936 */
937 std::pair<SignatureValidationInfo, std::shared_ptr<AsyncObject>> validateAsync(ValidateOptions opt, const QDateTime &validationTime = {}) const;
938
939 /**
940 * \return the updated signature validation info from validateAsync
941 * \note that this function will block if the result is not yet ready.
942 * Wait for the \ref AsyncObject::done signal to avoid this function blocking on an inconvenient time
943 *
944 * \since 24.05
945 */
946 SignatureValidationInfo::CertificateStatus validateResult() const;
947
948 /**
949 * \since 22.02
950 */
951 enum SigningResult
952 {
953 FieldAlreadySigned, ///< Trying to sign a field that is already signed
954 GenericSigningError,
955 SigningSuccess,
956 InternalError, ///< Unexpected error, likely a bug in poppler \since 25.07
957 KeyMissing, ///< Key not found (Either the input key is not from the list or the available keys has changed underneath) \since 25.07
958 WriteFailed, ///< Write failed (permissions, faulty disk, ...) \since 25.07
959 UserCancelled, ///< User cancelled the process \since 25.07
960 BadPassphrase, ///< User entered bad passphrase \since 25.07
961
962 };
963
964 /**
965 Signs a field of UnsignedSignature type.
966
967 Ignores data.page(), data.fieldPartialName() and data.boundingRectangle()
968
969 \since 22.02
970 */
971 SigningResult sign(const QString &outputFileName, const PDFConverter::NewSignatureData &data) const;
972
973 /**
974 * A string with a string that might offer more details of the signing result failure
975 * \note the string here is likely not super useful for end users, but might give more details to a trained supporter / bug triager
976 * \since 25.07
977 */
978 ErrorString lastSigningErrorDetails() const;
979
980 private:
981 Q_DISABLE_COPY(FormFieldSignature)
982 };
983
984 /**
985 * Possible compiled in backends for signature handling
986 *
987 * \since 23.06
988 */
989 enum class CryptoSignBackend
990 {
991 NSS,
992 GPG
993 };
994
995 /**
996 * The available compiled-in backends
997 *
998 * \since 23.06
999 */
1000 QVector<CryptoSignBackend> POPPLER_QT5_EXPORT availableCryptoSignBackends();
1001
1002 /**
1003 * Returns current active backend or nullopt if none is active
1004 *
1005 * \note there will always be an active backend if there is available backends
1006 *
1007 * \since 23.06
1008 */
1009 std::optional<CryptoSignBackend> POPPLER_QT5_EXPORT activeCryptoSignBackend();
1010
1011 /**
1012 * Sets active backend
1013 *
1014 * \return true on success
1015 *
1016 * \since 23.06
1017 */
1018 bool POPPLER_QT5_EXPORT setActiveCryptoSignBackend(CryptoSignBackend backend);
1019
1020 enum class CryptoSignBackendFeature
1021 {
1022 /// If the backend itself out of band requests passwords
1023 /// or if the host applicaion somehow must do it
1024 BackendAsksPassphrase
1025 };
1026
1027 /**
1028 * Queries if a backend supports or not supports a given feature.
1029 *
1030 * \since 23.06
1031 */
1032 bool POPPLER_QT5_EXPORT hasCryptoSignBackendFeature(CryptoSignBackend, CryptoSignBackendFeature);
1033
1034 /**
1035 Returns is poppler was compiled with NSS support
1036
1037 \deprecated Use availableBackends instead
1038
1039 \since 21.01
1040 */
1041 bool POPPLER_QT5_DEPRECATED POPPLER_QT5_EXPORT hasNSSSupport();
1042
1043 /**
1044 Return vector of suitable signing certificates
1045
1046 \since 21.01
1047 */
1048 QVector<CertificateInfo> POPPLER_QT5_EXPORT getAvailableSigningCertificates();
1049
1050 /**
1051 Gets the current NSS CertDB directory
1052
1053 \since 21.01
1054 */
1055 QString POPPLER_QT5_EXPORT getNSSDir();
1056
1057 /**
1058 Set a custom NSS CertDB directory. Needs to be called before doing any other signature operation
1059
1060 \since 21.01
1061 */
1062 void POPPLER_QT5_EXPORT setNSSDir(const QString &pathURL);
1063
1064 /**
1065 Sets the callback for NSS password requests
1066
1067 \since 21.01
1068 */
1069 void POPPLER_QT5_EXPORT setNSSPasswordCallback(const std::function<char *(const char *)> &f);
1070
1071 /**
1072 * Allow pgp signatures in pdf files (standard-extension, experimental)
1073 * Not supported for NSS backend
1074 *
1075 * \param allowed new value for pgp signatures allowed
1076 *
1077 * \since 25.03
1078 */
1079 void POPPLER_QT5_EXPORT setPgpSignaturesAllowed(bool allowed);
1080
1081 /**
1082 * \returns if pgp signatures are allowed.
1083 *
1084 * \since 25.03
1085 */
1086 bool POPPLER_QT5_EXPORT arePgpSignaturesAllowed();
1087 }
1088
1089 #endif