CoreSpotlight.framework注釋翻譯，momospotlight

CoreSpotlight.framework注釋翻譯，momospotlight

iOS9推出了CoreSpotlight，今天沒事在家翻譯了一部分代碼裡面的注釋，這裡貼出了，後面繼續貼出實驗的文章。

聲明：本人大學四級剛過，英語水平有限，所以會有錯誤，歡迎拍磚。

關於CoreSpotlight的介紹，請讀者自己百度、Google。

CoreSpotlight.framework包含的檔案如下：

在上面的檔案中CSSearchableIndex，用於儲存可以被搜尋的item；CSSearchableItem，對應儲存的itmen；CSSearchableItemAttributeSet，item中儲存的相關屬性，其他得CSSearchableItemAttributeSet類別都是對應特定的搜尋內容的。

下面就貼出代碼了（只貼出翻譯的代碼 有些沒有翻譯的沒有貼出來）：

////  CSPerson.h//  CoreSpotlight////  Copyright © 2015 Apple. All rights reserved.//#import <CoreSpotlight/CSBase.h>NS_ASSUME_NONNULL_BEGINNS_CLASS_AVAILABLE(10_11, 9_0)@interface CSPerson : NSObject <NSSecureCoding,NSCopying>- (instancetype)initWithDisplayName:(nullable NSString *)displayName handles:(NSArray<NSString*> *)handles handleIdentifier:(NSString *)handleIdentifier;@property (readonly,nullable) NSString *displayName; //An optional display name for displaying this recipient 展示這個容易的一個可選的名字@property (readonly) NSArray<NSString*> *handles; //An array of contact handles, e.g. phone numbers 連絡人資訊的數組@property (readonly) NSString *handleIdentifier; //A CNContactPropertyKey to identify the type of of handle, e.g. CNContactPhoneNumbersKey 一個CNContactPropertyKey，用於標註資訊的類型@property (copy,nullable) NSString *contactIdentifier; //If the property has already been resolved, the identifier for the Contact 如果屬性已經被改變，標誌這個連絡人得標識@endNS_ASSUME_NONNULL_END

