Haiku BNodeInfo: Per-File MIME Types, Icons, and App Hints

BNodeInfo reads and writes metadata associated with a filesystem node, including its MIME type, icon, preferred application, and application hint. It is a file-oriented API: the object attaches to a BNode, such as a BFile, and operates on that node’s metadata. It is related to Haiku’s MIME database but is not the entire database service, and it is not a replacement for BAppFileInfo when editing an application’s executable signature or supported types.

This distinction matters in file managers, importers, and document applications. A data file can have a per-file MIME type and custom icon. An executable’s signature and supported document types are application metadata. Changing one does not automatically register every handler relationship or prove that a document’s bytes match the label.

Attach to a valid node

Construct BNodeInfo with a BNode or call SetTo(), then inspect InitCheck(). The node must be open and valid for the intended operation. Keep the node alive while using the metadata helper, and check every returned status. Do not attach a BNodeInfo to a temporary object that is destroyed before a later metadata call.

BFile file(path, B_READ_WRITE);
status_t status = file.InitCheck();
if (status != B_OK)
    return status;

BNodeInfo info(&file);
status = info.InitCheck();
if (status != B_OK)
    return status;

char type[B_MIME_TYPE_LENGTH];
status = info.GetType(type);
if (status == B_OK) {
    // Use the returned type as metadata, not as proof of file contents.
}

Use a buffer sized according to the MIME type constant defined by the platform headers. Initialize it and inspect the status before reading it. A failed getter does not mean the node is a file of some default type; it means the requested metadata could not be retrieved under the current conditions.

Separate node type from application registration

The per-node type identifies the content format used by Haiku and applications. It is usually a MIME-style string. SetType() writes that metadata, but it does not convert the file contents. If a tool changes a binary document from one format to another, the type should be updated only after the new bytes are completely written and validated. Otherwise the system may dispatch the file to an application that cannot parse it.

The MIME database maps types to descriptions, preferred applications, attributes, and other system knowledge. A node’s type attribute is one piece of that ecosystem. If the system does not recognize a type, registering or refreshing the MIME database is a separate administrative/developer workflow. Do not attempt to repair a missing global type by changing unrelated files’ node attributes.

GetPreferredApp() and SetPreferredApp() operate on the per-node preferred application hint. This can express a user or workflow preference for one item without rewriting the application’s global signature. GetAppHint() and SetAppHint() similarly use an entry reference for an application hint. Before storing a hint, confirm that the referenced application is the intended one and can be launched. A hint is not proof the program remains installed forever.

For an application executable, use BAppFileInfo to manipulate its signature, supported types, and version data. Those fields participate in application registration. Avoid using BNodeInfo::SetType() as a substitute for an executable signature: the APIs have different roles even though both relate to MIME identity.

Read and write icons safely

GetIcon() and SetIcon() have bitmap and raw-data overloads. The bitmap overload expects a BBitmap with the appropriate icon dimensions and color space. The raw-data overload returns or accepts icon bytes with a type_code on read; preserve the type and size rather than treating the payload as an arbitrary PNG. When displaying icons, prefer the Tracker icon lookup when the goal is the final system-resolved icon, because MIME associations and application state can influence what users see.

Before updating an icon, validate bitmap initialization, dimensions, and color space. Keep the bitmap lifetime valid for the API call and check the returned status. An icon update does not change the file’s content type. If the application writes the icon and MIME type separately, handle partial failure: the file may have one updated attribute and one old attribute. Report what succeeded and provide a repair path rather than claiming the whole update was atomic.

The BNodeInfo object stores a pointer to its associated node, so do not let it outlive that node. If metadata changes while another component is reading the file, refresh or recreate your metadata view as appropriate. Avoid using a cached MIME type as a permanent file identity; content can be replaced while the path remains the same.

Validate metadata against real file content

For an importer, combine extension, MIME metadata, and format sniffing according to the application’s trust model. Extensions and node attributes are user-editable labels. A parser should still reject malformed or unexpected bytes. For an exporter, write and close the data first, verify the output signature or parseability, then update the metadata. If validation fails, preserve the previous file or mark the temporary output as incomplete.

Test files with missing type metadata, an incorrect type, a custom icon, an unavailable preferred application, and a stale app hint. Also test metadata on read-only nodes and non-BFS filesystems supported by the system. Check whether the desired attributes are supported and how errors are surfaced; do not assume every filesystem implements every Haiku metadata behavior identically.

When a user reports a wrong icon or handler, inspect the node’s current type, MIME database state, preferred application, and application registration independently. Restarting Tracker may refresh presentation in some cases, but it is not a substitute for identifying which metadata layer is wrong. Capture the exact file reference and status code while protecting sensitive file names in shared reports.

Treat a series of metadata edits as a small state machine. Read and retain the original values, validate the replacement type and application reference, apply one change at a time, and log the result of each call. If the second write fails, either restore the first value and verify the rollback or leave a clear partial-update record for the user. Do not claim all-or-nothing behavior unless your own storage layer provides it. On removable volumes, test what happens after the volume disappears between opening the node and updating its attributes; reopen and revalidate rather than retrying through a stale object.

For raw icon data, keep the returned type_code with the bytes and preserve the exact size supplied by the API. Do not assume the payload is a standalone image file merely because it can be written to an attribute. If an icon must cross an application boundary, use a format with an explicit converter and validate its dimensions and color representation. Also test a node whose MIME type has no registered preferred app: that is a valid state and should not cause the UI to invent an association or silently rewrite the node.

When the metadata API reports success, verify the result through a fresh node or a separate read path in tests. This catches cached-object assumptions and confirms the persisted attribute is visible after reopening. Keep these checks in integration tests for each filesystem your product supports; attribute behavior is not identical across all volumes.

Acceptance criteria

Accept a BNodeInfo workflow when the target node is valid and remains alive through the operation, MIME type changes occur only after content validation, app-specific metadata uses BAppFileInfo, and icon getters/setters validate size and status. Verify custom handlers, unavailable application hints, missing metadata, and a filesystem that may not support the expected attributes.

BNodeInfo is a focused interface to per-node metadata. It does not validate file bytes, install global MIME definitions, or replace the executable metadata contract managed by BAppFileInfo.

Related:

Sources:

Attach to a valid node

Separate node type from application registration

Read and write icons safely

Validate metadata against real file content

Acceptance criteria

Comments