Haiku BAppFileInfo: Executable Signatures, Supported Types, and Version Data

BAppFileInfo is the Storage Kit interface for application metadata associated with an executable file. It builds on BNodeInfo and can read or write fields such as an application’s signature, supported MIME types, icons, flags, and version information. The critical boundary is that executable metadata is not the same thing as the MIME database, a particular document’s BEOS:TYPE, or a preferred-application override on one file.

That separation matters when packaging a native application, updating its supported file types, or diagnosing why Tracker launches a different handler. Editing metadata on an executable does not automatically mean every existing document changes type. Updating the MIME database can affect associations beyond the one executable. A reliable installer or packaging step states which object it is modifying and checks each status result.

Initialize against the application file

BAppFileInfo is associated with a BFile or other supported node context. Open the executable with the access needed by the operation, check the file’s initialization, construct the metadata object, then check its own initialization before reading or writing fields. A valid BAppFileInfo object is not proof that every requested metadata field exists or can be changed.

BFile executable("/boot/home/apps/Example", B_READ_ONLY);
if (executable.InitCheck() != B_OK)
	return executable.InitCheck();

BAppFileInfo appInfo(&executable);
status_t status = appInfo.InitCheck();
if (status != B_OK)
	return status;

char signature[B_MIME_TYPE_LENGTH] = {};
status = appInfo.GetSignature(signature);
if (status != B_OK)
	return status;

The path is illustrative; installed locations and permissions vary. A read-only open is enough for this getter; use write access only when the operation needs to modify metadata. Keep the BFile alive while the metadata object uses it. Check output buffers and statuses, and do not assume a failed Get...() call cleared the buffer: the implementation may write data before detecting a short or malformed read. Initialize output storage and only consume it after a successful result.

Keep the application signature stable

The application signature is a MIME-style identifier for the application itself. It should be unique within the ecosystem and stable across versions when the updated binary remains the same application. Changing it casually can make the new build appear to be a different application to the roster and MIME system. Choose it as part of the product identity and keep it consistent between the application’s runtime declaration, packaged binary metadata, and installer configuration.

SetSignature() writes the executable’s application signature. It does not set the preferred application for an arbitrary document. If an application is registered to handle a MIME type, that is a type-level relationship managed through supported-type metadata and MIME database behavior. If one user’s particular document should open in a different application, that is a different preference with different scope. Diagnose the actual field rather than changing whichever API name sounds closest.

Do not use BAppFileInfo::SetType() as a substitute for application identity or supported-type registration. It sets the MIME type of the associated executable node; changing that to a document type can disrupt the file’s MIME classification and is not how an application declares which documents it can open. Use SetSignature() for application identity and SetSupportedTypes() or the appropriate MIME APIs for document support.

Declare supported types intentionally

Supported types describe file formats an application can handle. The API represents them in a BMessage and offers SetSupportedTypes() overloads, including options that control whether the MIME database is updated and how removed types are synchronized. Choose the overload deliberately. Updating only the executable metadata and updating the system’s MIME database are not interchangeable operations.

Before publishing a type, verify that the application actually parses it and define the supported operations. A MIME type listed in metadata is a claim to the shell and other applications; declaring an unsupported format creates broken open-with behavior and false expectations. Prefer narrow, specific types to a broad wildcard unless the application can safely inspect and reject unsupported content. The receiving application must still validate file contents rather than trusting the type label.

When retiring a format, understand the synchronization option and migration consequences. Removing a type from one version can remove its association from the database depending on the API path used. Test upgrade and downgrade scenarios with a clean user profile and an existing MIME database; a metadata update that works on a fresh install can leave stale associations or erase a user’s intentional setup during an upgrade.

Choose where metadata is stored

BAppFileInfo supports metadata stored in file attributes and/or resources, and SetInfoLocation() controls the location used. IsUsingAttributes() and IsUsingResources() report the active behavior. These storage mechanisms have different packaging and filesystem properties. File attributes are tied to the filesystem and can be unavailable or lost when an executable is copied through a filesystem that does not preserve them. Resources are embedded in the file’s resource data and travel with the executable, but updating them can require a writable binary and a packaging step.

Do not assume that copying the executable preserves all metadata on every target volume. If the installer stages files on a different filesystem, verify signature, icons, supported types, and version data after installation on that filesystem. Also verify the actual packaged binary rather than only the build-tree copy. A release pipeline should fail if required metadata cannot be read back after writing.

Icons and version fields deserve the same post-write validation. An icon associated with an application is not the same as the icon for a particular document type. Version info can carry short and long version strings; keep them aligned with release notes and package metadata so support staff can identify the exact build. Avoid hand-editing one channel while another generated resource still reports an older version.

Make metadata updates recoverable

Metadata setters can fail because the file is not writable, the object is uninitialized, storage is unavailable, data is malformed, or a MIME database operation cannot complete. Preserve the specific status, stop dependent steps when required values were not written, and provide a useful diagnostic. Do not report a successful installation simply because the executable was copied if its launch identity or file associations are required for the product to work.

For a packaging system, update a temporary or staging copy, read the values back, and only then promote the artifact. Be careful about changing a running executable or a shared installation path; the operation may be rejected or may produce inconsistent metadata if interrupted. Treat the binary, resources, and system MIME registration as a coordinated release transaction with a documented recovery strategy, not as a sequence of unrelated best-effort setters.

Diagnose the right layer

If double-clicking a file launches an unexpected application, inspect the document’s MIME type, the MIME database’s preferred handler, and any per-node preferred application separately. If Tracker shows a generic icon, inspect the relevant type and icon metadata rather than assuming BAppFileInfo for the editor is wrong. If an application cannot be discovered or launched, confirm its signature, executable type, install path, and roster state. Each symptom points to a different layer.

Test metadata on a fresh install, an upgrade, a removable volume, and a filesystem with different attribute behavior. Confirm that a failed getter is not interpreted as a previous value, that the application signature remains stable across upgrades, and that supported-type updates have the intended MIME database effect. Verify document parsing independently because metadata is a routing hint, not a content validator.

The practical rule is to identify the exact subject of the metadata: executable, MIME type, individual document, or handler association. BAppFileInfo is powerful because it describes the application binary, and safe use depends on not asking it to stand in for the other three.

Related:

Sources: