NSURL

Overview 概要

You can use URL objects to construct URLs and access their parts. For URLs that represent local files, you can also manipulate properties of those files directly, such as changing the file’s last modification date. Finally, you can pass URL objects to other APIs to retrieve the contents of those URLs. For example, you can use the NSURLSession, NSURLConnection, and NSURLDownload classes to access the contents of remote resources, as described in URL Loading System. あなたはURLオブジェクトを使って、URLを構築することそしてそれらの一部にアクセスすることができます。ローカルファイルを表すURLに対しては、あなたはまたそれらのファイルのプロパティを直接に操作できます、例えばファイルの持つ最終修正日を変更するなど。最終的に、あなたはURLオブジェクトを他のAPIに渡すことで、それらURLの内容を回収できます。例えば、あなたはNSURLSession、NSURLConnection、そしてNSURLDownloadクラスを使って、遠隔のリソースの内容にアクセスできます、URL Loading Systemで記述されるように。

URL objects are the preferred way to refer to local files. Most objects that read data from or write data to a file have methods that accept an NSURL object instead of a pathname as the file reference. For example, you can get the contents of a local file URL as an NSString object using the initWithContentsOfURL:encoding:error: initializer, or as an NSData object using the initWithContentsOfURL:options:error: initializer. URLオブジェクトは、ローカルのファイルを参照する好ましい方法です。ファイルからデータを読み出すまたはそれへと書き込むほとんどのオブジェクトは、NSURLオブジェクトをパス名の代わりにファイル参照として受け入れるメソッドを持ちます。例えば、あなたはローカルファイルURLの内容を得ることが、NSStringオブジェクトとしてinitWithContentsOfURL:encoding:error:イニシャライザを使って、またはNSDataオブジェクトとしてinitWithContentsOfURL:options:error:イニシャライザを使って可能です。

You can also use URLs for interapplication communication. In macOS, the NSWorkspace class provides the openURL: method to open a location specified by a URL. Similarly, in iOS, the UIApplication class provides the openURL:options:completionHandler: method. あなたはまた、URLをアプリケーション間通信に使うことができます。macOSでは、NSWorkspaceクラスはopenURL:メソッドを提供してあるURLによって指定される場所を開きます。同様に、iOSでは、UIApplicationクラスはopenURL:options:completionHandler:メソッドを提供します。

Additionally, you can use URLs when working with pasteboards, as described in NSURL Additions Reference (part of the AppKit framework). 加えて、あなたはURLをペーストボードを扱う時に使用できます、NSURL Additions Reference（AppKitフレームワークの部分）で記述されるように。

The NSURL class is “toll-free bridged” with its Core Foundation counterpart, CFURLRef. See Toll-Free Bridging for more information on toll-free bridging. NSURLクラスは、それのCore Foundation相当物CFURLRefと「トールフリーブリッジ」されます。トールフリーブリッジに関する更なる情報としてToll-Free Bridgingを見てください。

Structure of a URL URLの構造

An NSURL object is composed of two parts—a potentially nil base URL and a string that is resolved relative to the base URL. An NSURL object is considered absolute if its string part is fully resolved without a base; all other URLs are considered relative. NSURLオブジェクトは２つの部分で構成されます — もしかするとnilかもしれない基準URLと、その基準URLに対して相対的に解決される文字列。NSURLオブジェクトは絶対的とみなされます、もしそれの文字列部分がある基準なしに完全に解決されるならば；全ての他のURLは相対的とみなされます。

For example, when constructing an NSURL object, you might specify file:///path/to/user/ as the base URL and folder/file.html as the string part, as follows: 例えば、あるNSURLオブジェクトを組み立てるとき、あなたはfile:///path/to/user/を基準URLとしてそしてfolder/file.htmlを文字列の部分として指定するかもしれません、次のように：

NSURL *baseURL = [NSURL fileURLWithPath:@"file:///path/to/user/"];
NSURL *URL = [NSURL URLWithString:@"folder/file.html" relativeToURL:baseURL];
NSLog(@"absoluteURL = %@", [URL absoluteURL]);

When fully resolved, the absolute URL is file:///path/to/user/folder/file.html. 完全に解決される場合、絶対URLはfile:///path/to/user/folder/file.htmlです。

