MacOS File and Custom URL Scheme Associations

This is an old revision of MacOS File and Custom URL Scheme Associations, edited by Trev at . The current revision is 137794.

/* See also */ Added entry

│ {{#if:{{PROTECTIONEXPIRY:edit|{{{Link|}}}}} |'''[[:{{{Link}}}|{{{Caption}}}]]''' │ }}

{{#if:{{PROTECTIONEXPIRY:edit|{{{Link|}}}}} |'''[[:{{{Link}}}|{{{Caption}}}]]''' │ }}

{{#if:{{PROTECTIONEXPIRY:edit|{{{Link|}}}}} |'''[[:{{{Link}}}|{{{Caption}}}]]''' │ }}

{{#if:{{PROTECTIONEXPIRY:edit|{{{Link|}}}}} |'''[[:{{{Link}}}|{{{Caption}}}]]''' │ }}

{{#if:{{PROTECTIONEXPIRY:edit|{{{Link|}}}}} |'''[[:{{{Link}}}|{{{Caption}}}]]''' │ }}

{{#if:{{PROTECTIONEXPIRY:edit|{{{Link|}}}}} |'''[[:{{{Link}}}|{{{Caption}}}]]''' │ }}

{{#if:{{PROTECTIONEXPIRY:edit|{{{Link|}}}}} |'''[[:{{{Link}}}|{{{Caption}}}]]''' │ }}

{{#if:{{PROTECTIONEXPIRY:edit|{{{Link|}}}}} |'''[[:{{{Link}}}|{{{Caption}}}]]''' │ }}

{{#if:{{PROTECTIONEXPIRY:edit|{{{Link|}}}}} |'''[[:{{{Link}}}|{{{Caption}}}]]''' │ }}

{{#if:{{PROTECTIONEXPIRY:edit|{{{Link|}}}}} |'''[[:{{{Link}}}|{{{Caption}}}]]''' │ }}

{{#if:{{PROTECTIONEXPIRY:edit|{{{Link|}}}}} |'''[[:{{{Link}}}|{{{Caption}}}]]''' │ }}

{{#if:{{PROTECTIONEXPIRY:edit|{{{Link|}}}}} |'''[[:{{{Link}}}|{{{Caption}}}]]''' │ }}

{{#if:{{PROTECTIONEXPIRY:edit|{{{Link|}}}}} |'''[[:{{{Link}}}|{{{Caption}}}]]''' │ }}

{{#if:{{PROTECTIONEXPIRY:edit|{{{Link|}}}}} |'''[[:{{{Link}}}|{{{Caption}}}]]''' │ }}

{{#if:{{PROTECTIONEXPIRY:edit|{{{Link|}}}}} |'''[[:{{{Link}}}|{{{Caption}}}]]''' │ }}

{{#if:{{PROTECTIONEXPIRY:edit|{{{Link|}}}}} |'''[[:{{{Link}}}|{{{Caption}}}]]''' │ }}

{{#if:{{PROTECTIONEXPIRY:edit|{{{Link|}}}}} |'''[[:{{{Link}}}|{{{Caption}}}]]''' │ }}

{{#if:{{PROTECTIONEXPIRY:edit|{{{Link|}}}}} |'''[[:{{{Link}}}|{{{Caption}}}]]''' │ }}

{{#if:{{PROTECTIONEXPIRY:edit|{{{Link|}}}}} |'''[[:{{{Link}}}|{{{Caption}}}]]''' │ }}

{{#if:{{PROTECTIONEXPIRY:edit|{{{Link|}}}}} |'''[[:{{{Link}}}|{{{Caption}}}]]''' │ }}

{{#if:{{PROTECTIONEXPIRY:edit|{{{Link|}}}}} |'''[[:{{{Link}}}|{{{Caption}}}]]''' │ }}

{{#if:{{PROTECTIONEXPIRY:edit|{{{Link|}}}}} |'''[[:{{{Link}}}|{{{Caption}}}]]''' │ }}

{{#if:{{PROTECTIONEXPIRY:edit|{{{Link|}}}}} |'''[[:{{{Link}}}|{{{Caption}}}]]''' │ }}

{{#if:{{PROTECTIONEXPIRY:edit|{{{Link|}}}}} |'''[[:{{{Link}}}|{{{Caption}}}]]''' │ }}

{{#if:{{PROTECTIONEXPIRY:edit|{{{Link|}}}}} |'''[[:{{{Link}}}|{{{Caption}}}]]''' │ }}

{{#if:{{PROTECTIONEXPIRY:edit|{{{Link|}}}}} |'''[[:{{{Link}}}|{{{Caption}}}]]''' │ }}

{{#if:{{PROTECTIONEXPIRY:edit|{{{Link|}}}}} |'''[[:{{{Link}}}|{{{Caption}}}]]''' │ }}

{{#if:{{PROTECTIONEXPIRY:edit|{{{Link|}}}}} |'''[[:{{{Link}}}|{{{Caption}}}]]''' │ }}

{{#if:{{PROTECTIONEXPIRY:edit|{{{Link|}}}}} |'''[[:{{{Link}}}|{{{Caption}}}]]''' │ }}

{{#if:{{PROTECTIONEXPIRY:edit|{{{Link|}}}}} |'''[[:{{{Link}}}|{{{Caption}}}]]''' │ }}

{{#if:{{PROTECTIONEXPIRY:edit|{{{Link|}}}}} |'''[[:{{{Link}}}|{{{Caption}}}]]''' │ }}

This article applies to macOS only.

See also: Multiplatform Programming Guide

Work in progress...

Overview

macOS does not have a central registry like Windows to which applications explicitly write information. Instead, every application with a graphical interface has a property list file named Info.plist, roughly equivalent to a manifest in the Windows world, stored in its application bundle. The Info.plist file may optionally include file type association and custom URL scheme information.

macOS Launch Services is an API that enables a running application to open other applications or their document files in a way similar to the Finder or the Dock. Using Launch Services, an application can perform such tasks as:

Launch Services automatically registers an application with the database the first time the application becomes known to the system. This can occur when:

When you open a document or URL, Launch Services is used to determine which application should open the item. Launch Services uses the following specific order:

Identifying the type of content in a file

There are two primary techniques for identifying the type of content in a file:

A UTI is a string that uniquely identifies a class of entities considered to have a "type". UTIs provide consistent identifiers for data on which all applications and services can recognise and rely. They are also more flexible than most other techniques because you can use them to represent any type of data, not just files and directories. Examples of UTIs include:

Whenever a UTI-based interface is available for specifying file types, you should prefer that interface over any others. Many macOS interfaces allow you to specify UTIs corresponding to the files or directories you want to work with.

One way the system determines the UTI for a given file is by looking at its filename extension. A filename extension is a string of characters appended to the end of a file and separated from the main filename with a period. Each unique string of characters identifies a file of a specific type. For example, the .png extension identifies a file with image data in the portable network graphics format.

Note: Because period characters are valid characters in macOS filenames, only the characters after the last period in a filename are considered part of the filename extension. Everything to the left of the last period is considered part of the filename itself.

If your application defines custom file formats, you should register those formats and any associated filename extensions in your application's Info.plist file. The CFBundleDocumentTypes key specifies the file formats that your application recognises and is able to open. Entries for any custom file formats should include both a filename extension and UTI corresponding to the file contents. The system uses that information to direct files with the appropriate type to your application.

Simple MyEditor example application

We shall start by creating a very simple editor application to which we will add our own custom file type extension. After that is working we will then add a custom URL scheme so that other applications (eg Safari) when faced with our custom URL scheme will offer to open files in our MyEditor application.

procedure TForm1.btnOpenClick(Sender: TObject);
begin
  LoadMemo;
end;

procedure TForm1.btnSaveClick(Sender: TObject);
begin
  SaveMemo;
end;

procedure TForm1.btnQuitClick(Sender: TObject);
begin
  close;
end;
    sTmp : string;
    procedure LoadMemo;
    procedure SaveMemo;
procedure TForm1.LoadMemo;
begin
if OpenDialog1.Execute then
  sTmp:=OpenDialog1.Filename;

if FileExists(sTmp) then
  memo1.Lines.LoadFromFile(sTmp)
 else
   showmessage('File not found: ' + sTmp);
end;

procedure TForm1.SaveMemo;
begin

if SaveDialog1.Execute then
  begin
    try
      memo1.Lines.SaveToFile(SaveDialog1.FileName);
    except on EStreamError do
        showmessage('Could not save file: ' + SaveDialog1.FileName);
    end;
  end
end;
unit Unit1;

{$mode objfpc}{$H+}

interface

uses
  Classes, SysUtils, Forms, Controls, Graphics, Dialogs, StdCtrls;

type

  { TForm1 }

  TForm1 = class(TForm)
    btnOpen: TButton;
    btnSave: TButton;
    btnQuit: TButton;
    Memo1: TMemo;
    OpenDialog1: TOpenDialog;
    SaveDialog1: TSaveDialog;
    procedure btnOpenClick(Sender: TObject);
    procedure btnQuitClick(Sender: TObject);
    procedure btnSaveClick(Sender: TObject);
  private
    sTmp : string;
    procedure LoadMemo;
    procedure SaveMemo;
  public

  end;

var
  Form1: TForm1;

implementation

{$R *.lfm}

{ TForm1 }

procedure TForm1.btnOpenClick(Sender: TObject);
begin
  Form1.LoadMemo;
end;

procedure TForm1.btnSaveClick(Sender: TObject);
begin
  Form1.SaveMemo;
end;

procedure TForm1.btnQuitClick(Sender: TObject);
begin
  Form1.Close;
end;

procedure TForm1.LoadMemo;
begin
if OpenDialog1.Execute then
  sTmp:=OpenDialog1.Filename;

if FileExists(sTmp) then
  memo1.Lines.LoadFromFile(sTmp)
 else
   showmessage('File not found: ' + sTmp);
end;

procedure TForm1.SaveMemo;
begin
if SaveDialog1.Execute then
  begin
    try
      memo1.Lines.SaveToFile(SaveDialog1.FileName);
    except on EStreamError do
        showmessage('Could not save file: ' + SaveDialog1.FileName);
    end;
  end
end;

end.

Adding your own file type extension

Lazarus will have created an application bundle for our MyEditor application. Use Finder to navigate to the project directory, right-click on the bundle directory MyEditor.app and select "Show package contents". Open the Contents subdirectory and you should see: a MacOS subdirectory, a Resources subdirectory, a Pkginfo file and the application's Info.plist property list file. Open the file with TextEditor.app and the content should look very similar to this:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>CFBundleDevelopmentRegion</key>
  <string>English</string>
  <key>CFBundleExecutable</key>
  <string>MyEditor</string>
  <key>CFBundleName</key>
  <string>MyEditor</string>
  <key>CFBundleIdentifier</key>
  <string>com.company.MyEditor</string>
  <key>CFBundleInfoDictionaryVersion</key>
  <string>6.0</string>
  <key>CFBundlePackageType</key>
  <string>APPL</string>
  <key>CFBundleSignature</key>
  <string>MyEd</string>
  <key>CFBundleShortVersionString</key>
  <string>0.1</string>
  <key>CFBundleVersion</key>
  <string>1</string>
  <key>CSResourcesFileMapped</key>
  <true/>
  <key>CFBundleDocumentTypes</key>
  <array>
    <dict>
      <key>CFBundleTypeRole</key>
      <string>Viewer</string>
      <key>CFBundleTypeExtensions</key>
      <array>
        <string>*</string>
      </array>
      <key>CFBundleTypeOSTypes</key>
      <array>
        <string>fold</string>
        <string>disk</string>
        <string>****</string>
      </array>
    </dict>
  </array>
  <key>NSHighResolutionCapable</key>
  <true/>
</dict>
</plist>

We will now add our custom filename extension to the property list so that MyEditor will be the default application used to open such files. Delete the highlighted lines and insert these replacement lines:

      <string>Editor</string>
    <key>LSTypeIsPackage</key>
    <false/>
        <key>CFBundleTypeIconFile</key>
        <string>txt.icns</string>
    <key>CFBundleTypeExtensions</key>
    <array>
      <string>xyz</string>
    </array>

Save the file. You will notice that we have changed the "role" from Viewer to Editor and we have added our custom file extension.

... TO BE CONTINUED ...

See also