////  CSSearchableIndex.h//  CoreSpotlight////  Copyright © 2015 Apple. All rights reserved.//#import <CoreSpotlight/CSSearchableItem.h>#import <CoreSpotlight/CSBase.h>NS_ASSUME_NONNULL_BEGINCORESPOTLIGHT_EXPORT NSString * const CSIndexErrorDomain NS_AVAILABLE(10_11, 9_0);typedef NS_ENUM(NSInteger, CSIndexErrorCode) {    CSIndexErrorCodeUnknownError =                               -1,    CSIndexErrorCodeIndexUnavailableError =                   -1000, //The indexer was unavailable    CSIndexErrorCodeInvalidItemError =                        -1001, //The CSSearchableItem is invalid for some reason    CSIndexErrorCodeInvalidClientStateError =                 -1002, //The provided clientState was not valid for some reason    CSIndexErrorCodeRemoteConnectionError =                   -1003, //There was an error trying to communicate with the remote process    CSIndexErrorCodeQuotaExceeded =                           -1004, //Quota for bundle was exceeded} NS_AVAILABLE(10_11, 9_0);NS_CLASS_AVAILABLE(10_11, 9_0)@protocol CSSearchableIndexDelegate;@interface CSSearchableIndex : NSObject@property (weak,nullable) id<CSSearchableIndexDelegate> indexDelegate;+ (instancetype)defaultSearchableIndex;- (instancetype)initWithName:(NSString *)name;//Apps can set a default protection class for items in their entitlements.  You can alternately create an instance with a custom protection class to use on iOS.  It should be one of NSFileProtectionNone, NSFileProtectionComplete, NSFileProtectionCompleteUnlessOpen, or NSFileProtectionCompleteUntilFirstUserAuthentication.// App能夠在他們的許可權範圍內，為items設定一個預設的保護類。你能夠選擇使用一個在iOS自訂的的保護類建立一個執行個體。他應該是其中之一：NSFileProtectionNone, NSFileProtectionComplete, NSFileProtectionCompleteUnlessOpen, or NSFileProtectionCompleteUntilFirstUserAuthentication.- (instancetype)initWithName:(NSString *)name protectionClass:(nullable NSString *)protectionClass NS_AVAILABLE_IOS(9_0);// Call this method to add or update items in the index.// Completion handlers will be called once the data has been journaled by the index.  If the completion handler returns an error, the client should retry, as it was not journaled correctly.// reindexSearchableItemsWithIdentifiers will be called if the journaling completed successfully but the data was not able to be indexed for some reason.// 調用這個方法在index（索引）中添加更新items// Completion handlers將會在資料被記錄入index後調用一次。當資料沒有被正確得記錄的時候，這個Completion handlers返回error，用戶端應該重試。// 如果資料被正常得記錄了，但是由於某些原因資料不能被索引，reindexSearchableItemsWithIdentifiers將會被調用- (void)indexSearchableItems:(NSArray<CSSearchableItem *> *)items completionHandler:(void (^ __nullable)(NSError * __nullable error))completionHandler;// Call this method to remove items with the given identifiers from the index.// Completion handlers will be called once the data has been journaled by the index.  If the completion handler returns an error, the client should retry, as it was not journaled correctly.// reindexSearchableItemsWithIdentifiers will be called if the journaling completed successfully but the data was not able to be indexed for some reason.// 調用這個方法可以從索引裡，根據給定的identifiers刪除items// Completion handlers將會在資料被記錄入index後調用一次。當資料沒有被正確得記錄的時候，這個Completion handlers返回error，用戶端應該重試。// 如果資料被正常得記錄了，但是由於某些原因資料不能被索引，reindexSearchableItemsWithIdentifiers將會被調用- (void)deleteSearchableItemsWithIdentifiers:(NSArray<NSString *> *)identifiers completionHandler:(void (^ __nullable)(NSError * __nullable error))completionHandler;// Call this method on the index to remove any items from the index with the given domain identifiers.  The delete is recursive so if domain identifiers are of the form <account-id>.<mailbox-id>, for example, calling delete with <account-id> will items with that account and any mailbox.// 在索引上調用這個方法，將會根據給定的域標示符（domain identifiers）刪除所有得items。如果域標示符（domain identifiers）是這種格式：<account-id>.<mailbox-id>，這個刪除將會遞迴刪除。例如：調用刪除參數<account-id>，將會刪除這個賬戶下和任何郵箱的items- (void)deleteSearchableItemsWithDomainIdentifiers:(NSArray<NSString *> *)domainIdentifiers completionHandler:(void (^ __nullable)(NSError * __nullable error))completionHandler;// Call this method to delete all searchable items from the index.// 調用這個方法在索引上刪除所有的可搜素的items- (void)deleteAllSearchableItemsWithCompletionHandler:(void (^ __nullable)(NSError * __nullable error))completionHandler;@end@interface CSSearchableIndex (CSOptionalBatching)//Batching://For some clients, it may be beneficial to batch updates to the index.  Those clients can use batching and persist client state information (< 250 bytes) in the index.  That state information can be used to determine where indexing needs to resume from in case of a client crash or jetsam. Batching is supported for indexSearchableItems deleteSearchableItemsWithIdentifiers.  Persisted client state will be reset whenever deleteAllSearchableItemsWithCompletionHandler is called.// 對於一些使用者，批次更新所以將會非常便利。使用者可以使用大量操作持久化使用者的狀態資訊在索引中。如果用戶端crash或者退出，這些狀態資訊用於決定索引應該在哪裡被喚醒（譯者註：可能翻譯的有問題）。批處理可以支援indexSearchableItems、deleteSearchableItemsWithIdentifiers。當調用deleteAllSearchableItemsWithCompletionHandler方法時候，持久化用戶端狀態將會被重設。//Note: Batching is unsupported for the CSSearchableIndex returned by the defaultSearchableIndex method//Note: 對於通過defaultSearchableIndex方法擷取的CSSearchableIndex不支援批處理//Thread safety: In batch mode, the client takes responsibility for protecting the private CSSearchableIndex instance from concurrent access from multiple threads. Concurrent calls to the index instance will have undefined results. beginIndexBatch must not be called again before endIndexBatchWithClientState:completionHandler: has returned (it is however safe to call before the completionHandler passed to endIndexBatchWithClientState:completionHandler has been called).// 安全執行緒：在批處理模式下，用戶端負責保護私人的CSSearchableIndex，處理多線程的同時訪問。同時訪問索引執行個體將會有未定義的結果。beginIndexBatch不能在endIndexBatchWithClientState:completionHandler:還沒有返回結果前調用。//Begin a batch of index adds, updates, or deletes.// 開始批出index添加、更新、刪除- (void)beginIndexBatch;//End a batch passing in client state information to be persisted in the index.  The completion handler will be called once the client state has been persisted.// 結束一個批處理，傳入用戶端狀態資訊在index中去做持久化。completion handler將會在用戶端狀態被持久化結束後調用一次。- (void)endIndexBatchWithClientState:(NSData *)clientState completionHandler:(void (^ __nullable)(NSError * __nullable error))completionHandler;// Async fetches the app's last stored client state information.// 非同步擷取App的最後儲存的用戶端狀態資訊。- (void)fetchLastClientStateWithCompletionHandler:(void (^)(NSData * __nullable clientState,NSError * __nullable error))completionHandler;@end//An application that is long running should provide a CSSearchableIndexDelegate conforming object to handle communication from the index.//Alternatively, an app can provide an extension whose request handler conforms to this protocol and the extension will be called if the app isn't running.// 一個長時間啟動並執行應用程式，應該提供一個CSSearchableIndexDelegate對象，處理index相關的聯絡。@protocol CSSearchableIndexDelegate <NSObject>@required// The index requests that the delegate should reindex all of its searchable data and clear any local state that it might have persisted because the index has been lost.// 索引請求這個代理重新索引所有可搜尋的資料，並且清除任何本地狀態（可能該狀態已經被持久化），因為索引已經丟失了。// The app or extension should call indexSearchableItems on the passed in CSSearchableIndex.// The app or extension must call the acknowledgement handler once any client state information has been persisted, that way, in case of a crash, the indexer can call this again.// If the app passes clientState information in a batch, the acknowledgement can be called right away.// The passed in index shouldn't be used in an extension if a custom protection class is needed.- (void)searchableIndex:(CSSearchableIndex *)searchableIndex reindexAllSearchableItemsWithAcknowledgementHandler:(void (^)(void))acknowledgementHandler;// The index requests that the delegate should reindex the searchable data with the provided identifiers.// 根據給定的identifiers重新索引可搜尋的資料// The app or extension should call indexSearchableItems:completionHandler on the passed in index CSSearchableIndex to update the items' states.// The app or extension must call the acknowledgement handler once any client state information has been persisted, that way, in case of a crash, the indexer can call this again.// If the app passes clientState information in a batch, the acknowledgement can be called right away.// The passed in index shouldn't be used in an extension if a custom protection class is needed.- (void)searchableIndex:(CSSearchableIndex *)searchableIndex reindexSearchableItemsWithIdentifiers:(NSArray <NSString *> *)identifiers acknowledgementHandler:(void (^)(void))acknowledgementHandler;@endNS_ASSUME_NONNULL_END