A URL can be also be divided into pieces based on its structure. For example, the URL https://johnny:p4ssw0rd@www.example.com:443/script.ext;param=value?query=value#ref contains the following URL components: あるURLはまた、それの構造に基づいて断片へと分割されることができます。例えば、URL https://johnny:p4ssw0rd@www.example.com:443/script.ext;param=value?query=value#refは以下のURL構成要素を含みます：

The NSURL class provides properties that let you examine each of these components. NSURLクラスは、プロパティいくらかを提供します、それらはあなたにこれら構成要素の各々を調べさせます。

Bookmarks and Security Scope ブックマークとセキュリティスコープ

Starting with OS X v10.6 and iOS 4.0, the NSURL class provides a facility for creating and using bookmark objects. A bookmark provides a persistent reference to a file-system resource. When you resolve a bookmark, you obtain a URL to the resource’s current location. A bookmark’s association with a file-system resource (typically a file or folder) usually continues to work if the user moves or renames the resource, or if the user relaunches your app or restarts the system. OS X 10.6とiOS 4.0から、NSURLクラスはブックマークオブジェクトの作成と利用に対する便宜を提供します。ブックマークは、あるファイルシステムリソースに対する永続的な参照を提供します。あなたがあるブックマークを解決する時、あなたはそのリソースの現在の位置に対するURLを入手します。あるブックマークの持つファイルシステムリソース（概してファイルまたはフォルダ）とのつながりは、通常は継続して働きます、ユーザがそのリソースを移動または改名するとしても、またはユーザがあなたのアプリを再起動するまたはシステムを再始動するとしても。

For a general introduction to using bookmarks, read Locating Files Using Bookmarks in File System Programming Guide. ブックマークを使うことに対する概括的な導入として、Locating Files Using BookmarksをFile System Programming Guideで見てください。

In a macOS app that adopts App Sandbox, you can use security-scoped bookmarks to gain access to file-system resources outside your app’s sandbox. These bookmarks preserve the user’s intent to give your app access to a resource across app launches. For details on how this works, including information on the entitlements you need in your Xcode project, read Security-Scoped Bookmarks and Persistent Resource Access in App Sandbox Design Guide. The methods for using security-scoped bookmarks are described in this document in Working with Bookmark Data. App Sandboxを採用するmacOSアプリでは、あなたは保安作用域ブックマークを使って、ファイルシステムリソースに対するアクセスを、あなたのアプリのサンドボックスの外側で獲得できます。これらのブックマークは、ユーザの意図を保全してあなたのアプリにアプリの起動を越えて、あるリソースに対するアクセスを与えます。どのようにこれが働くかに関する詳細として、含めてあなたのXcodeプロジェクトにおいてあなたが必要とする資格付与に関する情報を、Security-Scoped Bookmarks and Persistent Resource AccessをApp Sandbox Design Guideで見てください。保安作用域ブックマークを使うためのメソッドは、この文書においてブックマークデータを扱うで記述されます。

When you resolve a security-scoped bookmark, you get a security-scoped URL. あなたが保安作用域ブックマークを解決する時、あなたはある保安作用域URLを得ます。

Security-Scoped URLs 保安作用域URL

Security-scoped URLs provide access to resources outside an app’s sandbox. In macOS, you get access to security-scoped URLs when you resolve a security-scoped bookmark. In iOS, apps that open or move documents using a UIDocumentPickerViewController also receive security-scoped URLs. 保安作用域URLは、リソースに対するアクセスをアプリのサンドボックスの外側で提供します。macOSでは、あなたは保安作用域URLに対するアクセスを、あなたが保安作用域ブックマークを解決する時に得ます。iOSでは、書類を開くまたは移動するをUIDocumentPickerViewControllerを使って行うアプリも同様に、保安作用域URLを受け取ります。

To gain access to a security-scoped URL, you must call the startAccessingSecurityScopedResource method (or its Core Foundation equivalent, the CFURLStartAccessingSecurityScopedResource function). For iOS apps, if you use a UIDocument to access the URL, it automatically manages the security-scoped URL for you. 保安作用域URLへのアクセスを入手するには、あなたはstartAccessingSecurityScopedResourceメソッド（またはそれのCore Foundation相当物、CFURLStartAccessingSecurityScopedResource関数）を呼び出さなければなりません。iOSアプリに対して、あなたがUIDocumentを使ってURLにアクセスするならば、それは自動的に保安作用域URLをあなたの代わりに管理します。

