PageRenderTime 71ms CodeModel.GetById 33ms RepoModel.GetById 0ms app.codeStats 0ms

/packages/univint/src/MDQuery.pas

https://github.com/kpowick/freepascal
Pascal | 1271 lines | 73 code | 82 blank | 1116 comment | 0 complexity | ee70ce059bb0a47637e002473a074455 MD5 | raw file
Possible License(s): GPL-2.0, LGPL-2.0, LGPL-2.1, LGPL-3.0, BSD-3-Clause

Large files files are truncated, but you can click here to view the full file

  1. { MDQuery.h
  2. Copyright (c) 2003-2005, Apple Computer, Inc. All rights reserved.
  3. }
  4. { Pascal Translation: Gorazd Krosl <gorazd_1957@yahoo.ca>, October 2009 }
  5. { Pascal Translation Updated: Jonas Maebe <jonas@freepascal.org>, September 2012 }
  6. {
  7. Modified for use with Free Pascal
  8. Version 308
  9. Please report any bugs to <gpc@microbizz.nl>
  10. }
  11. {$ifc not defined MACOSALLINCLUDE or not MACOSALLINCLUDE}
  12. {$mode macpas}
  13. {$packenum 1}
  14. {$macro on}
  15. {$inline on}
  16. {$calling mwpascal}
  17. unit MDQuery;
  18. interface
  19. {$setc UNIVERSAL_INTERFACES_VERSION := $0400}
  20. {$setc GAP_INTERFACES_VERSION := $0308}
  21. {$ifc not defined USE_CFSTR_CONSTANT_MACROS}
  22. {$setc USE_CFSTR_CONSTANT_MACROS := TRUE}
  23. {$endc}
  24. {$ifc defined CPUPOWERPC and defined CPUI386}
  25. {$error Conflicting initial definitions for CPUPOWERPC and CPUI386}
  26. {$endc}
  27. {$ifc defined FPC_BIG_ENDIAN and defined FPC_LITTLE_ENDIAN}
  28. {$error Conflicting initial definitions for FPC_BIG_ENDIAN and FPC_LITTLE_ENDIAN}
  29. {$endc}
  30. {$ifc not defined __ppc__ and defined CPUPOWERPC32}
  31. {$setc __ppc__ := 1}
  32. {$elsec}
  33. {$setc __ppc__ := 0}
  34. {$endc}
  35. {$ifc not defined __ppc64__ and defined CPUPOWERPC64}
  36. {$setc __ppc64__ := 1}
  37. {$elsec}
  38. {$setc __ppc64__ := 0}
  39. {$endc}
  40. {$ifc not defined __i386__ and defined CPUI386}
  41. {$setc __i386__ := 1}
  42. {$elsec}
  43. {$setc __i386__ := 0}
  44. {$endc}
  45. {$ifc not defined __x86_64__ and defined CPUX86_64}
  46. {$setc __x86_64__ := 1}
  47. {$elsec}
  48. {$setc __x86_64__ := 0}
  49. {$endc}
  50. {$ifc not defined __arm__ and defined CPUARM}
  51. {$setc __arm__ := 1}
  52. {$elsec}
  53. {$setc __arm__ := 0}
  54. {$endc}
  55. {$ifc defined cpu64}
  56. {$setc __LP64__ := 1}
  57. {$elsec}
  58. {$setc __LP64__ := 0}
  59. {$endc}
  60. {$ifc defined __ppc__ and __ppc__ and defined __i386__ and __i386__}
  61. {$error Conflicting definitions for __ppc__ and __i386__}
  62. {$endc}
  63. {$ifc defined __ppc__ and __ppc__}
  64. {$setc TARGET_CPU_PPC := TRUE}
  65. {$setc TARGET_CPU_PPC64 := FALSE}
  66. {$setc TARGET_CPU_X86 := FALSE}
  67. {$setc TARGET_CPU_X86_64 := FALSE}
  68. {$setc TARGET_CPU_ARM := FALSE}
  69. {$setc TARGET_OS_MAC := TRUE}
  70. {$setc TARGET_OS_IPHONE := FALSE}
  71. {$setc TARGET_IPHONE_SIMULATOR := FALSE}
  72. {$setc TARGET_OS_EMBEDDED := FALSE}
  73. {$elifc defined __ppc64__ and __ppc64__}
  74. {$setc TARGET_CPU_PPC := FALSE}
  75. {$setc TARGET_CPU_PPC64 := TRUE}
  76. {$setc TARGET_CPU_X86 := FALSE}
  77. {$setc TARGET_CPU_X86_64 := FALSE}
  78. {$setc TARGET_CPU_ARM := FALSE}
  79. {$setc TARGET_OS_MAC := TRUE}
  80. {$setc TARGET_OS_IPHONE := FALSE}
  81. {$setc TARGET_IPHONE_SIMULATOR := FALSE}
  82. {$setc TARGET_OS_EMBEDDED := FALSE}
  83. {$elifc defined __i386__ and __i386__}
  84. {$setc TARGET_CPU_PPC := FALSE}
  85. {$setc TARGET_CPU_PPC64 := FALSE}
  86. {$setc TARGET_CPU_X86 := TRUE}
  87. {$setc TARGET_CPU_X86_64 := FALSE}
  88. {$setc TARGET_CPU_ARM := FALSE}
  89. {$ifc defined(iphonesim)}
  90. {$setc TARGET_OS_MAC := FALSE}
  91. {$setc TARGET_OS_IPHONE := TRUE}
  92. {$setc TARGET_IPHONE_SIMULATOR := TRUE}
  93. {$elsec}
  94. {$setc TARGET_OS_MAC := TRUE}
  95. {$setc TARGET_OS_IPHONE := FALSE}
  96. {$setc TARGET_IPHONE_SIMULATOR := FALSE}
  97. {$endc}
  98. {$setc TARGET_OS_EMBEDDED := FALSE}
  99. {$elifc defined __x86_64__ and __x86_64__}
  100. {$setc TARGET_CPU_PPC := FALSE}
  101. {$setc TARGET_CPU_PPC64 := FALSE}
  102. {$setc TARGET_CPU_X86 := FALSE}
  103. {$setc TARGET_CPU_X86_64 := TRUE}
  104. {$setc TARGET_CPU_ARM := FALSE}
  105. {$setc TARGET_OS_MAC := TRUE}
  106. {$setc TARGET_OS_IPHONE := FALSE}
  107. {$setc TARGET_IPHONE_SIMULATOR := FALSE}
  108. {$setc TARGET_OS_EMBEDDED := FALSE}
  109. {$elifc defined __arm__ and __arm__}
  110. {$setc TARGET_CPU_PPC := FALSE}
  111. {$setc TARGET_CPU_PPC64 := FALSE}
  112. {$setc TARGET_CPU_X86 := FALSE}
  113. {$setc TARGET_CPU_X86_64 := FALSE}
  114. {$setc TARGET_CPU_ARM := TRUE}
  115. { will require compiler define when/if other Apple devices with ARM cpus ship }
  116. {$setc TARGET_OS_MAC := FALSE}
  117. {$setc TARGET_OS_IPHONE := TRUE}
  118. {$setc TARGET_IPHONE_SIMULATOR := FALSE}
  119. {$setc TARGET_OS_EMBEDDED := TRUE}
  120. {$elsec}
  121. {$error __ppc__ nor __ppc64__ nor __i386__ nor __x86_64__ nor __arm__ is defined.}
  122. {$endc}
  123. {$ifc defined __LP64__ and __LP64__ }
  124. {$setc TARGET_CPU_64 := TRUE}
  125. {$elsec}
  126. {$setc TARGET_CPU_64 := FALSE}
  127. {$endc}
  128. {$ifc defined FPC_BIG_ENDIAN}
  129. {$setc TARGET_RT_BIG_ENDIAN := TRUE}
  130. {$setc TARGET_RT_LITTLE_ENDIAN := FALSE}
  131. {$elifc defined FPC_LITTLE_ENDIAN}
  132. {$setc TARGET_RT_BIG_ENDIAN := FALSE}
  133. {$setc TARGET_RT_LITTLE_ENDIAN := TRUE}
  134. {$elsec}
  135. {$error Neither FPC_BIG_ENDIAN nor FPC_LITTLE_ENDIAN are defined.}
  136. {$endc}
  137. {$setc ACCESSOR_CALLS_ARE_FUNCTIONS := TRUE}
  138. {$setc CALL_NOT_IN_CARBON := FALSE}
  139. {$setc OLDROUTINENAMES := FALSE}
  140. {$setc OPAQUE_TOOLBOX_STRUCTS := TRUE}
  141. {$setc OPAQUE_UPP_TYPES := TRUE}
  142. {$setc OTCARBONAPPLICATION := TRUE}
  143. {$setc OTKERNEL := FALSE}
  144. {$setc PM_USE_SESSION_APIS := TRUE}
  145. {$setc TARGET_API_MAC_CARBON := TRUE}
  146. {$setc TARGET_API_MAC_OS8 := FALSE}
  147. {$setc TARGET_API_MAC_OSX := TRUE}
  148. {$setc TARGET_CARBON := TRUE}
  149. {$setc TARGET_CPU_68K := FALSE}
  150. {$setc TARGET_CPU_MIPS := FALSE}
  151. {$setc TARGET_CPU_SPARC := FALSE}
  152. {$setc TARGET_OS_UNIX := FALSE}
  153. {$setc TARGET_OS_WIN32 := FALSE}
  154. {$setc TARGET_RT_MAC_68881 := FALSE}
  155. {$setc TARGET_RT_MAC_CFM := FALSE}
  156. {$setc TARGET_RT_MAC_MACHO := TRUE}
  157. {$setc TYPED_FUNCTION_POINTERS := TRUE}
  158. {$setc TYPE_BOOL := FALSE}
  159. {$setc TYPE_EXTENDED := FALSE}
  160. {$setc TYPE_LONGLONG := TRUE}
  161. uses MacTypes,CFBase,CFString,CFDictionary,CFArray,MDItem,MacOSXPosix;
  162. {$endc} {not MACOSALLINCLUDE}
  163. {$ifc TARGET_OS_MAC}
  164. {$ALIGN POWER}
  165. {!
  166. @header MDQuery
  167. MDQuery is a CF-compliant object, and follows the CF conventions,
  168. and can be used with the CF polymorphic functions, like CFRetain().
  169. MDQuery encapsulates all queries against the MetaData
  170. database. Queries gather results or process updates only while
  171. the current thread's run loop is running. Queries normally
  172. operate asynchronously, and only send out progress
  173. notificiations as the list is being collected. The query list
  174. is kept up to date with respect to value lists and sorting as
  175. the progress notifications are sent out, so the query is in a
  176. good state during those events.
  177. Result Retreval
  178. An MDQueryRef presents its results as if it were a simple
  179. array object. The results can either be MDItemRefs (the
  180. default) or custom structs, CFTypeRefs, or Objective C
  181. objects. For example if the result objects are represented
  182. as 'FSNodes' (a type defined in the client application) a
  183. call to MDQueryGetResultAtIndex() will return an FSNode
  184. object. This is useful, because it allows the Metadata
  185. library to maintain the results in a form that is directly
  186. useable in the application.
  187. Query Sorting
  188. Sorting the results from a query can be performed in one of
  189. two ways. First is to let the library sort the results for you
  190. by passing an array of attributes to sort on to
  191. MDQueryCreate(). The default sort provided by MDQueryCreate()
  192. is a assending sort strings are compared using
  193. CFStringCompare() with the options kCFCompareNonliteral |
  194. kCFCompareLocalized | kCFCompareNumerically. CFDataRefs are
  195. compared by using memcmp() of the data pointers. If an Item
  196. does not have the attribute, it compares less than the
  197. attribute that is there.
  198. If you need to do a more complex sort (like a case insensitive
  199. sort on CFStringRefs) then you will need to also provide a
  200. comparitor function and call MDQuerySetSortComparator(), and
  201. also provide which attributes to sort on to MDQueryCreate().
  202. Undefined Behavior
  203. For functions which take an MDQueryRef parameter, if this
  204. parameter is not a valid MDQueryRef, the behavior is
  205. undefined. NULL is not a valid MDQueryRef.
  206. For functions which take CF*Ref parameters, such as
  207. CFStringRef and CFArrayRef, if this parameter is not a
  208. valid CF object of the correct type, the behavior is
  209. undefined. NULL is not a valid CF*Ref.
  210. Additional constraints or allowed values on parameters
  211. are noted with the specific functions.
  212. }
  213. {!
  214. @typedef MDQueryRef
  215. This is the type of a reference to MDQuerys.
  216. }
  217. type
  218. MDQueryRef = ^__MDQuery; { an opaque type }
  219. __MDQuery = record end;
  220. const
  221. kMDQuerySynchronous = 1;
  222. kMDQueryWantsUpdates = 4;
  223. type
  224. MDQueryOptionFlags = SIGNEDLONG;
  225. {!
  226. @enum MDQueryOptionFlags
  227. @constant kMDQuerySynchronous Block during the gathering phase.
  228. If this parameter is true, the function will not return
  229. until the query has finished gathering the initial
  230. results. The run loop will run in the default mode, which
  231. will allow anything registered in that mode with this run
  232. loop to execute as well. If this parameter is false, the
  233. function returns immediately after starting the query
  234. asychronously.
  235. @constant kMDQueryWantsUpdates When set, after gathering the initial results
  236. the query will watch for changes in the system which should
  237. update the list of results. This can be changes which cause
  238. new files to now match the query, or changes which cause
  239. files in the result list to continue to match, or no longer
  240. match, the query. Files which begin to match the query are
  241. added to the result list, and files which no longer match
  242. the query expression are removed from the result list.
  243. Currently, this parameter is ignored if the synchronous
  244. parameter is true. This is subject to change, and you
  245. should always pass in the value you want here.
  246. }
  247. {!
  248. @function MDQueryGetTypeID
  249. Returns the type identifier of all MDQuery instances.
  250. }
  251. function MDQueryGetTypeID: CFTypeID; external name '_MDQueryGetTypeID';
  252. (* AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER *)
  253. {!
  254. @function MDQueryCreate
  255. Creates a new query with the given query expression.
  256. @param allocator The CFAllocator which should be used to allocate
  257. memory for the query and its sub-storage. This
  258. parameter may be NULL in which case the current default
  259. CFAllocator is used.
  260. @param queryString The query expression string for this query. The
  261. syntax for query expressions is explained above in the
  262. header overview documentation.
  263. @param valueListAttrs An optional array of attribute names. The
  264. query will collect the values of these attributes into
  265. uniqued lists, which can be used or displayed to summarize
  266. the results of the query, or allow a user to further
  267. qualify the items for which they are searching. This
  268. parameter may be NULL if no value lists are desired. Value
  269. list collection increases CPU usage and significantly
  270. increases the memory usage of an MDQuery. The attribute
  271. names are CFStrings.
  272. @param sortingAttrs An optional array of attribute names. The
  273. query will results of the query based on the values of
  274. these attributes. The first name in the array is used as
  275. the primary sort key, the second as the secondary key, and
  276. so on. The comparison of like-typed values is a simple,
  277. literal comparison. This parameter may be NULL if no
  278. sorting is desired. Sorting increases memory usage and
  279. significantly increases the CPU usage of an MDQuery.
  280. However, when possible, it is almost always cheaper to have
  281. the MDQuery do the sorting, rather than you fetching all
  282. the results and attributes from each of them and doing the
  283. sorting yourself. The attribute names are CFStrings.
  284. @result An MDQueryRef, or NULL on failure. If the query string
  285. is empty or malformed (invalid syntax), returns NULL.
  286. }
  287. function MDQueryCreate( allocator: CFAllocatorRef; queryString: CFStringRef; valueListAttrs: CFArrayRef; sortingAttrs: CFArrayRef ): MDQueryRef; external name '_MDQueryCreate';
  288. (* AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER *)
  289. {!
  290. @function MDQueryCreateSubset
  291. Creates a new query, which is a subset of the given query. Only
  292. results matched by the given query can be matched by the
  293. query expression of this query.
  294. @param allocator The CFAllocator which should be used to allocate
  295. memory for the query and its sub-storage. This
  296. parameter may be NULL in which case the current default
  297. CFAllocator is used.
  298. @param query The parent query of the new query.
  299. @param queryString The query expression string for this query.
  300. This expression in effect may further restrict the matches
  301. found by the parent query. If the string is empty the
  302. behavior is undefined.
  303. @param valueListAttrs An optional array of attribute names. The
  304. query will collect the values of these attributes into
  305. uniqued lists, which can be used or displayed to summarize
  306. the results of the query, or allow a user to further
  307. qualify the items for which they are searching. This
  308. parameter may be NULL if no value lists are desired. Value
  309. list collection increases CPU usage and significantly
  310. increases the memory usage of an MDQuery. The attribute
  311. names are CFStrings.
  312. @param sortingAttrs An optional array of attribute names. The
  313. query will results of the query based on the values of
  314. these attributes. The first name in the array is used as
  315. the primary sort key, the second as the secondary key, and
  316. so on. The comparison of like-typed values is a simple,
  317. literal comparison. This parameter may be NULL if no
  318. sorting is desired. Sorting increases memory usage and
  319. significantly increases the CPU usage of an MDQuery.
  320. However, when possible, it is almost always cheaper to have
  321. the MDQuery do the sorting, rather than you fetching all
  322. the results and attributes from each of them and doing the
  323. sorting yourself. The attribute names are CFStrings.
  324. @result An MDQueryRef, or NULL on failure. If the query string
  325. is empty or malformed (invalid syntax), returns NULL.
  326. }
  327. function MDQueryCreateSubset( allocator: CFAllocatorRef; query: MDQueryRef; queryString: CFStringRef; valueListAttrs: CFArrayRef; sortingAttrs: CFArrayRef ): MDQueryRef; external name '_MDQueryCreateSubset';
  328. (* AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER *)
  329. {!
  330. @function MDQueryCreateForItems
  331. Creates a new query with the given query expression.
  332. @param allocator The CFAllocator which should be used to allocate
  333. memory for the query and its sub-storage. This
  334. parameter may be NULL in which case the current default
  335. CFAllocator is used.
  336. @param queryString The query expression string for this query. The
  337. syntax for query expressions is explained above in the
  338. header overview documentation.
  339. @param valueListAttrs An optional array of attribute names. The
  340. query will collect the values of these attributes into
  341. uniqued lists, which can be used or displayed to summarize
  342. the results of the query, or allow a user to further
  343. qualify the items for which they are searching. This
  344. parameter may be NULL if no value lists are desired. Value
  345. list collection increases CPU usage and significantly
  346. increases the memory usage of an MDQuery. The attribute
  347. names are CFStrings.
  348. @param sortingAttrs An optional array of attribute names. The
  349. query will results of the query based on the values of
  350. these attributes. The first name in the array is used as
  351. the primary sort key, the second as the secondary key, and
  352. so on. The comparison of like-typed values is a simple,
  353. literal comparison. This parameter may be NULL if no
  354. sorting is desired. Sorting increases memory usage and
  355. significantly increases the CPU usage of an MDQuery.
  356. However, when possible, it is almost always cheaper to have
  357. the MDQuery do the sorting, rather than you fetching all
  358. the results and attributes from each of them and doing the
  359. sorting yourself. The attribute names are CFStrings.
  360. @param items An array of items. The query will only return results
  361. in this set.
  362. @result An MDQueryRef, or NULL on failure. If the query string
  363. is empty or malformed (invalid syntax), returns NULL.
  364. }
  365. function MDQueryCreateForItems( allocator: CFAllocatorRef; queryString: CFStringRef; valueListAttrs: CFArrayRef; sortingAttrs: CFArrayRef; items: CFArrayRef ): MDQueryRef; external name '_MDQueryCreateForItems';
  366. (* AVAILABLE_MAC_OS_X_VERSION_10_7_AND_LATER *)
  367. {!
  368. @function MDQueryCopyQueryString
  369. Returns the query string of the query.
  370. @param query The query to be interrogated.
  371. @result The query string of the query.
  372. }
  373. function MDQueryCopyQueryString( query: MDQueryRef ): CFStringRef; external name '_MDQueryCopyQueryString';
  374. (* AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER *)
  375. {!
  376. @function MDQueryCopyValueListAttributes
  377. Returns the list of attribute names for which the query is
  378. collecting the lists of values.
  379. @param query The query to be interrogated.
  380. @result The list of value list attribute names of the query.
  381. }
  382. function MDQueryCopyValueListAttributes( query: MDQueryRef ): CFArrayRef; external name '_MDQueryCopyValueListAttributes';
  383. (* AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER *)
  384. {!
  385. @function MDQueryCopySortingAttributes
  386. Returns the list of attribute names the query is using to sort
  387. the results.
  388. @param query The query to be interrogated.
  389. @result The list of sorting attribute names of the query.
  390. }
  391. function MDQueryCopySortingAttributes( query: MDQueryRef ): CFArrayRef; external name '_MDQueryCopySortingAttributes';
  392. (* AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER *)
  393. {!
  394. @typedef MDQueryBatchingParams
  395. Structure containing the progress notification batching
  396. parameters of an MDQuery. The first notification can be
  397. triggered by the either first_max_num or first_max_ms limit
  398. being exceeded. Subsequent notifications are triggered by
  399. either the progress_max_num or progress_max_ms limit. The
  400. default batching parameters are undefined and subject to
  401. change.
  402. @field first_max_num The maximum number of results that can
  403. accumulate before a progress notification is sent out
  404. by the MDQuery, for the first notification.
  405. @field first_max_ms The maximum number of milliseconds that can
  406. pass before a progress notification is sent out. This
  407. value is advisory, in that the notification will be
  408. triggered "at some point after first_max_ms milliseconds
  409. have passed since the query began accumulating results",
  410. but generally not very long after, for the first
  411. progress notification.
  412. @field progress_max_num The maximum number of results that can
  413. accumulate before a progress notification is sent out
  414. by the MDQuery, for notifications after the first,
  415. during the initial gathering phase of the query.
  416. @field progress_max_ms The maximum number of milliseconds that can
  417. pass before a progress notification is sent out. This
  418. value is advisory, in that the notification will be
  419. triggered "at some point after first_max_ms milliseconds
  420. have passed since the query began accumulating results",
  421. but generally not very long after, for progress
  422. notifications after the first, during the initial
  423. gathering phase of the query.
  424. @field update_max_num The maximum number of results that can
  425. accumulate before an update notification is sent out
  426. by the MDQuery, for notifications after the gathering
  427. phase of the query has finished.
  428. @field update_max_ms The maximum number of milliseconds that can
  429. pass before a progress notification is sent out. This
  430. value is advisory, in that the notification will be
  431. triggered "at some point after first_max_ms milliseconds
  432. have passed since the query began accumulating results",
  433. but generally not very long after, for update notifications
  434. after the gathering phase of the query has finished.
  435. }
  436. type
  437. MDQueryBatchingParams = record
  438. first_max_num: size_t;
  439. first_max_ms: size_t;
  440. progress_max_num: size_t;
  441. progress_max_ms: size_t;
  442. update_max_num: size_t;
  443. update_max_ms: size_t;
  444. end;
  445. {!
  446. @function MDQueryGetBatchingParameters
  447. Returns the current parameters that control batching of progress
  448. notifications.
  449. @param query The query to be interrogated.
  450. @result An MDQueryBatchingParams structure with the current
  451. batching parameters.
  452. }
  453. function MDQueryGetBatchingParameters( query: MDQueryRef ): MDQueryBatchingParams; external name '_MDQueryGetBatchingParameters';
  454. (* AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER *)
  455. {!
  456. @function MDQuerySetBatchingParameters
  457. @param query The query whose batching parameters are to be set.
  458. @param params An MDQueryBatchingParams structure with the batching
  459. parameters to set.
  460. }
  461. procedure MDQuerySetBatchingParameters( query: MDQueryRef; params: MDQueryBatchingParams ); external name '_MDQuerySetBatchingParameters';
  462. (* AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER *)
  463. {!
  464. @typedef MDQueryCreateResultFunction
  465. Type of the callback function used to create the result objects
  466. stored and returned by an MDQuery. The function may
  467. hold onto the given MDItemRef in some other data
  468. structure, but must retain it for it to remain valid.
  469. The create-result function is called lazily as results
  470. are requested from a query, so it will not generally
  471. be called on all results, if in fact any. This avoids
  472. the cost of creating potentially hundreds of thousands
  473. of what might be temporary objects.
  474. @param query The MDQuery instance.
  475. @param item The default MDItemRef for the result.
  476. @param context The user-defined context parameter given to
  477. MDQuerySetCreateResultFunction().
  478. @result The function must return a pointer-sized value that can
  479. be managed with the callbacks which were set at the same
  480. time the create function was given to the query. The
  481. value must be returned with a reference (such as if the
  482. retain callback had been called on it), as implied by the
  483. Create name. If this function doesn't wish to create a
  484. new object, it can return the given MDItemRef, but must
  485. also return it with a new retain, and the callbacks must
  486. be able to handle an MDItemRef as an input value. If
  487. this function returns NULL, NULL will be stored for the
  488. moment in the query, MDQueryGetResultAtIndex() may return
  489. NULL for that result, and the next time the query wants
  490. the result, it will call this function again.
  491. }
  492. type
  493. MDQueryCreateResultFunction = function( query: MDQueryRef; item: MDItemRef; context: UnivPtr ): UnivPtr;
  494. {!
  495. @function MDQuerySetCreateResultFunction
  496. Sets the function used to create the result objects of the
  497. MDQuery. If no create function is set on an MDQuery,
  498. the default result objects are MDItemRefs. Results
  499. created after a create function is set will be created
  500. through the given create function, but values created
  501. before the function was set (or after it is unset) are
  502. not modified. Therefore it is not advisable to change
  503. this function after MDQueryExecute() has been called
  504. with the query. The create-result function is called
  505. lazily as results are requested from a query, so it will
  506. not generally be called on all results, if in fact any.
  507. This avoids the cost of creating potentially hundreds
  508. of thousands of what might be temporary objects.
  509. @param query The query to whose result create function is to be set.
  510. @param func The callback function the MDQuery will use to
  511. create its results, such as those returned from
  512. MDQueryGetResultAtIndex(). This parameter
  513. may be NULL, in which case any previous result creation
  514. settings are cancelled, and the MDQuery will subsequently
  515. produce MDItemRefs. If the function (when the parameter is
  516. not NULL) is not of type MDQueryCreateResultFunction or
  517. does not behave as a MDQueryCreateResultFunction must,
  518. the behavior is undefined.
  519. @param context A pointer-sized user-defined value, which is
  520. passed as the third parameter to the create function,
  521. but is otherwise unused by MDQuery. The MDQuery does
  522. not retain the context in any way, so it must remain
  523. valid for at least the lifetime of the query. If the
  524. context is not what is expected by the create function,
  525. the behavior is undefined.
  526. @param cb A pointer to a CFArrayCallBacks structure
  527. initialized with the callbacks for the query to use to
  528. manage the created result objects. A copy of the
  529. contents of the callbacks structure is made, so that a
  530. pointer to a structure on the stack can be passed in, or
  531. can be reused for multiple query creations. Only version
  532. 0 of the CFArrayCallBacks is supported. The retain field
  533. may be NULL, in which case the MDQuery will do nothing to
  534. add a retain to the created results for the query. The
  535. release field may be NULL, in which case the MDQuery will
  536. do nothing to remove the query's retain (such as the one
  537. it gets from the create function) on the result objects
  538. when the query is destroyed. If the copyDescription field
  539. is NULL, the query will create a simple description for
  540. the result objects. If the equal field is NULL, the query
  541. will use pointer equality to test for equality of results.
  542. This callbacks parameter itself may be NULL, which is
  543. treated as if a valid structure of version 0 with all
  544. fields NULL had been passed in. Otherwise, if any of the
  545. fields are not valid pointers to functions of the correct
  546. type, or this parameter is not a valid pointer to a
  547. CFArrayCallBacks callbacks structure, the behavior is
  548. undefined. If any of the value values returned from the
  549. create function is not one understood by one or more of
  550. the callback functions, the behavior when those callback
  551. functions are used is undefined. For example, if the create
  552. function can return NULL, then NULL must be understood by
  553. the callback functions as a possible parameter. The retain
  554. and release callbacks must be a matched set -- do not
  555. assume that the retain function will be unused or that
  556. additional reference counts will not be taken on the
  557. created results.
  558. }
  559. procedure MDQuerySetCreateResultFunction( query: MDQueryRef; func: MDQueryCreateResultFunction; context: UnivPtr; {const} cb: CFArrayCallBacksPtr ); external name '_MDQuerySetCreateResultFunction';
  560. (* AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER *)
  561. {!
  562. @typedef MDQueryCreateValueFunction
  563. Type of the callback function used to create the value objects
  564. stored and returned by an MDQuery. The function may
  565. hold onto the given attribute name and/or value in some
  566. other data structure, but must retain them for them to
  567. remain valid.
  568. @param query The MDQuery instance.
  569. @param attrName The attribute name of the value.
  570. @param attrValue The default value of the value.
  571. @param context The user-defined context parameter given to
  572. MDQuerySetCreateValueFunction().
  573. @result The function must return a pointer-sized value that can
  574. be managed with the callbacks which were set at the same
  575. time the create function was given to the query. The
  576. value must be returned with a reference (such as if the
  577. retain callback had been called on it), as implied by the
  578. Create name. If this function doesn't wish to create a
  579. new object, it can return the given CFTypeRef, but must
  580. also return it with a new retain, and the callbacks must
  581. be able to handle a CFTypeRef as an input value.
  582. }
  583. type
  584. MDQueryCreateValueFunction = function( query: MDQueryRef; attrName: CFStringRef; attrValue: CFTypeRef; context: UnivPtr ): UnivPtr;
  585. {!
  586. @function MDQuerySetCreateValueFunction
  587. Sets the function used to create the value objects of the
  588. MDQuery. These are the values of the value lists that
  589. were requested when the query was created. If no create
  590. function is set on an MDQuery, the default value objects
  591. are the CFTypeRef values of the attributes. Values
  592. created after a create function is set will be created
  593. through the given create function, but values created
  594. before the function was set (or after it is unset)
  595. are not modified. Therefore it is not advisable to
  596. change this function after MDQueryExecute() has been
  597. called with the query.
  598. @param query The query to whose value create function is to be set.
  599. @param func The callback function the MDQuery will use to
  600. create the value list values, such as those returned from
  601. MDQueryCopyValuesOfAttribute(). This parameter
  602. may be NULL, in which case any previous value creation
  603. settings are cancelled, and the MDQuery will subsequently
  604. produce the default CFTypeRefs. If the function (when the
  605. parameter is not NULL) is not of type
  606. MDQueryCreateValueFunction or does not behave as a
  607. MDQueryCreateValueFunction must, the behavior is undefined.
  608. @param context A pointer-sized user-defined value, which is
  609. passed as the fourth parameter to the create function,
  610. but is otherwise unused by MDQuery. The MDQuery does
  611. not retain the context in any way, so it must remain
  612. valid for at least the lifetime of the query. If the
  613. context is not what is expected by the create function,
  614. the behavior is undefined.
  615. @param cb A pointer to a CFArrayCallBacks structure
  616. initialized with the callbacks for the query to use to
  617. manage the created value objects. A copy of the
  618. contents of the callbacks structure is made, so that a
  619. pointer to a structure on the stack can be passed in, or
  620. can be reused for multiple query creations. Only version
  621. 0 of the CFArrayCallBacks is supported. The retain field
  622. may be NULL, in which case the MDQuery will do nothing to
  623. add a retain to the created values for the query. The
  624. release field may be NULL, in which case the MDQuery will
  625. do nothing to remove the query's retain (such as the one
  626. it gets from the create function) on the value objects
  627. when the query is destroyed. If the copyDescription field
  628. is NULL, the query will create a simple description for
  629. the value objects. If the equal field is NULL, the query
  630. will use pointer equality to test for equality of values.
  631. This callbacks parameter itself may be NULL, which is
  632. treated as if a valid structure of version 0 with all
  633. fields NULL had been passed in. Otherwise, if any of the
  634. fields are not valid pointers to functions of the correct
  635. type, or this parameter is not a valid pointer to a
  636. CFArrayCallBacks callbacks structure, the behavior is
  637. undefined. If any of the value values returned from the
  638. create function is not one understood by one or more of
  639. the callback functions, the behavior when those callback
  640. functions are used is undefined. For example, if the
  641. create function can return NULL, then NULL must be
  642. understood by the callback functions as a possible
  643. parameter. The retain and release callbacks must be a
  644. matched set -- do not assume that the retain function will
  645. be unused or that additional reference counts will not be
  646. taken on the created values.
  647. }
  648. procedure MDQuerySetCreateValueFunction( query: MDQueryRef; func: MDQueryCreateValueFunction; context: UnivPtr; {const} cb: CFArrayCallBacksPtr ); external name '_MDQuerySetCreateValueFunction';
  649. (* AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER *)
  650. {!
  651. @function MDQuerySetDispatchQueue
  652. Set the dispatch queue on which query results will be delivered
  653. by MDQueryExecute. It is not advisable to change set
  654. dispatch queue after MDQueryExecute() has been called with
  655. the query. Setting the dispatch queue for a synchronous
  656. query (kMDQuerySynchronous) has no effect.
  657. @param query The query for which the dispatch queue should be set.
  658. @param queue The dispatch queue on which results should be delivered.
  659. }
  660. procedure MDQuerySetDispatchQueue( query: MDQueryRef; queue: dispatch_queue_t ); external name '_MDQuerySetDispatchQueue';
  661. (* AVAILABLE_MAC_OS_X_VERSION_10_6_AND_LATER *)
  662. {!
  663. @function MDQueryExecute
  664. Run the query, and populate the query with the results. Queries
  665. only gather results or process updates while the current
  666. thread's run loop is running. Queries normally operate
  667. asynchronously, and send out progress and update
  668. notifications to report changes to the list of results
  669. that has been collected. Queries have two phases: the
  670. initial gathering of all currently matching results, and
  671. a second live-update phase where queries monitor the
  672. state of the system and update themselves to external
  673. changes in files or the operating environment (for example,
  674. as time advances, files which did not match the query
  675. when it was started may later match the query). Query
  676. notifications are posted within the context of the same
  677. thread which executes the query.
  678. [[There are three operational modes: (1) synchronous static
  679. queries, which collect the list of current results and then
  680. do not watch for updates to the results, (2) asynchronous
  681. static queries, which collect the results asychronously
  682. after this function returns, and then do not watch for
  683. updates to the results, and (3) asynchronous live queries
  684. which collect the initial results asychronously after this
  685. function returns, and then do watch for updates to the
  686. results, until the query is destroyed. There is little
  687. reason not to allow the fourth case, synchronous collection
  688. of initial results, followed by asynchronous monitoring
  689. for updates, so this may change in the future.]]
  690. @param query The query to execute.
  691. @param optionFlags Bitwise or of MDQueryOptionFlags
  692. @result Returns true if the query was started (executed in the case
  693. of a synchronous query), false otherwise. Queries cannot be
  694. executed more than once.
  695. }
  696. function MDQueryExecute( query: MDQueryRef; optionFlags: CFOptionFlags ): Boolean; external name '_MDQueryExecute';
  697. (* AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER *)
  698. {!
  699. @function MDQueryStop
  700. Stops the query from ever generating more results. Queries may be
  701. executed only once, so a stopped query cannot be
  702. restarted. The query will also not generate any result
  703. updates. The query is static after this function returns.
  704. The query will do final processing of results that have
  705. come in but not yet been processed (because, say, the
  706. batching parameters hasn't triggered that yet). That may
  707. trigger a progress notification, so be aware of that if
  708. you are stopping a query from within your progress note
  709. handler; that is, during this function, a recursive
  710. progress and/or finished notification might occur, which
  711. might recursively call your notification handler. It is
  712. safe to call this function recursively. You would call
  713. this function to stop a query that is generating way too
  714. many results to be useful, but still want to access the
  715. results that have come in so far. If a query is stopped
  716. before the gathering phase finishes, it will not report
  717. itself as finished, nor will it send out a finished
  718. notification.
  719. @param query The query to stop.
  720. }
  721. procedure MDQueryStop( query: MDQueryRef ); external name '_MDQueryStop';
  722. (* AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER *)
  723. {!
  724. @function MDQueryDisableUpdates
  725. Disables updates to the query result list. This should be called
  726. before iterating through the list of results to prevent
  727. the result list from changing during the iteration. The
  728. disabled state is a counter, and disabling can be done
  729. recursively and from different threads.
  730. @param query The query for which updates are to be disabled.
  731. @result The generation number of the query. This changes each time the query's
  732. result set has changed.
  733. }
  734. procedure MDQueryDisableUpdates( query: MDQueryRef ); external name '_MDQueryDisableUpdates';
  735. (* AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER *)
  736. {!
  737. @function MDQueryEnableUpdates
  738. Re-enables updates to the query result list. This should be called
  739. when finished iterating through the list of results, to
  740. allow changes to the result list to occur. Changes will
  741. be allowed when all the disables have been matched by a
  742. corresponding enable.
  743. @param query The query for which updates are to be enabled.
  744. }
  745. procedure MDQueryEnableUpdates( query: MDQueryRef ); external name '_MDQueryEnableUpdates';
  746. (* AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER *)
  747. {!
  748. @function MDQueryIsGatheringComplete
  749. Returns true if the first phase of a query, the initial result
  750. gathering, has finished.
  751. @param query The query to be interrogated.
  752. @result A boolean indicating whether or not the first phase
  753. of a query has completed.
  754. }
  755. function MDQueryIsGatheringComplete( query: MDQueryRef ): Boolean; external name '_MDQueryIsGatheringComplete';
  756. (* AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER *)
  757. {!
  758. @function MDQueryGetResultCount
  759. Returns the number of results currently collected by the query.
  760. Note that the number of results in a query will change
  761. over time as the query's result list is updated.
  762. @param query The query to be interrogated.
  763. @result The number of results in the query.
  764. }
  765. function MDQueryGetResultCount( query: MDQueryRef ): CFIndex; external name '_MDQueryGetResultCount';
  766. (* AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER *)
  767. {!
  768. @function MDQueryGetResultAtIndex
  769. Returns the current result at the given index. This function
  770. causes the result object to be created if it hasn't
  771. been created already. For performance reasons, it is
  772. not advisable to ask for results that you don't need,
  773. to avoid the cost of creating them. If possible, call
  774. this function to fetch only the results you need to
  775. display or otherwise process. Note that the index of
  776. a particular result will change over time, as the
  777. query's result list is updated.
  778. @param query The query to be interrogated.
  779. @param idx The index into the query's result list. If the index is
  780. negative, or is equal to or larger than the current
  781. number of results in the query, the behavior is undefined.
  782. @result Returns the MDItemRef currently at the given index, or
  783. if a result-create function has been set, returns the
  784. result returned by that function.
  785. }
  786. function MDQueryGetResultAtIndex( query: MDQueryRef; idx: CFIndex ): UnivPtr; external name '_MDQueryGetResultAtIndex';
  787. (* AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER *)
  788. {!
  789. @function MDQueryGetIndexOfResult
  790. Returns the current index of the given result. If a result-create
  791. function has been set, and the equal callback is non-NULL,
  792. it will be used to test the query's results against the
  793. candidate result. Note that the index of a result will
  794. change over time, as the query's result list is updated.
  795. @param query The query to be interrogated.
  796. @param result The candidate result object for which to search.
  797. If a custom create-result function has been set, and this
  798. parameter is not a valid result object that the provided
  799. callbacks can handle, the behavior is undefined. If a custom
  800. create-result function has not been set, this parameter
  801. must be a valid MDItemRef.
  802. @result The index of the given result, or kCFNotFound if the
  803. value is not one of the query's existing results. If
  804. you provided a custom result creation function,
  805. as well as a custom object comparator function,
  806. result will be objects created by that function.
  807. }
  808. function MDQueryGetIndexOfResult( query: MDQueryRef; result: {const} UnivPtr ): CFIndex; external name '_MDQueryGetIndexOfResult';
  809. (* AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER *)
  810. {!
  811. @function MDQueryGetAttributeValueOfResultAtIndex
  812. Returns the value of the named attribute for the result at
  813. the given index.
  814. @param query The query to be interrogated.
  815. @param name The attribute name for which to return the values.
  816. If the attribute is not one of those requested in the
  817. valueListAttrs or sortingAttrs parameters to one of
  818. the query creation functions, the result will be NULL.
  819. @param idx The index into the query's result list. If the index is
  820. negative, or is equal to or larger than the current
  821. number of results in the query, the behavior is undefined.
  822. @result The value of the attribute, or NULL if the attribute
  823. doesn't exist in the query on that result.
  824. }
  825. function MDQueryGetAttributeValueOfResultAtIndex( query: MDQueryRef; name: CFStringRef; idx: CFIndex ): UnivPtr; external name '_MDQueryGetAttributeValueOfResultAtIndex';
  826. (* AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER *)
  827. {!
  828. @function MDQueryCopyValuesOfAttribute
  829. Returns the list of values, from the results of the query, of the
  830. named attribute. The list is not ordered in any way. The
  831. list contains only one occurrence of each value. Note that
  832. this list may change over time, as the query's result list
  833. is updated.
  834. @param query The query to be interrogated.
  835. @param name The attribute name for which to return the values.
  836. If the attribute is not one of those requested in the
  837. valueListAttrs parameter to one of the query creation
  838. functions, the behavior is undefined.
  839. @result A CFArray holding the value objects for that attribute.
  840. }
  841. function MDQueryCopyValuesOfAttribute( query: MDQueryRef; name: CFStringRef ): CFArrayRef; external name '_MDQueryCopyValuesOfAttribute';
  842. (* AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER *)
  843. {!
  844. @function MDQueryGetCountOfResultsWithAttributeValue
  845. Returns the number of results which have the given attribute and
  846. attribute value. Note that this count may change over time,
  847. as the query's result list is updated.
  848. @param query The query to be interrogated.
  849. @param name The attribute name for which to return the number
  850. of results with the given value. If the attribute is not
  851. one of those requested in the valueListAttrs parameter to
  852. one of the query creation functions, the behavior is
  853. undefined.
  854. @param value The attribute value for which to return the number
  855. of results with that value. This parameter may be NULL,
  856. in which case the number of results that do not contain
  857. the named attribute is returned.
  858. @result The number of results with that attribute and value.
  859. }
  860. function MDQueryGetCountOfResultsWithAttributeValue( query: MDQueryRef; name: CFStringRef; value: CFTypeRef ): CFIndex; external name '_MDQueryGetCountOfResultsWithAttributeValue';
  861. (* AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER *)
  862. {!
  863. @function MDQuerySetSortOrder
  864. Sets the sort order for a query.
  865. @param query The query for which the sort order is to be set.
  866. @param sortingAttrs An array of attribute names, as in MDQueryCreate.
  867. The query's result set will be sorted according to the order of
  868. these attributes. All names in the array have to have been passed
  869. as sortingAttrs when the query was created. The attribute names
  870. are CFStrings
  871. @result A boolean, true on success, false on failure.
  872. }
  873. function MDQuerySetSortOrder( query: MDQueryRef; sortingAttrs: CFArrayRef ): Boolean; external name '_MDQuerySetSortOrder';
  874. (* AVAILABLE_MAC_OS_X_VERSION_10_7_AND_LATER *)
  875. {!
  876. @enum MDQuerySortOptionFlags
  877. @constant kMDQueryReverseSortOrderFlag Sort the attribute in reverse order.
  878. }
  879. const
  880. kMDQueryReverseSortOrderFlag = (1 shl 0);
  881. type
  882. MDQuerySortOptionFlags = SIGNEDLONG;
  883. {!
  884. @function MDQuerySetSortOptionFlagsForAttribute
  885. Sets the sort flags for a query.
  886. @param query The query for which the sort flags is to be set.
  887. @param fieldName The attribute name for which sort option flags are to be set.
  888. The attribute name must have been part of the sortingFlags when the query was created.
  889. @param flags A uint32_t containing MDQuerySortOptionFlags to be applied to the attibute
  890. @result A boolean, true on success, false on failure.
  891. }
  892. function MDQuerySetSortOptionFlagsForAttribute( query: MDQueryRef; fieldName: CFStringRef; flags: UInt32 ): Boolean; external name '_MDQuerySetSortOptionFlagsForAttribute';
  893. (* AVAILABLE_MAC_OS_X_VERSION_10_7_AND_LATER *)
  894. {!
  895. @function MDQueryGetSortOptionFlagsForAttribute
  896. Gets the sort option flags for a sorting attribute.
  897. @param query The query for which fetch sort option flags.
  898. @param fieldName The attribute name for which sort option flags are to be fetched.
  899. @result A uint32_t, with MDQuerySortOptionFlags set for the attribute.
  900. }
  901. function MDQueryGetSortOptionFlagsForAttribute( query: MDQueryRef; fieldName: CFStringRef ): UInt32; external name '_MDQueryGetSortOptionFlagsForAttribute';
  902. (* AVAILABLE_MAC_OS_X_VERSION_10_7_AND_LATER *)
  903. {!
  904. @typedef MDQuerySortComparatorFunction
  905. Type of the callback function used to sort the results of an
  906. MDQuery.
  907. @param query The MDQuery instance.
  908. @param attrs1 A C array of attribute values for a result. The
  909. values occur in the array in the same order and position
  910. that the attribute names were passed in the sortingAttrs
  911. array when the query was created. The values of the
  912. attributes might be NULL, if the attribute doesn't exist

Large files files are truncated, but you can click here to view the full file