////  CSSearchableItem.h//  CoreSpotlight////  Copyright © 2015 Apple. All rights reserved.//#import <CoreSpotlight/CSBase.h>#import <CoreSpotlight/CSSearchableItemAttributeSet.h>NS_ASSUME_NONNULL_BEGIN// When opening a document from Spotlight, the application's application:willContinueUserActivityWithType:// method will get called with CSSearchableItemActionType, followed by  application:continueUserActivity:restorationHandler: with an NSUserActivity where the userInfo dictionary has a single key value pair where CSSearchableItemActivityIdentifier is the key and the value is the uniqueIdentifier used when creating the item.// 當從Spotlight開啟一個文檔的時候，application的application:willContinueUserActivityWithType方法CORESPOTLIGHT_EXPORT NSString * const CSSearchableItemActionType;CORESPOTLIGHT_EXPORT NSString * const CSSearchableItemActivityIdentifier;NS_CLASS_AVAILABLE(10_11, 9_0)@interface CSSearchableItem : NSObject <NSSecureCoding, NSCopying>- (instancetype)initWithUniqueIdentifier:(nullable NSString *)uniqueIdentifier //Can be null, one will be generated                        domainIdentifier:(nullable NSString *)domainIdentifier                            attributeSet:(CSSearchableItemAttributeSet *)attributeSet;// Should be unique to your application group.// 在你的應用程式群組中，這個應該是唯一值// REQUIRED since this is the way you will refer to the item to update the index / delete it from the index// 必須的 由於這個是你在索引中更新、刪除索引的標識// Starts with an UUID for ease of use, but you can replace it with an UID of your own before the item is first indexed if you wish.// 使用UUID在這裡是一個簡單的方法。如果你希望，你也可以在第一次索引前使用你自己定義的UID。@property (copy) NSString *uniqueIdentifier;// An optional identifier that represents the "domain" or owner of this item.// 一個可選的identifier，用來標識item的域（"domain"）或者所有者// This might be an identifier for a mailbox in an account whose indexed data you may want to remove when the account is deleted.// 這個可能用一個賬戶的郵箱作為identifier來索引資料，並且當賬戶刪除的時候可以根據這個來刪除資料。// In that case the domainIdentifier should be of the form <account-id>.<mailbox-id> where <account-id> and <mailbox-id> should not contains periods.// 一般情況下domainIdentifier應該是這種格式<account-id>.<mailbox-id>，並且不能含有時間// Calling deleteSearchableItemsWithDomainIdentifiers with <acconut-id>.<mailbox-id> will delete all items with that domain identifier.// 帶參數<acconut-id>.<mailbox-id>調用deleteSearchableItemsWithDomainIdentifiers，將會刪除這個domain identifier下的所有items// Calling deleteSearchableItemsWithDomainIdentifiers with <acconut-id> will delete all items with <account-id> and any <mailbox-id>.// 單參數<acconut-id>調用deleteSearchableItemsWithDomainIdentifiers將會刪除<account-id>和任何<mailbox-id>的items@property (copy, nullable) NSString *domainIdentifier;// Searchable items have an expiration date or time to live.  By default it's set to 1 month.// 可搜尋的items失效時間，預設一個月@property (copy, null_resettable) NSDate * expirationDate;// Set of attributes containing meta data for the item// 設定itme attributes包含的中繼資料@property (strong) CSSearchableItemAttributeSet *attributeSet;@endNS_ASSUME_NONNULL_END