If startAccessingSecurityScopedResource (or CFUrLStartAccessingSecurityScopedResource) returns YES, you must relinquish your access by calling the stopAccessingSecurityScopedResource method (or its Core Foundation equivalent, the CFURLStopAccessingSecurityScopedResource function). You should relinquish your access as soon as you have finished using the file. After you call these methods, you immediately lose access to the resource in question. startAccessingSecurityScopedResource（またはCFUrLStartAccessingSecurityScopedResource）がYESを返すならば、あなたはあなたのアクセスをstopAccessingSecurityScopedResourceメソッド（またはそれのCore Foundation相当物、CFURLStopAccessingSecurityScopedResource関数）を呼び出すことによって放棄しなければなりません。あなたは、あなたのアクセスをあなたがファイルの使用を完了するやいなや放棄すべきです。あなたがこのメソッドを呼び出した後、あなたは直ぐに当該のリソースへのアクセスを失います。

Security-Scoped URLs and String Paths 保安作用域URLと文字列パス

In a macOS app, when you copy a security-scoped URL, the copy has the security scope of the original. You gain access to the file-system resource (that the URL points to) just as you would with the original URL: by calling the startAccessingSecurityScopedResource method (or its Core Foundation equivalent). macOSアプリでは、あなたが保安作用域URLをコピーする場合、そのコピーは元の保安作用域を持ちます。あなたはファイルシステムリソース（そのURLが指し示すもの）へのアクセスをきっかりあなたが元のURLでするように獲得します：startAccessingSecurityScopedResourceメソッド（またはそれのCore Foundation相当物）を呼び出すことによって。

If you need a security-scoped URL’s path as a string value (as provided by the path method), such as to provide to an API that requires a string value, obtain the path from the URL as needed. Note, however, that a string-based path obtained from a security-scoped URL does not have security scope and you cannot use that string to obtain access to a security-scoped resource. あなたが保安作用域URLの持つパスを文字列値（pathメソッドによって提供されるように）として必要とするならば、例えば文字列値を要求するAPIに提供するためなど、パスをURLから必要に応じて入手してください。しかしながら、保安作用域URLから入手された文字列に基づくパスは保安作用域を持っていないそしてあなたはその文字列を使って保安作用域リソースにアクセスできないことに注意してください。

iCloud Document Thumbnails iCloud書類サムネール

With OS X v10.10 and iOS 8.0, the NSURL class includes the ability to get and set document thumbnails as a resource property for iCloud documents. You can get a dictionary of NSImage objects in macOS or UIImage objects in iOS using the getResourceValue:forKey:error: or getPromisedItemResourceValue:forKey:error: methods. OS X 10.10そしてiOS 8.0では、NSURLクラスは、書類サムネールをリソースプロパティとしてiCloud書類に対して取得および設定する能力を含みます。あなたは、macOSではNSImageオブジェクトまたはiOSではUIImageオブジェクトからなる辞書を取得することがgetResourceValue:forKey:error:またはgetPromisedItemResourceValue:forKey:error:メソッドを使って行えます。

NSURL *URL = [self URLForDocument];
NSDictionary *thumbnails = nil;
NSError *error = nil;
 
BOOL success = [URL getPromisedItemResourceValue:&thumbnails
                                          forKey:NSURLThumbnailDictionaryKey
                                           error:&error];
if (success) {
  NSImage *image = thumbnails[NSThumbnail1024x1024SizeKey];
} else {
  // handle the error
}

In macOS, you can set a dictionary of thumbnails using the setResourceValue:forKey:error: method. You can also get or set all the thumbnails as an NSImage object with multiple representations by using the NSURLThumbnailKey. macOSでは、あなたはサムネールいくらかからなるひとつの辞書をsetResourceValue:forKey:error:メソッドを使って設定できます。あなたはまた、サムネール全てを複数の表現を持つひとつのNSImageオブジェクトとしてNSURLThumbnailKeyを使うことで取得および設定できます。

NSURL *URL = [self URLForDocument];
NSImage *thumbnail = [self createDocumentThumbnail];
NSError *error = nil;
 
BOOL success = [URL setResourceValue:@{NSThumbnail1024x1024SizeKey : thumbnail}
                              forKey:NSURLThumbnailDictionaryKey
                               error:&error];
 
if (!success) {
  // handle the error
}