Deprecation of FPDF_InitLibrary() ?

[geisserml]

The documentation for FPDF_InitLibrary() says:

```

// Convenience function to call FPDF_InitLibraryWithConfig() for
// backwards compatibility purposes. This will be deprecated in the
// future.

```

I'm wondering what is the rationale for the deprecation of FPDF_initLibrary()?

My project doesn't need any of the initialisation options, so I'd have to do FPDF_InitLibraryWithConfig(FPDF_LIBRARY_CONFIG(2, None, None, 0)).

However, this means I would need to follow updates of the interface version, which is not necessary with FPDF_InitLibrary(), so isn't that better in terms of API stability?

[geisserml]

Ah, I see implementing the config fields isn't mandatory - so I can just call FPDF_InitLibraryWithConfig( FPDF_LIBRARY_CONFIG() ) and don't need to wory about future changes.
Then I agree it makes sense to deprecate the convenience alias. Sorry!

[Lei Zhang]

The intention was to ask embedders to explicitly state the
configuration they want, especially if the configuration parameters
evolve to a point where there is some required field. If that does
happen, then the parameter-less FPDF_InitLibrary() won't work.

> --
> You received this message because you are subscribed to the Google Groups "pdfium" group.
> To unsubscribe from this group and stop receiving emails from it, send an email to pdfium+un...@googlegroups.com.
> To view this discussion on the web visit https://groups.google.com/d/msgid/pdfium/61157452-d67e-4348-816f-c322e020060cn%40googlegroups.com.

[Lei Zhang]

It turns out I also would like to deprecate
FPDF_InitLibraryWithConfig(), as it uses FPDF_LIBRARY_CONFIG, which is
a struct that is directly exposed to embedders. The struct can be
hard/annoying to change. For instance:
- Any field change should result in a version update. If PDFium
developers accidentally forget, embedders may have a bad time. (See
also next point)
- Adding a new field to FPDF_LIBRARY_CONFIG can potentially result in
an embedder passing in a config with the new field uninitialized.
- Fields in the struct must be annotated with the versions they are valid for.
- FPDF_InitLibraryWithConfig() needs to be able to parse all supported
config versions, which can become complex over time as the number of
fields increases.

While it is possible to work with the existing way of doing init, and
do versioning on FPDF_LIBRARY_CONFIG, there are potentially better
alternatives. I would like to have an opaque config object, instead of
FPDF_LIBRARY_CONFIG, just as PDFium exposes FPDF_DOCUMENT and not the
underlying class that implements a document. Along with a set of APIs
to modify the config, and a new library init function that takes the
opaque config object, they can fully replace
FPDF_InitLibraryWithConfig(). Then init config changes become public
API changes, which goes through the same experimental / stable /
deprecated lifecycle like any other public API. To put this more
concretely, https://pdfium-review.googlesource.com/c/pdfium/+/97151/1/
is a work-in-progress CL to implement such an object and associated
APIs.

One additional change is the proposed init function returns a bool to
indicate whether initialization succeeded or not. (Maybe it should
become an error code...) It gives PDFium an opportunity to signal to
the embedder if something goes wrong during initialization. If PDFium
ever changes to require some initialization data from the embedder,
the return value can help let the embedder know about that.

[Lei Zhang]

In https://crbug.com/pdfium/1446, at the time I was thinking about not
having to deal with versioning as much, by forcing embedders to
upgrade to the newest version. Of course, then embedders have to
understand all the new fields in FPDF_LIBRARY_CONFIG and deal with
them. I'm hoping with my proposal, there will be less of that.

For additional context, there is ongoing work that can change how
initialization works. e.g. https://crbug.com/pdfium/1844 and
https://crbug.com/pdfium/1878. So this is a good time to figure out
how to make those changes in a more future-proof and less disruptive
way.

[geisserml]

> - Adding a new field to FPDF_LIBRARY_CONFIG can potentially result in
> an embedder passing in a config with the new field uninitialized.

Is it generally illegal to pass config structs with uninitialized fields, or is this just about required fields?

[Lei Zhang]

On Wed, Aug 31, 2022 at 4:20 AM geisserml <geis...@gmail.com> wrote:
>
> > - Adding a new field to FPDF_LIBRARY_CONFIG can potentially result in
> > an embedder passing in a config with the new field uninitialized.
>
> Is it generally illegal to pass config structs with uninitialized fields, or is this just about required fields?

It's more error prone and in general just not a good thing to do in C/C++.

BTW, https://pdfium-review.googlesource.com/c/pdfium/+/97151/3/ has a
slightly broken implementation, but is API complete and had
equivalents for setting every field in FPDF_LIBRARY_CONFIG.

[geisserml]

> It's more error prone and in general just not a good thing to do in C/C++.

OK, I checked that ctypes/ctypesgen always does assign defaults corresponding to the type in question, e. g. 0 for int or a no-op CFUNCTYPE instance for function fields.

So in pypdfium2 I don't need to care about non-relevant fields as long as the default set by ctypes is appropriate.