2
0

MDQuery.pas 65 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978979980981982983984985986987988989990991992993994995996997998999100010011002100310041005100610071008100910101011101210131014101510161017101810191020102110221023102410251026102710281029103010311032103310341035103610371038103910401041104210431044104510461047104810491050105110521053105410551056105710581059106010611062106310641065106610671068106910701071107210731074107510761077107810791080108110821083108410851086108710881089109010911092109310941095109610971098109911001101110211031104110511061107110811091110111111121113111411151116111711181119112011211122112311241125112611271128112911301131113211331134113511361137113811391140114111421143114411451146114711481149115011511152115311541155115611571158115911601161116211631164116511661167116811691170117111721173117411751176117711781179118011811182118311841185118611871188118911901191119211931194119511961197119811991200120112021203120412051206120712081209121012111212121312141215121612171218121912201221122212231224122512261227122812291230123112321233123412351236123712381239124012411242124312441245124612471248124912501251125212531254125512561257125812591260126112621263126412651266126712681269127012711272127312741275127612771278127912801281128212831284128512861287128812891290129112921293129412951296129712981299
  1. { MDQuery.h
  2. Copyright (c) 2003-2005, Apple Computer, Inc. All rights reserved.
  3. }
  4. { Pascal Translation: Gorazd Krosl <[email protected]>, October 2009 }
  5. { Pascal Translation Updated: Jonas Maebe <[email protected]>, September 2012 }
  6. {
  7. Modified for use with Free Pascal
  8. Version 308
  9. Please report any bugs to <[email protected]>
  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 not defined __arm64__ and defined CPUAARCH64}
  56. {$setc __arm64__ := 1}
  57. {$elsec}
  58. {$setc __arm64__ := 0}
  59. {$endc}
  60. {$ifc defined cpu64}
  61. {$setc __LP64__ := 1}
  62. {$elsec}
  63. {$setc __LP64__ := 0}
  64. {$endc}
  65. {$ifc defined __ppc__ and __ppc__ and defined __i386__ and __i386__}
  66. {$error Conflicting definitions for __ppc__ and __i386__}
  67. {$endc}
  68. {$ifc defined __ppc__ and __ppc__}
  69. {$setc TARGET_CPU_PPC := TRUE}
  70. {$setc TARGET_CPU_PPC64 := FALSE}
  71. {$setc TARGET_CPU_X86 := FALSE}
  72. {$setc TARGET_CPU_X86_64 := FALSE}
  73. {$setc TARGET_CPU_ARM := FALSE}
  74. {$setc TARGET_CPU_ARM64 := FALSE}
  75. {$setc TARGET_OS_MAC := TRUE}
  76. {$setc TARGET_OS_IPHONE := FALSE}
  77. {$setc TARGET_IPHONE_SIMULATOR := FALSE}
  78. {$setc TARGET_OS_EMBEDDED := FALSE}
  79. {$elifc defined __ppc64__ and __ppc64__}
  80. {$setc TARGET_CPU_PPC := FALSE}
  81. {$setc TARGET_CPU_PPC64 := TRUE}
  82. {$setc TARGET_CPU_X86 := FALSE}
  83. {$setc TARGET_CPU_X86_64 := FALSE}
  84. {$setc TARGET_CPU_ARM := FALSE}
  85. {$setc TARGET_CPU_ARM64 := FALSE}
  86. {$setc TARGET_OS_MAC := TRUE}
  87. {$setc TARGET_OS_IPHONE := FALSE}
  88. {$setc TARGET_IPHONE_SIMULATOR := FALSE}
  89. {$setc TARGET_OS_EMBEDDED := FALSE}
  90. {$elifc defined __i386__ and __i386__}
  91. {$setc TARGET_CPU_PPC := FALSE}
  92. {$setc TARGET_CPU_PPC64 := FALSE}
  93. {$setc TARGET_CPU_X86 := TRUE}
  94. {$setc TARGET_CPU_X86_64 := FALSE}
  95. {$setc TARGET_CPU_ARM := FALSE}
  96. {$setc TARGET_CPU_ARM64 := FALSE}
  97. {$ifc defined(iphonesim)}
  98. {$setc TARGET_OS_MAC := FALSE}
  99. {$setc TARGET_OS_IPHONE := TRUE}
  100. {$setc TARGET_IPHONE_SIMULATOR := TRUE}
  101. {$elsec}
  102. {$setc TARGET_OS_MAC := TRUE}
  103. {$setc TARGET_OS_IPHONE := FALSE}
  104. {$setc TARGET_IPHONE_SIMULATOR := FALSE}
  105. {$endc}
  106. {$setc TARGET_OS_EMBEDDED := FALSE}
  107. {$elifc defined __x86_64__ and __x86_64__}
  108. {$setc TARGET_CPU_PPC := FALSE}
  109. {$setc TARGET_CPU_PPC64 := FALSE}
  110. {$setc TARGET_CPU_X86 := FALSE}
  111. {$setc TARGET_CPU_X86_64 := TRUE}
  112. {$setc TARGET_CPU_ARM := FALSE}
  113. {$setc TARGET_CPU_ARM64 := FALSE}
  114. {$ifc defined(iphonesim)}
  115. {$setc TARGET_OS_MAC := FALSE}
  116. {$setc TARGET_OS_IPHONE := TRUE}
  117. {$setc TARGET_IPHONE_SIMULATOR := TRUE}
  118. {$elsec}
  119. {$setc TARGET_OS_MAC := TRUE}
  120. {$setc TARGET_OS_IPHONE := FALSE}
  121. {$setc TARGET_IPHONE_SIMULATOR := FALSE}
  122. {$endc}
  123. {$setc TARGET_OS_EMBEDDED := FALSE}
  124. {$elifc defined __arm__ and __arm__}
  125. {$setc TARGET_CPU_PPC := FALSE}
  126. {$setc TARGET_CPU_PPC64 := FALSE}
  127. {$setc TARGET_CPU_X86 := FALSE}
  128. {$setc TARGET_CPU_X86_64 := FALSE}
  129. {$setc TARGET_CPU_ARM := TRUE}
  130. {$setc TARGET_CPU_ARM64 := FALSE}
  131. { will require compiler define when/if other Apple devices with ARM cpus ship }
  132. {$setc TARGET_OS_MAC := FALSE}
  133. {$setc TARGET_OS_IPHONE := TRUE}
  134. {$setc TARGET_IPHONE_SIMULATOR := FALSE}
  135. {$setc TARGET_OS_EMBEDDED := TRUE}
  136. {$elifc defined __arm64__ and __arm64__}
  137. {$setc TARGET_CPU_PPC := FALSE}
  138. {$setc TARGET_CPU_PPC64 := FALSE}
  139. {$setc TARGET_CPU_X86 := FALSE}
  140. {$setc TARGET_CPU_X86_64 := FALSE}
  141. {$setc TARGET_CPU_ARM := FALSE}
  142. {$setc TARGET_CPU_ARM64 := TRUE}
  143. { will require compiler define when/if other Apple devices with ARM cpus ship }
  144. {$setc TARGET_OS_MAC := FALSE}
  145. {$setc TARGET_OS_IPHONE := TRUE}
  146. {$setc TARGET_IPHONE_SIMULATOR := FALSE}
  147. {$setc TARGET_OS_EMBEDDED := TRUE}
  148. {$elsec}
  149. {$error __ppc__ nor __ppc64__ nor __i386__ nor __x86_64__ nor __arm__ nor __arm64__ is defined.}
  150. {$endc}
  151. {$ifc defined __LP64__ and __LP64__ }
  152. {$setc TARGET_CPU_64 := TRUE}
  153. {$elsec}
  154. {$setc TARGET_CPU_64 := FALSE}
  155. {$endc}
  156. {$ifc defined FPC_BIG_ENDIAN}
  157. {$setc TARGET_RT_BIG_ENDIAN := TRUE}
  158. {$setc TARGET_RT_LITTLE_ENDIAN := FALSE}
  159. {$elifc defined FPC_LITTLE_ENDIAN}
  160. {$setc TARGET_RT_BIG_ENDIAN := FALSE}
  161. {$setc TARGET_RT_LITTLE_ENDIAN := TRUE}
  162. {$elsec}
  163. {$error Neither FPC_BIG_ENDIAN nor FPC_LITTLE_ENDIAN are defined.}
  164. {$endc}
  165. {$setc ACCESSOR_CALLS_ARE_FUNCTIONS := TRUE}
  166. {$setc CALL_NOT_IN_CARBON := FALSE}
  167. {$setc OLDROUTINENAMES := FALSE}
  168. {$setc OPAQUE_TOOLBOX_STRUCTS := TRUE}
  169. {$setc OPAQUE_UPP_TYPES := TRUE}
  170. {$setc OTCARBONAPPLICATION := TRUE}
  171. {$setc OTKERNEL := FALSE}
  172. {$setc PM_USE_SESSION_APIS := TRUE}
  173. {$setc TARGET_API_MAC_CARBON := TRUE}
  174. {$setc TARGET_API_MAC_OS8 := FALSE}
  175. {$setc TARGET_API_MAC_OSX := TRUE}
  176. {$setc TARGET_CARBON := TRUE}
  177. {$setc TARGET_CPU_68K := FALSE}
  178. {$setc TARGET_CPU_MIPS := FALSE}
  179. {$setc TARGET_CPU_SPARC := FALSE}
  180. {$setc TARGET_OS_UNIX := FALSE}
  181. {$setc TARGET_OS_WIN32 := FALSE}
  182. {$setc TARGET_RT_MAC_68881 := FALSE}
  183. {$setc TARGET_RT_MAC_CFM := FALSE}
  184. {$setc TARGET_RT_MAC_MACHO := TRUE}
  185. {$setc TYPED_FUNCTION_POINTERS := TRUE}
  186. {$setc TYPE_BOOL := FALSE}
  187. {$setc TYPE_EXTENDED := FALSE}
  188. {$setc TYPE_LONGLONG := TRUE}
  189. uses MacTypes,CFBase,CFString,CFDictionary,CFArray,MDItem,MacOSXPosix;
  190. {$endc} {not MACOSALLINCLUDE}
  191. {$ifc TARGET_OS_MAC}
  192. {$ALIGN POWER}
  193. {!
  194. @header MDQuery
  195. MDQuery is a CF-compliant object, and follows the CF conventions,
  196. and can be used with the CF polymorphic functions, like CFRetain().
  197. MDQuery encapsulates all queries against the MetaData
  198. database. Queries gather results or process updates only while
  199. the current thread's run loop is running. Queries normally
  200. operate asynchronously, and only send out progress
  201. notificiations as the list is being collected. The query list
  202. is kept up to date with respect to value lists and sorting as
  203. the progress notifications are sent out, so the query is in a
  204. good state during those events.
  205. Result Retreval
  206. An MDQueryRef presents its results as if it were a simple
  207. array object. The results can either be MDItemRefs (the
  208. default) or custom structs, CFTypeRefs, or Objective C
  209. objects. For example if the result objects are represented
  210. as 'FSNodes' (a type defined in the client application) a
  211. call to MDQueryGetResultAtIndex() will return an FSNode
  212. object. This is useful, because it allows the Metadata
  213. library to maintain the results in a form that is directly
  214. useable in the application.
  215. Query Sorting
  216. Sorting the results from a query can be performed in one of
  217. two ways. First is to let the library sort the results for you
  218. by passing an array of attributes to sort on to
  219. MDQueryCreate(). The default sort provided by MDQueryCreate()
  220. is a assending sort strings are compared using
  221. CFStringCompare() with the options kCFCompareNonliteral |
  222. kCFCompareLocalized | kCFCompareNumerically. CFDataRefs are
  223. compared by using memcmp() of the data pointers. If an Item
  224. does not have the attribute, it compares less than the
  225. attribute that is there.
  226. If you need to do a more complex sort (like a case insensitive
  227. sort on CFStringRefs) then you will need to also provide a
  228. comparitor function and call MDQuerySetSortComparator(), and
  229. also provide which attributes to sort on to MDQueryCreate().
  230. Undefined Behavior
  231. For functions which take an MDQueryRef parameter, if this
  232. parameter is not a valid MDQueryRef, the behavior is
  233. undefined. NULL is not a valid MDQueryRef.
  234. For functions which take CF*Ref parameters, such as
  235. CFStringRef and CFArrayRef, if this parameter is not a
  236. valid CF object of the correct type, the behavior is
  237. undefined. NULL is not a valid CF*Ref.
  238. Additional constraints or allowed values on parameters
  239. are noted with the specific functions.
  240. }
  241. {!
  242. @typedef MDQueryRef
  243. This is the type of a reference to MDQuerys.
  244. }
  245. type
  246. MDQueryRef = ^__MDQuery; { an opaque type }
  247. __MDQuery = record end;
  248. const
  249. kMDQuerySynchronous = 1;
  250. kMDQueryWantsUpdates = 4;
  251. type
  252. MDQueryOptionFlags = SIGNEDLONG;
  253. {!
  254. @enum MDQueryOptionFlags
  255. @constant kMDQuerySynchronous Block during the gathering phase.
  256. If this parameter is true, the function will not return
  257. until the query has finished gathering the initial
  258. results. The run loop will run in the default mode, which
  259. will allow anything registered in that mode with this run
  260. loop to execute as well. If this parameter is false, the
  261. function returns immediately after starting the query
  262. asychronously.
  263. @constant kMDQueryWantsUpdates When set, after gathering the initial results
  264. the query will watch for changes in the system which should
  265. update the list of results. This can be changes which cause
  266. new files to now match the query, or changes which cause
  267. files in the result list to continue to match, or no longer
  268. match, the query. Files which begin to match the query are
  269. added to the result list, and files which no longer match
  270. the query expression are removed from the result list.
  271. Currently, this parameter is ignored if the synchronous
  272. parameter is true. This is subject to change, and you
  273. should always pass in the value you want here.
  274. }
  275. {!
  276. @function MDQueryGetTypeID
  277. Returns the type identifier of all MDQuery instances.
  278. }
  279. function MDQueryGetTypeID: CFTypeID; external name '_MDQueryGetTypeID';
  280. (* AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER *)
  281. {!
  282. @function MDQueryCreate
  283. Creates a new query with the given query expression.
  284. @param allocator The CFAllocator which should be used to allocate
  285. memory for the query and its sub-storage. This
  286. parameter may be NULL in which case the current default
  287. CFAllocator is used.
  288. @param queryString The query expression string for this query. The
  289. syntax for query expressions is explained above in the
  290. header overview documentation.
  291. @param valueListAttrs An optional array of attribute names. The
  292. query will collect the values of these attributes into
  293. uniqued lists, which can be used or displayed to summarize
  294. the results of the query, or allow a user to further
  295. qualify the items for which they are searching. This
  296. parameter may be NULL if no value lists are desired. Value
  297. list collection increases CPU usage and significantly
  298. increases the memory usage of an MDQuery. The attribute
  299. names are CFStrings.
  300. @param sortingAttrs An optional array of attribute names. The
  301. query will results of the query based on the values of
  302. these attributes. The first name in the array is used as
  303. the primary sort key, the second as the secondary key, and
  304. so on. The comparison of like-typed values is a simple,
  305. literal comparison. This parameter may be NULL if no
  306. sorting is desired. Sorting increases memory usage and
  307. significantly increases the CPU usage of an MDQuery.
  308. However, when possible, it is almost always cheaper to have
  309. the MDQuery do the sorting, rather than you fetching all
  310. the results and attributes from each of them and doing the
  311. sorting yourself. The attribute names are CFStrings.
  312. @result An MDQueryRef, or NULL on failure. If the query string
  313. is empty or malformed (invalid syntax), returns NULL.
  314. }
  315. function MDQueryCreate( allocator: CFAllocatorRef; queryString: CFStringRef; valueListAttrs: CFArrayRef; sortingAttrs: CFArrayRef ): MDQueryRef; external name '_MDQueryCreate';
  316. (* AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER *)
  317. {!
  318. @function MDQueryCreateSubset
  319. Creates a new query, which is a subset of the given query. Only
  320. results matched by the given query can be matched by the
  321. query expression of this query.
  322. @param allocator The CFAllocator which should be used to allocate
  323. memory for the query and its sub-storage. This
  324. parameter may be NULL in which case the current default
  325. CFAllocator is used.
  326. @param query The parent query of the new query.
  327. @param queryString The query expression string for this query.
  328. This expression in effect may further restrict the matches
  329. found by the parent query. If the string is empty the
  330. behavior is undefined.
  331. @param valueListAttrs An optional array of attribute names. The
  332. query will collect the values of these attributes into
  333. uniqued lists, which can be used or displayed to summarize
  334. the results of the query, or allow a user to further
  335. qualify the items for which they are searching. This
  336. parameter may be NULL if no value lists are desired. Value
  337. list collection increases CPU usage and significantly
  338. increases the memory usage of an MDQuery. The attribute
  339. names are CFStrings.
  340. @param sortingAttrs An optional array of attribute names. The
  341. query will results of the query based on the values of
  342. these attributes. The first name in the array is used as
  343. the primary sort key, the second as the secondary key, and
  344. so on. The comparison of like-typed values is a simple,
  345. literal comparison. This parameter may be NULL if no
  346. sorting is desired. Sorting increases memory usage and
  347. significantly increases the CPU usage of an MDQuery.
  348. However, when possible, it is almost always cheaper to have
  349. the MDQuery do the sorting, rather than you fetching all
  350. the results and attributes from each of them and doing the
  351. sorting yourself. The attribute names are CFStrings.
  352. @result An MDQueryRef, or NULL on failure. If the query string
  353. is empty or malformed (invalid syntax), returns NULL.
  354. }
  355. function MDQueryCreateSubset( allocator: CFAllocatorRef; query: MDQueryRef; queryString: CFStringRef; valueListAttrs: CFArrayRef; sortingAttrs: CFArrayRef ): MDQueryRef; external name '_MDQueryCreateSubset';
  356. (* AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER *)
  357. {!
  358. @function MDQueryCreateForItems
  359. Creates a new query with the given query expression.
  360. @param allocator The CFAllocator which should be used to allocate
  361. memory for the query and its sub-storage. This
  362. parameter may be NULL in which case the current default
  363. CFAllocator is used.
  364. @param queryString The query expression string for this query. The
  365. syntax for query expressions is explained above in the
  366. header overview documentation.
  367. @param valueListAttrs An optional array of attribute names. The
  368. query will collect the values of these attributes into
  369. uniqued lists, which can be used or displayed to summarize
  370. the results of the query, or allow a user to further
  371. qualify the items for which they are searching. This
  372. parameter may be NULL if no value lists are desired. Value
  373. list collection increases CPU usage and significantly
  374. increases the memory usage of an MDQuery. The attribute
  375. names are CFStrings.
  376. @param sortingAttrs An optional array of attribute names. The
  377. query will results of the query based on the values of
  378. these attributes. The first name in the array is used as
  379. the primary sort key, the second as the secondary key, and
  380. so on. The comparison of like-typed values is a simple,
  381. literal comparison. This parameter may be NULL if no
  382. sorting is desired. Sorting increases memory usage and
  383. significantly increases the CPU usage of an MDQuery.
  384. However, when possible, it is almost always cheaper to have
  385. the MDQuery do the sorting, rather than you fetching all
  386. the results and attributes from each of them and doing the
  387. sorting yourself. The attribute names are CFStrings.
  388. @param items An array of items. The query will only return results
  389. in this set.
  390. @result An MDQueryRef, or NULL on failure. If the query string
  391. is empty or malformed (invalid syntax), returns NULL.
  392. }
  393. function MDQueryCreateForItems( allocator: CFAllocatorRef; queryString: CFStringRef; valueListAttrs: CFArrayRef; sortingAttrs: CFArrayRef; items: CFArrayRef ): MDQueryRef; external name '_MDQueryCreateForItems';
  394. (* AVAILABLE_MAC_OS_X_VERSION_10_7_AND_LATER *)
  395. {!
  396. @function MDQueryCopyQueryString
  397. Returns the query string of the query.
  398. @param query The query to be interrogated.
  399. @result The query string of the query.
  400. }
  401. function MDQueryCopyQueryString( query: MDQueryRef ): CFStringRef; external name '_MDQueryCopyQueryString';
  402. (* AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER *)
  403. {!
  404. @function MDQueryCopyValueListAttributes
  405. Returns the list of attribute names for which the query is
  406. collecting the lists of values.
  407. @param query The query to be interrogated.
  408. @result The list of value list attribute names of the query.
  409. }
  410. function MDQueryCopyValueListAttributes( query: MDQueryRef ): CFArrayRef; external name '_MDQueryCopyValueListAttributes';
  411. (* AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER *)
  412. {!
  413. @function MDQueryCopySortingAttributes
  414. Returns the list of attribute names the query is using to sort
  415. the results.
  416. @param query The query to be interrogated.
  417. @result The list of sorting attribute names of the query.
  418. }
  419. function MDQueryCopySortingAttributes( query: MDQueryRef ): CFArrayRef; external name '_MDQueryCopySortingAttributes';
  420. (* AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER *)
  421. {!
  422. @typedef MDQueryBatchingParams
  423. Structure containing the progress notification batching
  424. parameters of an MDQuery. The first notification can be
  425. triggered by the either first_max_num or first_max_ms limit
  426. being exceeded. Subsequent notifications are triggered by
  427. either the progress_max_num or progress_max_ms limit. The
  428. default batching parameters are undefined and subject to
  429. change.
  430. @field first_max_num The maximum number of results that can
  431. accumulate before a progress notification is sent out
  432. by the MDQuery, for the first notification.
  433. @field first_max_ms The maximum number of milliseconds that can
  434. pass before a progress notification is sent out. This
  435. value is advisory, in that the notification will be
  436. triggered "at some point after first_max_ms milliseconds
  437. have passed since the query began accumulating results",
  438. but generally not very long after, for the first
  439. progress notification.
  440. @field progress_max_num The maximum number of results that can
  441. accumulate before a progress notification is sent out
  442. by the MDQuery, for notifications after the first,
  443. during the initial gathering phase of the query.
  444. @field progress_max_ms The maximum number of milliseconds that can
  445. pass before a progress notification is sent out. This
  446. value is advisory, in that the notification will be
  447. triggered "at some point after first_max_ms milliseconds
  448. have passed since the query began accumulating results",
  449. but generally not very long after, for progress
  450. notifications after the first, during the initial
  451. gathering phase of the query.
  452. @field update_max_num The maximum number of results that can
  453. accumulate before an update notification is sent out
  454. by the MDQuery, for notifications after the gathering
  455. phase of the query has finished.
  456. @field update_max_ms The maximum number of milliseconds that can
  457. pass before a progress notification is sent out. This
  458. value is advisory, in that the notification will be
  459. triggered "at some point after first_max_ms milliseconds
  460. have passed since the query began accumulating results",
  461. but generally not very long after, for update notifications
  462. after the gathering phase of the query has finished.
  463. }
  464. type
  465. MDQueryBatchingParams = record
  466. first_max_num: size_t;
  467. first_max_ms: size_t;
  468. progress_max_num: size_t;
  469. progress_max_ms: size_t;
  470. update_max_num: size_t;
  471. update_max_ms: size_t;
  472. end;
  473. {!
  474. @function MDQueryGetBatchingParameters
  475. Returns the current parameters that control batching of progress
  476. notifications.
  477. @param query The query to be interrogated.
  478. @result An MDQueryBatchingParams structure with the current
  479. batching parameters.
  480. }
  481. function MDQueryGetBatchingParameters( query: MDQueryRef ): MDQueryBatchingParams; external name '_MDQueryGetBatchingParameters';
  482. (* AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER *)
  483. {!
  484. @function MDQuerySetBatchingParameters
  485. @param query The query whose batching parameters are to be set.
  486. @param params An MDQueryBatchingParams structure with the batching
  487. parameters to set.
  488. }
  489. procedure MDQuerySetBatchingParameters( query: MDQueryRef; params: MDQueryBatchingParams ); external name '_MDQuerySetBatchingParameters';
  490. (* AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER *)
  491. {!
  492. @typedef MDQueryCreateResultFunction
  493. Type of the callback function used to create the result objects
  494. stored and returned by an MDQuery. The function may
  495. hold onto the given MDItemRef in some other data
  496. structure, but must retain it for it to remain valid.
  497. The create-result function is called lazily as results
  498. are requested from a query, so it will not generally
  499. be called on all results, if in fact any. This avoids
  500. the cost of creating potentially hundreds of thousands
  501. of what might be temporary objects.
  502. @param query The MDQuery instance.
  503. @param item The default MDItemRef for the result.
  504. @param context The user-defined context parameter given to
  505. MDQuerySetCreateResultFunction().
  506. @result The function must return a pointer-sized value that can
  507. be managed with the callbacks which were set at the same
  508. time the create function was given to the query. The
  509. value must be returned with a reference (such as if the
  510. retain callback had been called on it), as implied by the
  511. Create name. If this function doesn't wish to create a
  512. new object, it can return the given MDItemRef, but must
  513. also return it with a new retain, and the callbacks must
  514. be able to handle an MDItemRef as an input value. If
  515. this function returns NULL, NULL will be stored for the
  516. moment in the query, MDQueryGetResultAtIndex() may return
  517. NULL for that result, and the next time the query wants
  518. the result, it will call this function again.
  519. }
  520. type
  521. MDQueryCreateResultFunction = function( query: MDQueryRef; item: MDItemRef; context: UnivPtr ): UnivPtr;
  522. {!
  523. @function MDQuerySetCreateResultFunction
  524. Sets the function used to create the result objects of the
  525. MDQuery. If no create function is set on an MDQuery,
  526. the default result objects are MDItemRefs. Results
  527. created after a create function is set will be created
  528. through the given create function, but values created
  529. before the function was set (or after it is unset) are
  530. not modified. Therefore it is not advisable to change
  531. this function after MDQueryExecute() has been called
  532. with the query. The create-result function is called
  533. lazily as results are requested from a query, so it will
  534. not generally be called on all results, if in fact any.
  535. This avoids the cost of creating potentially hundreds
  536. of thousands of what might be temporary objects.
  537. @param query The query to whose result create function is to be set.
  538. @param func The callback function the MDQuery will use to
  539. create its results, such as those returned from
  540. MDQueryGetResultAtIndex(). This parameter
  541. may be NULL, in which case any previous result creation
  542. settings are cancelled, and the MDQuery will subsequently
  543. produce MDItemRefs. If the function (when the parameter is
  544. not NULL) is not of type MDQueryCreateResultFunction or
  545. does not behave as a MDQueryCreateResultFunction must,
  546. the behavior is undefined.
  547. @param context A pointer-sized user-defined value, which is
  548. passed as the third parameter to the create function,
  549. but is otherwise unused by MDQuery. The MDQuery does
  550. not retain the context in any way, so it must remain
  551. valid for at least the lifetime of the query. If the
  552. context is not what is expected by the create function,
  553. the behavior is undefined.
  554. @param cb A pointer to a CFArrayCallBacks structure
  555. initialized with the callbacks for the query to use to
  556. manage the created result objects. A copy of the
  557. contents of the callbacks structure is made, so that a
  558. pointer to a structure on the stack can be passed in, or
  559. can be reused for multiple query creations. Only version
  560. 0 of the CFArrayCallBacks is supported. The retain field
  561. may be NULL, in which case the MDQuery will do nothing to
  562. add a retain to the created results for the query. The
  563. release field may be NULL, in which case the MDQuery will
  564. do nothing to remove the query's retain (such as the one
  565. it gets from the create function) on the result objects
  566. when the query is destroyed. If the copyDescription field
  567. is NULL, the query will create a simple description for
  568. the result objects. If the equal field is NULL, the query
  569. will use pointer equality to test for equality of results.
  570. This callbacks parameter itself may be NULL, which is
  571. treated as if a valid structure of version 0 with all
  572. fields NULL had been passed in. Otherwise, if any of the
  573. fields are not valid pointers to functions of the correct
  574. type, or this parameter is not a valid pointer to a
  575. CFArrayCallBacks callbacks structure, the behavior is
  576. undefined. If any of the value values returned from the
  577. create function is not one understood by one or more of
  578. the callback functions, the behavior when those callback
  579. functions are used is undefined. For example, if the create
  580. function can return NULL, then NULL must be understood by
  581. the callback functions as a possible parameter. The retain
  582. and release callbacks must be a matched set -- do not
  583. assume that the retain function will be unused or that
  584. additional reference counts will not be taken on the
  585. created results.
  586. }
  587. procedure MDQuerySetCreateResultFunction( query: MDQueryRef; func: MDQueryCreateResultFunction; context: UnivPtr; {const} cb: CFArrayCallBacksPtr ); external name '_MDQuerySetCreateResultFunction';
  588. (* AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER *)
  589. {!
  590. @typedef MDQueryCreateValueFunction
  591. Type of the callback function used to create the value objects
  592. stored and returned by an MDQuery. The function may
  593. hold onto the given attribute name and/or value in some
  594. other data structure, but must retain them for them to
  595. remain valid.
  596. @param query The MDQuery instance.
  597. @param attrName The attribute name of the value.
  598. @param attrValue The default value of the value.
  599. @param context The user-defined context parameter given to
  600. MDQuerySetCreateValueFunction().
  601. @result The function must return a pointer-sized value that can
  602. be managed with the callbacks which were set at the same
  603. time the create function was given to the query. The
  604. value must be returned with a reference (such as if the
  605. retain callback had been called on it), as implied by the
  606. Create name. If this function doesn't wish to create a
  607. new object, it can return the given CFTypeRef, but must
  608. also return it with a new retain, and the callbacks must
  609. be able to handle a CFTypeRef as an input value.
  610. }
  611. type
  612. MDQueryCreateValueFunction = function( query: MDQueryRef; attrName: CFStringRef; attrValue: CFTypeRef; context: UnivPtr ): UnivPtr;
  613. {!
  614. @function MDQuerySetCreateValueFunction
  615. Sets the function used to create the value objects of the
  616. MDQuery. These are the values of the value lists that
  617. were requested when the query was created. If no create
  618. function is set on an MDQuery, the default value objects
  619. are the CFTypeRef values of the attributes. Values
  620. created after a create function is set will be created
  621. through the given create function, but values created
  622. before the function was set (or after it is unset)
  623. are not modified. Therefore it is not advisable to
  624. change this function after MDQueryExecute() has been
  625. called with the query.
  626. @param query The query to whose value create function is to be set.
  627. @param func The callback function the MDQuery will use to
  628. create the value list values, such as those returned from
  629. MDQueryCopyValuesOfAttribute(). This parameter
  630. may be NULL, in which case any previous value creation
  631. settings are cancelled, and the MDQuery will subsequently
  632. produce the default CFTypeRefs. If the function (when the
  633. parameter is not NULL) is not of type
  634. MDQueryCreateValueFunction or does not behave as a
  635. MDQueryCreateValueFunction must, the behavior is undefined.
  636. @param context A pointer-sized user-defined value, which is
  637. passed as the fourth parameter to the create function,
  638. but is otherwise unused by MDQuery. The MDQuery does
  639. not retain the context in any way, so it must remain
  640. valid for at least the lifetime of the query. If the
  641. context is not what is expected by the create function,
  642. the behavior is undefined.
  643. @param cb A pointer to a CFArrayCallBacks structure
  644. initialized with the callbacks for the query to use to
  645. manage the created value objects. A copy of the
  646. contents of the callbacks structure is made, so that a
  647. pointer to a structure on the stack can be passed in, or
  648. can be reused for multiple query creations. Only version
  649. 0 of the CFArrayCallBacks is supported. The retain field
  650. may be NULL, in which case the MDQuery will do nothing to
  651. add a retain to the created values for the query. The
  652. release field may be NULL, in which case the MDQuery will
  653. do nothing to remove the query's retain (such as the one
  654. it gets from the create function) on the value objects
  655. when the query is destroyed. If the copyDescription field
  656. is NULL, the query will create a simple description for
  657. the value objects. If the equal field is NULL, the query
  658. will use pointer equality to test for equality of values.
  659. This callbacks parameter itself may be NULL, which is
  660. treated as if a valid structure of version 0 with all
  661. fields NULL had been passed in. Otherwise, if any of the
  662. fields are not valid pointers to functions of the correct
  663. type, or this parameter is not a valid pointer to a
  664. CFArrayCallBacks callbacks structure, the behavior is
  665. undefined. If any of the value values returned from the
  666. create function is not one understood by one or more of
  667. the callback functions, the behavior when those callback
  668. functions are used is undefined. For example, if the
  669. create function can return NULL, then NULL must be
  670. understood by the callback functions as a possible
  671. parameter. The retain and release callbacks must be a
  672. matched set -- do not assume that the retain function will
  673. be unused or that additional reference counts will not be
  674. taken on the created values.
  675. }
  676. procedure MDQuerySetCreateValueFunction( query: MDQueryRef; func: MDQueryCreateValueFunction; context: UnivPtr; {const} cb: CFArrayCallBacksPtr ); external name '_MDQuerySetCreateValueFunction';
  677. (* AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER *)
  678. {!
  679. @function MDQuerySetDispatchQueue
  680. Set the dispatch queue on which query results will be delivered
  681. by MDQueryExecute. It is not advisable to change set
  682. dispatch queue after MDQueryExecute() has been called with
  683. the query. Setting the dispatch queue for a synchronous
  684. query (kMDQuerySynchronous) has no effect.
  685. @param query The query for which the dispatch queue should be set.
  686. @param queue The dispatch queue on which results should be delivered.
  687. }
  688. procedure MDQuerySetDispatchQueue( query: MDQueryRef; queue: dispatch_queue_t ); external name '_MDQuerySetDispatchQueue';
  689. (* AVAILABLE_MAC_OS_X_VERSION_10_6_AND_LATER *)
  690. {!
  691. @function MDQueryExecute
  692. Run the query, and populate the query with the results. Queries
  693. only gather results or process updates while the current
  694. thread's run loop is running. Queries normally operate
  695. asynchronously, and send out progress and update
  696. notifications to report changes to the list of results
  697. that has been collected. Queries have two phases: the
  698. initial gathering of all currently matching results, and
  699. a second live-update phase where queries monitor the
  700. state of the system and update themselves to external
  701. changes in files or the operating environment (for example,
  702. as time advances, files which did not match the query
  703. when it was started may later match the query). Query
  704. notifications are posted within the context of the same
  705. thread which executes the query.
  706. [[There are three operational modes: (1) synchronous static
  707. queries, which collect the list of current results and then
  708. do not watch for updates to the results, (2) asynchronous
  709. static queries, which collect the results asychronously
  710. after this function returns, and then do not watch for
  711. updates to the results, and (3) asynchronous live queries
  712. which collect the initial results asychronously after this
  713. function returns, and then do watch for updates to the
  714. results, until the query is destroyed. There is little
  715. reason not to allow the fourth case, synchronous collection
  716. of initial results, followed by asynchronous monitoring
  717. for updates, so this may change in the future.]]
  718. @param query The query to execute.
  719. @param optionFlags Bitwise or of MDQueryOptionFlags
  720. @result Returns true if the query was started (executed in the case
  721. of a synchronous query), false otherwise. Queries cannot be
  722. executed more than once.
  723. }
  724. function MDQueryExecute( query: MDQueryRef; optionFlags: CFOptionFlags ): Boolean; external name '_MDQueryExecute';
  725. (* AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER *)
  726. {!
  727. @function MDQueryStop
  728. Stops the query from ever generating more results. Queries may be
  729. executed only once, so a stopped query cannot be
  730. restarted. The query will also not generate any result
  731. updates. The query is static after this function returns.
  732. The query will do final processing of results that have
  733. come in but not yet been processed (because, say, the
  734. batching parameters hasn't triggered that yet). That may
  735. trigger a progress notification, so be aware of that if
  736. you are stopping a query from within your progress note
  737. handler; that is, during this function, a recursive
  738. progress and/or finished notification might occur, which
  739. might recursively call your notification handler. It is
  740. safe to call this function recursively. You would call
  741. this function to stop a query that is generating way too
  742. many results to be useful, but still want to access the
  743. results that have come in so far. If a query is stopped
  744. before the gathering phase finishes, it will not report
  745. itself as finished, nor will it send out a finished
  746. notification.
  747. @param query The query to stop.
  748. }
  749. procedure MDQueryStop( query: MDQueryRef ); external name '_MDQueryStop';
  750. (* AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER *)
  751. {!
  752. @function MDQueryDisableUpdates
  753. Disables updates to the query result list. This should be called
  754. before iterating through the list of results to prevent
  755. the result list from changing during the iteration. The
  756. disabled state is a counter, and disabling can be done
  757. recursively and from different threads.
  758. @param query The query for which updates are to be disabled.
  759. @result The generation number of the query. This changes each time the query's
  760. result set has changed.
  761. }
  762. procedure MDQueryDisableUpdates( query: MDQueryRef ); external name '_MDQueryDisableUpdates';
  763. (* AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER *)
  764. {!
  765. @function MDQueryEnableUpdates
  766. Re-enables updates to the query result list. This should be called
  767. when finished iterating through the list of results, to
  768. allow changes to the result list to occur. Changes will
  769. be allowed when all the disables have been matched by a
  770. corresponding enable.
  771. @param query The query for which updates are to be enabled.
  772. }
  773. procedure MDQueryEnableUpdates( query: MDQueryRef ); external name '_MDQueryEnableUpdates';
  774. (* AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER *)
  775. {!
  776. @function MDQueryIsGatheringComplete
  777. Returns true if the first phase of a query, the initial result
  778. gathering, has finished.
  779. @param query The query to be interrogated.
  780. @result A boolean indicating whether or not the first phase
  781. of a query has completed.
  782. }
  783. function MDQueryIsGatheringComplete( query: MDQueryRef ): Boolean; external name '_MDQueryIsGatheringComplete';
  784. (* AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER *)
  785. {!
  786. @function MDQueryGetResultCount
  787. Returns the number of results currently collected by the query.
  788. Note that the number of results in a query will change
  789. over time as the query's result list is updated.
  790. @param query The query to be interrogated.
  791. @result The number of results in the query.
  792. }
  793. function MDQueryGetResultCount( query: MDQueryRef ): CFIndex; external name '_MDQueryGetResultCount';
  794. (* AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER *)
  795. {!
  796. @function MDQueryGetResultAtIndex
  797. Returns the current result at the given index. This function
  798. causes the result object to be created if it hasn't
  799. been created already. For performance reasons, it is
  800. not advisable to ask for results that you don't need,
  801. to avoid the cost of creating them. If possible, call
  802. this function to fetch only the results you need to
  803. display or otherwise process. Note that the index of
  804. a particular result will change over time, as the
  805. query's result list is updated.
  806. @param query The query to be interrogated.
  807. @param idx The index into the query's result list. If the index is
  808. negative, or is equal to or larger than the current
  809. number of results in the query, the behavior is undefined.
  810. @result Returns the MDItemRef currently at the given index, or
  811. if a result-create function has been set, returns the
  812. result returned by that function.
  813. }
  814. function MDQueryGetResultAtIndex( query: MDQueryRef; idx: CFIndex ): UnivPtr; external name '_MDQueryGetResultAtIndex';
  815. (* AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER *)
  816. {!
  817. @function MDQueryGetIndexOfResult
  818. Returns the current index of the given result. If a result-create
  819. function has been set, and the equal callback is non-NULL,
  820. it will be used to test the query's results against the
  821. candidate result. Note that the index of a result will
  822. change over time, as the query's result list is updated.
  823. @param query The query to be interrogated.
  824. @param result The candidate result object for which to search.
  825. If a custom create-result function has been set, and this
  826. parameter is not a valid result object that the provided
  827. callbacks can handle, the behavior is undefined. If a custom
  828. create-result function has not been set, this parameter
  829. must be a valid MDItemRef.
  830. @result The index of the given result, or kCFNotFound if the
  831. value is not one of the query's existing results. If
  832. you provided a custom result creation function,
  833. as well as a custom object comparator function,
  834. result will be objects created by that function.
  835. }
  836. function MDQueryGetIndexOfResult( query: MDQueryRef; result: {const} UnivPtr ): CFIndex; external name '_MDQueryGetIndexOfResult';
  837. (* AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER *)
  838. {!
  839. @function MDQueryGetAttributeValueOfResultAtIndex
  840. Returns the value of the named attribute for the result at
  841. the given index.
  842. @param query The query to be interrogated.
  843. @param name The attribute name for which to return the values.
  844. If the attribute is not one of those requested in the
  845. valueListAttrs or sortingAttrs parameters to one of
  846. the query creation functions, the result will be NULL.
  847. @param idx The index into the query's result list. If the index is
  848. negative, or is equal to or larger than the current
  849. number of results in the query, the behavior is undefined.
  850. @result The value of the attribute, or NULL if the attribute
  851. doesn't exist in the query on that result.
  852. }
  853. function MDQueryGetAttributeValueOfResultAtIndex( query: MDQueryRef; name: CFStringRef; idx: CFIndex ): UnivPtr; external name '_MDQueryGetAttributeValueOfResultAtIndex';
  854. (* AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER *)
  855. {!
  856. @function MDQueryCopyValuesOfAttribute
  857. Returns the list of values, from the results of the query, of the
  858. named attribute. The list is not ordered in any way. The
  859. list contains only one occurrence of each value. Note that
  860. this list may change over time, as the query's result list
  861. is updated.
  862. @param query The query to be interrogated.
  863. @param name The attribute name for which to return the values.
  864. If the attribute is not one of those requested in the
  865. valueListAttrs parameter to one of the query creation
  866. functions, the behavior is undefined.
  867. @result A CFArray holding the value objects for that attribute.
  868. }
  869. function MDQueryCopyValuesOfAttribute( query: MDQueryRef; name: CFStringRef ): CFArrayRef; external name '_MDQueryCopyValuesOfAttribute';
  870. (* AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER *)
  871. {!
  872. @function MDQueryGetCountOfResultsWithAttributeValue
  873. Returns the number of results which have the given attribute and
  874. attribute value. Note that this count may change over time,
  875. as the query's result list is updated.
  876. @param query The query to be interrogated.
  877. @param name The attribute name for which to return the number
  878. of results with the given value. If the attribute is not
  879. one of those requested in the valueListAttrs parameter to
  880. one of the query creation functions, the behavior is
  881. undefined.
  882. @param value The attribute value for which to return the number
  883. of results with that value. This parameter may be NULL,
  884. in which case the number of results that do not contain
  885. the named attribute is returned.
  886. @result The number of results with that attribute and value.
  887. }
  888. function MDQueryGetCountOfResultsWithAttributeValue( query: MDQueryRef; name: CFStringRef; value: CFTypeRef ): CFIndex; external name '_MDQueryGetCountOfResultsWithAttributeValue';
  889. (* AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER *)
  890. {!
  891. @function MDQuerySetSortOrder
  892. Sets the sort order for a query.
  893. @param query The query for which the sort order is to be set.
  894. @param sortingAttrs An array of attribute names, as in MDQueryCreate.
  895. The query's result set will be sorted according to the order of
  896. these attributes. All names in the array have to have been passed
  897. as sortingAttrs when the query was created. The attribute names
  898. are CFStrings
  899. @result A boolean, true on success, false on failure.
  900. }
  901. function MDQuerySetSortOrder( query: MDQueryRef; sortingAttrs: CFArrayRef ): Boolean; external name '_MDQuerySetSortOrder';
  902. (* AVAILABLE_MAC_OS_X_VERSION_10_7_AND_LATER *)
  903. {!
  904. @enum MDQuerySortOptionFlags
  905. @constant kMDQueryReverseSortOrderFlag Sort the attribute in reverse order.
  906. }
  907. const
  908. kMDQueryReverseSortOrderFlag = (1 shl 0);
  909. type
  910. MDQuerySortOptionFlags = SIGNEDLONG;
  911. {!
  912. @function MDQuerySetSortOptionFlagsForAttribute
  913. Sets the sort flags for a query.
  914. @param query The query for which the sort flags is to be set.
  915. @param fieldName The attribute name for which sort option flags are to be set.
  916. The attribute name must have been part of the sortingFlags when the query was created.
  917. @param flags A uint32_t containing MDQuerySortOptionFlags to be applied to the attibute
  918. @result A boolean, true on success, false on failure.
  919. }
  920. function MDQuerySetSortOptionFlagsForAttribute( query: MDQueryRef; fieldName: CFStringRef; flags: UInt32 ): Boolean; external name '_MDQuerySetSortOptionFlagsForAttribute';
  921. (* AVAILABLE_MAC_OS_X_VERSION_10_7_AND_LATER *)
  922. {!
  923. @function MDQueryGetSortOptionFlagsForAttribute
  924. Gets the sort option flags for a sorting attribute.
  925. @param query The query for which fetch sort option flags.
  926. @param fieldName The attribute name for which sort option flags are to be fetched.
  927. @result A uint32_t, with MDQuerySortOptionFlags set for the attribute.
  928. }
  929. function MDQueryGetSortOptionFlagsForAttribute( query: MDQueryRef; fieldName: CFStringRef ): UInt32; external name '_MDQueryGetSortOptionFlagsForAttribute';
  930. (* AVAILABLE_MAC_OS_X_VERSION_10_7_AND_LATER *)
  931. {!
  932. @typedef MDQuerySortComparatorFunction
  933. Type of the callback function used to sort the results of an
  934. MDQuery.
  935. @param query The MDQuery instance.
  936. @param attrs1 A C array of attribute values for a result. The
  937. values occur in the array in the same order and position
  938. that the attribute names were passed in the sortingAttrs
  939. array when the query was created. The values of the
  940. attributes might be NULL, if the attribute doesn't exist
  941. on a result or if read access to that attribute is not
  942. allowed.
  943. @param attrs2 A C array of attribute values for a result. The
  944. values occur in the array in the same order and position
  945. that the attribute names were passed in the sortingAttrs
  946. array when the query was created. The values of the
  947. attributes might be NULL, if the attribute doesn't exist
  948. on a result or if read access to that attribute is not
  949. allowed.
  950. @param context The user-defined context parameter given to
  951. MDQuerySetSortComparator().
  952. @result The function must return one of the CFComparisonResults
  953. kCFCompareLessThan, kCFCompareEqualTo, or
  954. kCFCompareGreaterThan. There is no provision for unordered
  955. results. The comparison must be a total order relation,
  956. and additionally produce temporally identical results (that
  957. is, produce the same results for the same inputs in the
  958. future as now), for the sort results to be predictable.
  959. }
  960. type
  961. MDQuerySortComparatorFunction = function( {const} attrs1: {variable-size-array} CFTypeRefPtr; {const} attrs2: {variable-size-array} CFTypeRefPtr; context: UnivPtr ): CFComparisonResult;
  962. {!
  963. @function MDQuerySetSortComparator
  964. Sets the function used to sort the results of an MDQuery. You
  965. may set the comparator function as many times as you
  966. like, even while the query is executing. Whenever the
  967. comparator function is set, all results are re-sorted
  968. using the new comparator function before the function
  969. returns. The function pointer can be NULL to cancel
  970. custom sorting and revert to the default sorting.
  971. The default sort provided by MDQueryCreate()
  972. is a assending sort strings are compared using
  973. CFStringCompare() with the options kCFCompareNonliteral |
  974. kCFCompareLocalized | kCFCompareNumerically. CFDataRefs are
  975. compared by using memcmp() of the data pointers.
  976. @param query The query to whose result sort function is to be set.
  977. @param func The callback function the MDQuery will use to
  978. sort its results. If the function (when the parameter is
  979. not NULL) is not of type MDQuerySortComparatorFunction or
  980. does not behave as a MDQuerySortComparatorFunction must,
  981. the behavior is undefined. The function pointer may
  982. be NULL to cancel any custom comparator.
  983. @param context A pointer-sized user-defined value, which is
  984. passed as the third parameter to the sort function,
  985. but is otherwise unused by MDQuery. The MDQuery does
  986. not retain the context in any way, so it must remain
  987. valid for the lifetime of the query or until the sort
  988. function is set again. If the context is not what is
  989. expected by the comparator, the behavior is undefined.
  990. }
  991. procedure MDQuerySetSortComparator( query: MDQueryRef; comparator: MDQuerySortComparatorFunction; context: UnivPtr ); external name '_MDQuerySetSortComparator';
  992. (* AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER *)
  993. {!
  994. @function MDQuerySetSortComparatorBlock
  995. Sets the block used to sort the results of an MDQuery. You
  996. may set the comparator block as many times as you
  997. like, even while the query is executing. Whenever the
  998. comparator block is set, all results are re-sorted
  999. using the new comparator block before the function
  1000. returns. The block can be NULL to cancel
  1001. custom sorting and revert to the default sorting.
  1002. The default sort provided by MDQueryCreate()
  1003. is a assending sort strings are compared using
  1004. CFStringCompare() with the options kCFCompareNonliteral |
  1005. kCFCompareLocalized | kCFCompareNumerically. CFDataRefs are
  1006. compared by using memcmp() of the data pointers.
  1007. @param query The query to whose result sort block is to be set.
  1008. @param comparator The callback block the MDQuery will use to
  1009. sort its results. The comparator may be called on multiple threads in
  1010. parallel, and must be reentrant. To take advantage of parallel
  1011. sorting, it is best to avoid any locking in the comparator.
  1012. The block may be NULL to cancel any custom comparator.
  1013. }
  1014. {!
  1015. @constant kMDQueryProgressNotification
  1016. The name of the notification sent to indicate changes to the
  1017. query's results list during the initial gathering phase
  1018. of a query's execution. Mostly adds will occur during
  1019. this phase, but removals and changes can also occur, as
  1020. in any update. This info dictionary parameter of the
  1021. notification can carry the kMDQueryUpdateChangedItems
  1022. and kMDQueryUpdateRemovedItems keys. Note that these
  1023. keys may be have empty arrays for values, or be missing,
  1024. if there are no changes of that particular type. For
  1025. performance reasons, added results are not indicated in
  1026. progress notifications (to avoid the cost of creating
  1027. the result objects). These notifications are sent out
  1028. by a query before the kMDQueryDidFinishNotification.
  1029. }
  1030. var kMDQueryProgressNotification: CFStringRef; external name '_kMDQueryProgressNotification'; (* attribute const *)
  1031. (* AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER *)
  1032. {!
  1033. @constant kMDQueryDidFinishNotification
  1034. The name of the notification sent to indicate that the query has
  1035. finished with the initial result-gathering phase, and may
  1036. now proceed into the live-update phase (if that option
  1037. was chosen when the query was executed). This notification
  1038. often shortly follows after the last progress notification.
  1039. It is usually not necessary to update any displayed UI in
  1040. response to this notification, since it doesn't indicate
  1041. any change in the result list of a query.
  1042. }
  1043. var kMDQueryDidFinishNotification: CFStringRef; external name '_kMDQueryDidFinishNotification'; (* attribute const *)
  1044. (* AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER *)
  1045. {!
  1046. @constant kMDQueryDidUpdateNotification
  1047. The name of the notification sent to indicate changes to the
  1048. query's results list during the second, live-update, phase
  1049. of a query's execution. This notification can carry the
  1050. kMDQueryUpdateAddedItems, kMDQueryUpdateChangedItems,
  1051. and kMDQueryUpdateRemovedItems keys in the info
  1052. dictionary parameter of the notification. Note that these
  1053. keys may be have empty arrays for values, or be missing,
  1054. if there are no changes of that particular type. These
  1055. notifications are sent out by a query after the
  1056. kMDQueryDidUpdateNotification.
  1057. }
  1058. var kMDQueryDidUpdateNotification: CFStringRef; external name '_kMDQueryDidUpdateNotification'; (* attribute const *)
  1059. (* AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER *)
  1060. {!
  1061. @constant kMDQueryUpdateAddedItems
  1062. The name of the key in a query notification's info dictionary
  1063. which identifies the list of added results. A result is
  1064. added if the file contents or some metadata attribute
  1065. of it is changed, and it now matches the query. Result
  1066. objects are created for the newly added results, to be
  1067. put in the list.
  1068. }
  1069. var kMDQueryUpdateAddedItems: CFStringRef; external name '_kMDQueryUpdateAddedItems'; (* attribute const *)
  1070. (* AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER *)
  1071. {!
  1072. @constant kMDQueryUpdateChangedItems
  1073. The name of the key in a query notification's info dictionary
  1074. which identifies the list of changed results. A result
  1075. is changed if the file contents or some metadata
  1076. attribute of it is changed, but it still matches the
  1077. query. The list only contains result objects which have
  1078. previously been created, and does not indicate results
  1079. which have been changed for which result objects have
  1080. not been created.
  1081. [[This is for performance reasons, to avoid creating
  1082. result objects just to represent a change of a result
  1083. which has not been looked at, but this semantic may
  1084. change.]]
  1085. }
  1086. var kMDQueryUpdateChangedItems: CFStringRef; external name '_kMDQueryUpdateChangedItems'; (* attribute const *)
  1087. (* AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER *)
  1088. {!
  1089. @constant kMDQueryUpdateRemovedItems
  1090. The name of the key in a query notification's info dictionary
  1091. which identifies the list of removed results. A result
  1092. can be removed if it no longer matches the query. The
  1093. list only contains result objects which have previously
  1094. been created, and does not indicate results which have
  1095. been removed for which result objects have not been
  1096. created.
  1097. [[This is for performance reasons, to avoid creating
  1098. temporary result objects just to represent the deletion
  1099. of the result, but this semantic may change.]]
  1100. }
  1101. var kMDQueryUpdateRemovedItems: CFStringRef; external name '_kMDQueryUpdateRemovedItems'; (* attribute const *)
  1102. (* AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER *)
  1103. {!
  1104. @constant kMDQueryResultContentRelevance
  1105. The name of a query-specific attribute for use in sorting.
  1106. The relevance of an item is a CFNumberRef with a
  1107. floating point value. This is the relevance for
  1108. content searches.
  1109. The maximum and minimum values for a particular
  1110. search cannot be determined until all of the results
  1111. have been returned. If there are multiple
  1112. kMDItemTextContent predicates in the query, no
  1113. relevance is returned.
  1114. This is an attribute of a result item that is
  1115. specific to the item in the context of the query.
  1116. Also, the relevance does not compare the result
  1117. relative to the other results of a query, but is
  1118. computed just on the result item itself. Finally,
  1119. this is only the relevance value for content,
  1120. not a relevance for the item as a whole. The
  1121. relevance attribute may not even be computed for
  1122. an item if the item is found to match the query
  1123. through evaluation of other attributes of the
  1124. item than its contents. If the value is not
  1125. computed, it is treated as an attribute on the
  1126. item which does not exist (for sorting purposes,
  1127. for example).
  1128. }
  1129. var kMDQueryResultContentRelevance: CFStringRef; external name '_kMDQueryResultContentRelevance'; (* attribute const *)
  1130. (* AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER *)
  1131. {!
  1132. @function MDQuerySetSearchScope
  1133. @discussion Use MDQuerySetSearchScope to limit the results
  1134. returned by the query engine to those MDItemRefs that
  1135. appear within the specified directories. This may be
  1136. used to limit searching to particular volumes. Tilde
  1137. paths, or environment variables are not expanded.
  1138. Calling this multiple times will replace the previous
  1139. options. This must be called before the query is executed.
  1140. @param query The query object to modify.
  1141. @param scopeDirectories a CFArray of CFStringRef or CFURLRef objects which
  1142. specify where to search. For conveinience, the kMDQueryScopeHome,
  1143. kMDQueryScopeComputer and kMDQueryScopeNetwork constants may also
  1144. be present in this array.
  1145. @param scopeOptions additional options for modifying the search.
  1146. Currently, pass 0 (zero).
  1147. }
  1148. procedure MDQuerySetSearchScope( query: MDQueryRef; scopeDirectories: CFArrayRef; scopeOptions: OptionBits ); external name '_MDQuerySetSearchScope';
  1149. (* AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER *)
  1150. {!
  1151. @constant kMDQueryScopeHome
  1152. A constant, which can be passed in the scopeDirectories array, to specify
  1153. that the search should be restricted to the volume and directory that contains
  1154. the current user's home directory
  1155. }
  1156. var kMDQueryScopeHome: CFStringRef; external name '_kMDQueryScopeHome'; (* attribute const *)
  1157. (* AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER *)
  1158. {!
  1159. @constant kMDQueryScopeComputer
  1160. A constant, which can be passed in the scopeDirectories array, to specify
  1161. that the search should be restricted to all locally mounted volumes, plus the user's
  1162. home directory (which may be on a remote volume).
  1163. }
  1164. var kMDQueryScopeComputer: CFStringRef; external name '_kMDQueryScopeComputer'; (* attribute const *)
  1165. (* AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER *)
  1166. {!
  1167. @constant kMDQueryScopeNetwork
  1168. A constant, which can be passed in the scopeDirectories array, to specify
  1169. that the search should include all user mounted remote volumes.
  1170. }
  1171. var kMDQueryScopeNetwork: CFStringRef; external name '_kMDQueryScopeNetwork'; (* attribute const *)
  1172. (* AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER *)
  1173. {!
  1174. @constant kMDQueryScopeAllIndexed
  1175. A constant, which can be passed in the scopeDirectories array, to specify
  1176. that the search should be restricted to indexed, locally mounted volumes and
  1177. indexed user mounted remote volumes, plus the user's home directory.
  1178. }
  1179. var kMDQueryScopeAllIndexed: CFStringRef; external name '_kMDQueryScopeAllIndexed'; (* attribute const *)
  1180. (* AVAILABLE_MAC_OS_X_VERSION_10_6_AND_LATER *)
  1181. {!
  1182. @constant kMDQueryScopeComputerIndexed
  1183. A constant, which can be passed in the scopeDirectories array, to specify
  1184. that the search should be restricted to indexed, locally mounted volumes, plus the user's
  1185. home directory (which may be on a remote volume).
  1186. }
  1187. var kMDQueryScopeComputerIndexed: CFStringRef; external name '_kMDQueryScopeComputerIndexed'; (* attribute const *)
  1188. (* AVAILABLE_MAC_OS_X_VERSION_10_6_AND_LATER *)
  1189. {!
  1190. @constant kMDQueryScopeNetworkIndexed
  1191. A constant, which can be passed in the scopeDirectories array, to specify
  1192. that the search should include indexed user mounted remote volumes.
  1193. }
  1194. var kMDQueryScopeNetworkIndexed: CFStringRef; external name '_kMDQueryScopeNetworkIndexed'; (* attribute const *)
  1195. (* AVAILABLE_MAC_OS_X_VERSION_10_6_AND_LATER *)
  1196. {!
  1197. @function MDQuerySetMaxCount
  1198. @discussion Use MDQuerySetMaxCount to limit the number of results
  1199. returned by the query engine. This must be called before the query is executed.
  1200. @param query The query object to modify.
  1201. @param size The maximum number of results desired.
  1202. }
  1203. procedure MDQuerySetMaxCount( query: MDQueryRef; size: CFIndex ); external name '_MDQuerySetMaxCount';
  1204. (* AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER *)
  1205. {$endc} {TARGET_OS_MAC}
  1206. {$ifc not defined MACOSALLINCLUDE or not MACOSALLINCLUDE}
  1207. end.
  1208. {$endc} {not MACOSALLINCLUDE}