How to skip protected macOS locations from detection process?

Overview

The Restrict Bundle Search feature allows you to specify which protected macOS locations the WAAPI detection engine should skip when scanning for installed application bundles.

This prevents macOS from displaying permission dialogs that require explicit user consent for accessing certain folders (e.g., Photos, Contacts, Reminders, Calendars). Using Restrict Bundle Search streamlines the end-user experience, especially in headless or automated deployments.

When to Use

• You have a headless or automated deployment that needs to enumerate installed applications without triggering macOS permission dialogs.
• Your product only needs to detect bundles in "standard" locations (e.g., /Applications) and should skip user-protected data.

Configuration Steps

To enable Restrict Bundle Search, pass the restrict_bundle_search configuration key when invoking the wa_api_setup API.

1.1 Configuration Key

#define WAAPI_CONFIG_RESTRICT_BUNDLE_SEARCH L"restrict_bundle_search"

• Type: string
• Default: (empty / no restrictions)

1.2 Value Format

The value for the restrict_bundle_search is a vertical-bar (|)-delimited list of folder tokens or absolute paths:

"restrict_bundle_search": "<entry1>|<entry2>|…|<entryN>"

• Entries can be:

  • Tokens (see 1.3)
  • Absolute POSIX paths (e.g., /Volumes/MyData).

• Order does not matter; duplicates are ignored.

• Invalid formats or tokens will return WAAPI_ERROR_INVALID_INPUT_ARGS.

1.3 Supported Tokens

Note:

• When using all_predefined_values, no other built-in tokens may appear alongside it—only custom absolute paths may be appended.
• Malformed :except: clauses or mixing all_predefined_values with other tokens will result in WAAPI_ERROR_INVALID_INPUT_ARGS.

1.4 Examples

// 1) Basic: all built-in tokens

{ "restrict_bundle_search": "all_predefined_values" }

​

// 2) With custom path

{ "restrict_bundle_search": "all_predefined_values|/custom/path" }

​

// 3) Exclude a few built-ins

{ "restrict_bundle_search": "all_predefined_values:except:photos,user_home" }

​

// 4) Exclude + custom path

{ "restrict_bundle_search": "all_predefined_values:except:reminders|/temp/path" }

​

// 5) Invalid: unknown except token → WAAPI_ERROR_INVALID_INPUT_ARGS

{ "restrict_bundle_search": "all_predefined_values:except:invalid_token" }

​

// 6) Invalid: empty except list → WAAPI_ERROR_INVALID_INPUT_ARGS

{ "restrict_bundle_search": "all_predefined_values:except:" }

​

// 7) Individual tokens + custom path

{ "restrict_bundle_search": "desktop|downloads|user_home|/Volumes/MyData" }

1.5 Return Codes

• WAAPI_OK: All specified tokens and paths were recognized and applied.
• WAAPI_OK_OUTDATED_ENGINE: One or more unknown tokens were skipped; the rest were applied.
• WAAPI_ERROR_INVALID_INPUT_ARGS: The format or tokens are invalid (e.g., malformed :except:, unknown token, or mixing tokens improperly).
• WAAPI_ERROR_FAILED_TO_INIT_BUNDLE_RESTRICTION_SEARCH: The SDK was unable to initialize the bundle restriction search.

Future Scenarios & Update Guidance

As macOS evolves, you may see two kinds of changes in the set of protected folders. We split tokens into:

2.1 Static Token Example

Scenario: Apple introduces a new protected folder called “Movies”. Action:

1. Update Data Only: libwaresource.dylib to include the movies token.
2. No engine update is needed.

2.2 Dynamic Token Example

Scenario: In macOS 16.x, Apple changes the location or mounting behavior for removable media. Action:

1. Update a new Engine: libwaapi.dylib, libwautils.dylib that contains updated logic to discover removable media under the new mount points.
2. Data JSON remains unchanged; the engine’s detection logic is enhanced.

2.3 Update Guidance

Depending on how you’ve configured restrict_bundle_search, the update path differs slightly:

2.3.1 Customers Using all_predefined_values

When you use all_predefined_values, this expands to all built-in tokens—both static (e.g. photos, downloads, music) and dynamic (e.g. user_home, shared_folder, removeable_media) values.

2.3.2 Customers Using Individual Tokens

When you list tokens one-by-one:

"restrict_bundle_search": "desktop|downloads|photos|user_home"

2.3.3 Engine-Update Signal

After calling wa_api_setup:

• WAAPI_OK: All listed tokens applied; no engine update needed.
• WAAPI_OK_OUTDATED_ENGINE: One or more dynamic tokens couldn’t be resolved by the current engine; plan a libwaapi.dylib, libwautils.dylib (and all relevant engine libraries) update.

This ensures you only update data for static-folder changes, and update the engine when runtime discovery logic must evolve.