pappl-resource(3)

📦
version 1.4.12 · 5 versions
, in arch rolling, fedora 43, fedora 44, nixpkgs unstable

💖 pappl-resource — the resource functions, explained bestie-style 💖

okay so this is the manual page for pappl-resource, aka the pappl resource functions, from the pappl resource functions corner of the pappl docs. If you're building a printer application and you wanna add links, serve up files, or wire in your own custom web pages — this is your girl. no cap. 🎀

✨ NAME ✨

pappl-resource — pappl resource functions

📚 LIBRARY 📚

Printer Application Framework (libpappl, "pkg-config --cflags --libs pappl")

like literally just ask pkg-config, she'll tell you the flags 🫶

🦋 SYNOPSIS 🦋

#include <pappl/pappl.h>

typedef struct _pappl_printer_s pappl_printer_t;

typedef struct _pappl_system_s pappl_system_t;

void
papplPrinterAddLink(pappl_printer_t *printer, const char *label, const char *path_or_url, bool secure);

void
papplSystemAddLink(pappl_system_t *system, const char *label, const char *path_or_url, bool secure);

void
papplSystemAddResourceCallback(pappl_system_t *system, const char *path, const char *format, pappl_resource_cb_t cb, void *data);

void
papplSystemAddResourceData(pappl_system_t *system, const char *path, const char *format, const void *data, size_t datalen);

void
papplSystemAddResourceDirectory(pappl_system_t *system, const char *basepath, const char *directory);

void
papplSystemAddResourceFile(pappl_system_t *system, const char *path, const char *format, const char *filename);

void
papplSystemAddResourceString(pappl_system_t *system, const char *path, const char *format, const char *data);

void
papplSystemAddStringsData(pappl_system_t *system, const char *path, const char *language, const char *data);

void
papplSystemAddStringsFile(pappl_system_t *system, const char *path, const char *language, const char *filename);

void
papplSystemRemoveResource(pappl_system_t *system, const char *path);

🌸 DESCRIPTION 🌸

The PAPPL resource functions manage resource files, callbacks, and links in the printer application.

that's it, that's the vibe — files, callbacks, links, all handled. 💅

👑 FUNCTIONS 👑

Add a printer link to the navigation header.

void papplPrinterAddLink (
    pappl_printer_t *printer,
    const char *label,
    const char *path_or_url,
    pappl_loptions_t options
);

This function adds a navigation link for a printer. The "path_or_url" argument specifies a absolute path such as "/ipp/print/example/page" or an absolute URL such as "https://www.example.com/". The "options" argument specifies where the link is shown and whether the link should redirect an absolute path to the secure ("https://.../path") web interface.

like, absolute path or absolute URL, pick your fighter, and options decides where it shows up and whether it gets bounced to the secure web interface. 🔐

Remove a printer link from the navigation header.

void papplPrinterRemoveLink (
    pappl_printer_t *printer,
    const char *label
);

This function removes the named link for the printer.

bye bye link, named and gone. 👋

Add a link to the navigation header.

void papplSystemAddLink (
    pappl_system_t *system,
    const char *label,
    const char *path_or_url,
    pappl_loptions_t options
);

This function adds a navigation link for the system. The "path_or_url" argument specifies a absolute path such as "/page" or an absolute URL such as "https://www.example.com/". The "options" argument specifies where the link is shown and whether the link should redirect an absolute path to the secure ("https://.../path") web interface.

same energy as the printer one but system-level — absolute path like "/page", or a whole absolute URL. options handles placement + the secure redirect situation. ✨

🌈 papplSystemAddResourceCallback

Add a dynamic resource that uses a callback function.

void papplSystemAddResourceCallback (
    pappl_system_t *system,
    const char *path,
    const char *format,
    pappl_resource_cb_t cb,
    void *data
);

This function adds a dynamic resource at the specified path. When a client GET or POST request is received at the specified path, the "cb" function will be called with the client pointer and "data" pointer to respond to it.

Resource callbacks are most often used to implement custom web pages.

Note: Any custom web page that is added prior to calling the papplSystemRun function will replace the corresponding standard web page at the same path.

so like, a client hits your path with GET or POST, and your cb gets called with the client pointer and the data pointer so you can answer. custom web pages live here, bestie. and heads up — add it before papplSystemRun and it replaces the standard page at that same path. you're the main character now. 😤

🍓 papplSystemAddResourceData

Add a static data resource.

void papplSystemAddResourceData (
    pappl_system_t *system,
    const char *path,
    const char *format,
    const void *data,
    size_t datalen
);