////  CSSearchableItemAttributeSet.h//  CoreSpotlight////  Copyright © 2015 Apple. All rights reserved.//#import <Foundation/Foundation.h>#import <CoreSpotlight/CSBase.h>#import <CoreSpotlight/CSPerson.h>NS_ASSUME_NONNULL_BEGINNS_CLASS_AVAILABLE(10_11, 9_0)// CSSearchableItemAttribute encapsulates a set of properties of an CSSearchableItem.// CSSearchableItemAttribute set should only be mutated from one thread at a time. Concurrent access to properties has undefined behavior.// CSSearchableItemAttribute包含CSSearchableItem一系列的屬性@interface CSSearchableItemAttributeSet : NSObject <NSCopying,NSSecureCoding>//Creates an attribute set for the given content type.// 根據給定的類型，建立一個attribute set- (instancetype)initWithItemContentType:(nonnull NSString *)itemContentType;@end//CSLocalizedString can be used in place of NSString to support localization//CSLocalizedString能夠在NSString需要使用國際化的時候使用@interface CSLocalizedString : NSString//Takes a dictionary of preferred codes to the localized string for that language// 通過一個包含語言本地碼的字典建立- (instancetype)initWithLocalizedStrings:(NSDictionary *)localizedStrings;//Returns the localized string for the current language// 返回當前語言的本地化字串- (NSString *)localizedString;@end//CSCustomAttributeKey allows you to specify a custom attribute as well as various other properties of that attribute.//CSCustomAttributeKey允許你指定自訂的attribute，和attribute的propertiesNS_CLASS_AVAILABLE(10_11, 9_0)@interface CSCustomAttributeKey : NSObject <NSCopying,NSSecureCoding>//Key names should be ASCII only, with no punctuation other than '_'.// key的名字必須是ASCII，並且不能包含處理'_'的標點符號//It is recommended keys be of the form "com_mycompany_myapp_keyname"// 建議key的形式是”com_mycompany_myapp_keyname“//Keys starting with 'kMD' are reserved.// 以'kMD'開頭得key時保留的- (nullable instancetype)initWithKeyName:(NSString *)keyName;- (nullable instancetype)initWithKeyName:(NSString *)keyName                              searchable:(BOOL)searchable                     searchableByDefault:(BOOL)searchableByDefault                                  unique:(BOOL)unique                             multiValued:(BOOL)multiValued NS_DESIGNATED_INITIALIZER;@property (readonly) NSString *keyName;//Can this attribute be searched on? By default, YES// 這個attribute能否被搜到，預設YES@property (readonly,getter=isSearchable) BOOL searchable;//Is this property searchable by default? By default, NO// property能否被搜尋到 預設為NO@property (readonly, getter=isSearchableByDefault) BOOL searchableByDefault;//Should values be uniqued to save storage? By default, NO. Set this to YES when there is a small set of known values, or values are likely to be frequently repeating for other reasons.// 值儲存的時候是否應該唯一，預設NO。當你知道只有少量的已知的值得時候，設定為YES，或者某些原因值經常被重複。@property (readonly, getter=isUnique) BOOL unique;//Is this attribute expecting multiple values to be associated with it, i.e. are values arrays?  By default, NO// 這個attribute是否希望多個值與它關聯，比如是一個值數組，預設NO@property (readonly, getter=isMultiValued) BOOL multiValued;@end//Use these methods to set custom attributes on an attribute set// 使用這些方法在attribute set上設定自訂的attribute//Values must be common plist types (NSString,NSNumber,NSNull,NSData,NSDate) or CSPerson, or arrays (NSArray) of these types.// 值必須是plist能儲存的類型、CSPerson或者array，這三種類型。@interface CSSearchableItemAttributeSet (CSCustomAttributes)- (void)setValue:(nullable id<NSSecureCoding>)value forCustomKey:(CSCustomAttributeKey *)key;- (nullable id<NSSecureCoding>)valueForCustomKey:(CSCustomAttributeKey *)key;@end//Attributes to be indexed for a given NSUserActivity// 根據給定的NSUserActivity，索引Attributes@interface NSUserActivity (CSSearchableItemAttributeSet)@property (nullable, copy) CSSearchableItemAttributeSet *contentAttributeSet;@endNS_ASSUME_NONNULL_END#ifndef CoreSpotlightAPIVersion#import <CoreSpotlight/CSSearchableItemAttributeSet_Categories.h>#endif

////  CSSearchableItemAttributeSet_General.h//  CoreSpotlight////  Copyright © 2015 Apple. All rights reserved.//#import <CoreSpotlight/CSSearchableItemAttributeSet.h>@interface CSSearchableItemAttributeSet (CSGeneral)//A localized string to be displayed in the UI for this item.// 這個item在UI中顯示的本地化字串@property(nullable, copy) NSString *displayName;//An array of localized strings of alternate display names for this item.// 這個item可選的顯示name的本地化字串的數組@property(nullable, copy) NSArray<NSString*> *alternateNames;//This is the complete path to the item.@property(nullable, copy) NSString *path;//Optional file URL representing the content to be indexed@property(nullable, strong) NSURL *contentURL;//Optional file URL pointing to a thumbnail image for this item// item中縮圖的URL@property(nullable, strong) NSURL *thumbnailURL;//Optional image data for thumbnail for this item// item中縮圖的image data@property(nullable, copy) NSData *thumbnailData;//For activities, this is the unique identifier for the item this activity is related to// 對於activities，這個是該item跟這個activity關聯的unique identifier@property(nullable, copy) NSString *relatedUniqueIdentifier;//This is the date that the last metadata attribute was changed.// 最後修改時間@property(nullable, strong) NSDate *metadataModificationDate;//UTI Type pedigree for an item.  Common types can be found in UTCoreTypes.h@property(nullable, copy) NSString *contentType;@property(nullable, copy) NSArray<NSString*> *contentTypeTree;//Represents keywords associated with this particular item.//Example Keywords might be Birthday,Important etc.@property(nullable, copy) NSArray<NSString*> *keywords;//The title of this particular item.//Title of the document, or it could be the title of this mp3 or a subject of a mail message.@property(nullable, copy) NSString *title;@end

本人水平有限，翻譯難免有錯誤，歡迎拍磚。另外本人還沒有實驗這個。後續會貼出CoreSpotlight的實驗，歡迎關注。