This function adds a static resource at the specified path. The provided data is not copied to the resource and must remain stable for as long as the resource is added to the system.

Note: Any resource that is added prior to calling the papplSystemRun function will replace the corresponding standard resource at the same path.

key thing here: the data is not copied — so it has to stay stable for as long as the resource is on the system. do not let it wander off. 🫣

🧚 papplSystemAddResourceDirectory

Add external files in a directory as resources.

void papplSystemAddResourceDirectory (
    pappl_system_t *system,
    const char *basepath,
    const char *directory
);

This function adds static resources from the specified directory under the specified path. The directory is scanned and only those files present at the time of the call are available, and those files must remain stable for as long as the resources are added to the system..

Note: Any resource that is added prior to calling the papplSystemRun function will replace the corresponding standard resource at the same path.

she scans the directory at the time of the call — only the files that are there right then make it in, and they gotta stay stable the whole time. no sneaky edits. 📁

💜 papplSystemAddResourceFile

Add an external file as a resource.

void papplSystemAddResourceFile (
    pappl_system_t *system,
    const char *path,
    const char *format,
    const char *filename
);

This function adds a static resource at the specified path. The provided file is not copied to the resource and must remain stable for as long as the resource is added to the system.

Note: Any resource that is added prior to calling the papplSystemRun function will replace the corresponding standard resource at the same path.

again: not copied, must remain stable. periodt. 📌

🎀 papplSystemAddResourceString

Add a static data resource as a C string.

void papplSystemAddResourceString (
    pappl_system_t *system,
    const char *path,
    const char *format,
    const char *data
);

This function adds a static resource at the specified path. The provided data is not copied to the resource and must remain stable for as long as the resource is added to the system.

Note: Any resource that is added prior to calling the papplSystemRun function will replace the corresponding standard resource at the same path.

yes bestie, still not copied, still has to remain stable. the rules do not change just because it's a string. 💅

🌸 papplSystemAddStringsData

Add a static localization file resource.

void papplSystemAddStringsData (
    pappl_system_t *system,
    const char *path,
    const char *language,
    const char *data
);

This function adds a static localization resource at the specified path. Localization files use the NeXTStep strings ("text/strings") format defined in PWG Candidate Standard 5100.13-2013. The provided data is not copied to the resource and must remain stable for as long as the resource is added to the system.

Note: Any resource that is added prior to calling the papplSystemRun function will replace the corresponding standard resource at the same path.

localization files use the NeXTStep strings ("text/strings") format from PWG Candidate Standard 5100.13-2013 — iykyk. and yeah, not copied, keep it stable. 🌍

🔥 papplSystemAddStringsFile

Add an external localization file resource.

void papplSystemAddStringsFile (
    pappl_system_t *system,
    const char *path,
    const char *language,
    const char *filename
);

This function adds a static localization resource at the specified path. Localization files use the NeXTStep strings ("text/strings") format defined in PWG Candidate Standard 5100.13-2013. The provided file is not copied to the resource and must remain stable for as long as the resource is added to the system.

Note: Any resource that is added prior to calling the papplSystemRun function will replace the corresponding standard resource at the same path.

same format, same standard, but from a file. and, one more time for the people in the back: not copied, must remain stable. 🗣️

Remove a link from the navigation header.

void papplSystemRemoveLink (
    pappl_system_t *system,
    const char *label
);

This function removes the named link for the system.

named link, system-level, removed. clean. ✂️

🎀 papplSystemRemoveResource

Remove a resource at the specified path.

void papplSystemRemoveResource (
    pappl_system_t *system,
    const char *path
);

This function removes a resource at the specified path.

point at the path, resource is gone, that's the whole bit. 🫶

💫 SEE ALSO 💫

go read the rest of the family, they're all iconic. 💖

Copyright © 2019-2022 by Michael R Sweet.

PAPPL is licensed under the Apache License Version 2.0 with an (optional) exception to allow linking against GPL2/LGPL2 software (like older versions of CUPS), so it can be used freely in any project you'd like. See the files "LICENSE" and "NOTICE" in the source distribution for more information.

so basically: Apache License Version 2.0, plus an optional exception so you can link against GPL2/LGPL2 stuff (like the older CUPS girls) — use it in literally any project you want. the "LICENSE" and "NOTICE" files in the source distribution have the receipts. 🌈

and that's the whole page, bestie!! this was the pappl resource functions page, dated 2026-08-11, from pappl version-land, and it ate, no crumbs. now go add a link or something. mwah. 💅✨🎀

📦 where this page comes from