libetpan - fdik
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

690 lines
18 KiB

11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
  1. /*
  2. * libEtPan! -- a mail stuff library
  3. *
  4. * Copyright (C) 2001, 2005 - DINH Viet Hoa
  5. * All rights reserved.
  6. *
  7. * Redistribution and use in source and binary forms, with or without
  8. * modification, are permitted provided that the following conditions
  9. * are met:
  10. * 1. Redistributions of source code must retain the above copyright
  11. * notice, this list of conditions and the following disclaimer.
  12. * 2. Redistributions in binary form must reproduce the above copyright
  13. * notice, this list of conditions and the following disclaimer in the
  14. * documentation and/or other materials provided with the distribution.
  15. * 3. Neither the name of the libEtPan! project nor the names of its
  16. * contributors may be used to endorse or promote products derived
  17. * from this software without specific prior written permission.
  18. *
  19. * THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND
  20. * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  21. * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  22. * ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE
  23. * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  24. * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  25. * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  26. * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  27. * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  28. * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  29. * SUCH DAMAGE.
  30. */
  31. /*
  32. * $Id: mailimap.h,v 1.23 2011/03/29 23:59:05 hoa Exp $
  33. */
  34. #ifndef MAILIMAP_H
  35. #define MAILIMAP_H
  36. #ifdef __cplusplus
  37. extern "C" {
  38. #endif
  39. #include <libetpan/mailimap_types.h>
  40. #include <libetpan/mailimap_types_helper.h>
  41. #include <libetpan/mailimap_helper.h>
  42. #include <libetpan/mailimap_socket.h>
  43. #include <libetpan/mailimap_ssl.h>
  44. #include <libetpan/acl.h>
  45. #include <libetpan/annotatemore.h>
  46. #include <libetpan/uidplus.h>
  47. #include <libetpan/idle.h>
  48. #include <libetpan/quota.h>
  49. #include <libetpan/namespace.h>
  50. #include <libetpan/mailimap_id.h>
  51. #include <libetpan/enable.h>
  52. #include <libetpan/xlist.h>
  53. #include <libetpan/xgmlabels.h>
  54. #include <libetpan/xgmmsgid.h>
  55. #include <libetpan/xgmthrid.h>
  56. #include <libetpan/condstore.h>
  57. #include <libetpan/qresync.h>
  58. #include <libetpan/mailimap_sort.h>
  59. #include <libetpan/mailimap_compress.h>
  60. /*
  61. mailimap_connect()
  62. This function will connect the IMAP session with the given stream.
  63. @param session the IMAP session
  64. @param s stream to use
  65. @return the return code is one of MAILIMAP_ERROR_XXX or
  66. MAILIMAP_NO_ERROR codes
  67. note that on success, MAILIMAP_NO_ERROR_AUTHENTICATED or
  68. MAILIMAP_NO_ERROR_NON_AUTHENTICATED is returned
  69. MAILIMAP_NO_ERROR_NON_AUTHENTICATED is returned when you need to
  70. use mailimap_login() to authenticate, else
  71. MAILIMAP_NO_ERROR_AUTHENTICATED is returned.
  72. */
  73. LIBETPAN_EXPORT
  74. int mailimap_connect(mailimap * session, mailstream * s);
  75. /*
  76. mailimap_append()
  77. This function will append a given message to the given mailbox
  78. by sending an APPEND command.
  79. @param session the IMAP session
  80. @param mailbox name of the mailbox
  81. @param flag_list flags of the message
  82. @param date_time timestamp of the message
  83. @param literal content of the message
  84. @param literal_size size of the message
  85. @return the return code is one of MAILIMAP_ERROR_XXX or
  86. MAILIMAP_NO_ERROR codes
  87. */
  88. LIBETPAN_EXPORT
  89. int mailimap_append(mailimap * session, const char * mailbox,
  90. struct mailimap_flag_list * flag_list,
  91. struct mailimap_date_time * date_time,
  92. const char * literal, size_t literal_size);
  93. /*
  94. mailimap_noop()
  95. This function will poll for an event on the server by
  96. sending a NOOP command to the IMAP server
  97. @param session IMAP session
  98. @return the return code is one of MAILIMAP_ERROR_XXX or
  99. MAILIMAP_NO_ERROR_XXX codes
  100. */
  101. LIBETPAN_EXPORT
  102. int mailimap_noop(mailimap * session);
  103. /*
  104. mailimap_logout()
  105. This function will logout from an IMAP server by sending
  106. a LOGOUT command.
  107. @param session IMAP session
  108. @return the return code is one of MAILIMAP_ERROR_XXX or
  109. MAILIMAP_NO_ERROR codes
  110. */
  111. LIBETPAN_EXPORT
  112. int mailimap_logout(mailimap * session);
  113. /*
  114. mailimap_capability()
  115. This function will query an IMAP server for his capabilities
  116. by sending a CAPABILITY command.
  117. @param session IMAP session
  118. @param result The result of this command is a list of
  119. capabilities and it is stored into (* result).
  120. @return the return code is one of MAILIMAP_ERROR_XXX or
  121. MAILIMAP_NO_ERROR codes
  122. */
  123. LIBETPAN_EXPORT
  124. int mailimap_capability(mailimap * session,
  125. struct mailimap_capability_data ** result);
  126. /*
  127. mailimap_check()
  128. This function will request for a checkpoint of the mailbox by
  129. sending a CHECK command.
  130. @param session IMAP session
  131. @return the return code is one of MAILIMAP_ERROR_XXX or
  132. MAILIMAP_NO_ERROR codes
  133. */
  134. LIBETPAN_EXPORT
  135. int mailimap_check(mailimap * session);
  136. /*
  137. mailimap_close()
  138. This function will close the selected mailbox by sending
  139. a CLOSE command.
  140. @param session IMAP session
  141. @return the return code is one of MAILIMAP_ERROR_XXX or
  142. MAILIMAP_NO_ERROR codes
  143. */
  144. LIBETPAN_EXPORT
  145. int mailimap_close(mailimap * session);
  146. /*
  147. mailimap_expunge()
  148. This function will permanently remove from the selected mailbox
  149. message that have the \Deleted flag set.
  150. @param session IMAP session
  151. @return the return code is one of MAILIMAP_ERROR_XXX or
  152. MAILIMAP_NO_ERROR codes
  153. */
  154. LIBETPAN_EXPORT
  155. int mailimap_expunge(mailimap * session);
  156. /*
  157. mailimap_copy()
  158. This function will copy the given messages from the selected mailbox
  159. to the given mailbox.
  160. @param session IMAP session
  161. @param set This is a set of message numbers.
  162. @param mb This is the destination mailbox.
  163. @return the return code is one of MAILIMAP_ERROR_XXX or
  164. MAILIMAP_NO_ERROR codes
  165. */
  166. LIBETPAN_EXPORT
  167. int mailimap_copy(mailimap * session, struct mailimap_set * set,
  168. const char * mb);
  169. /*
  170. mailimap_uid_copy()
  171. This function will copy the given messages from the selected mailbox
  172. to the given mailbox.
  173. @param session IMAP session
  174. @param set This is a set of message unique identifiers.
  175. @param mb This is the destination mailbox.
  176. @return the return code is one of MAILIMAP_ERROR_XXX or
  177. MAILIMAP_NO_ERROR codes
  178. */
  179. LIBETPAN_EXPORT
  180. int mailimap_uid_copy(mailimap * session,
  181. struct mailimap_set * set, const char * mb);
  182. /*
  183. mailimap_create()
  184. This function will create a mailbox.
  185. @param session IMAP session
  186. @param mb This is the name of the mailbox to create.
  187. @return the return code is one of MAILIMAP_ERROR_XXX or
  188. MAILIMAP_NO_ERROR codes
  189. */
  190. LIBETPAN_EXPORT
  191. int mailimap_create(mailimap * session, const char * mb);
  192. /*
  193. mailimap_delete()
  194. This function will delete a mailox.
  195. @param session IMAP session
  196. @param mb This is the name of the mailbox to delete.
  197. @return the return code is one of MAILIMAP_ERROR_XXX or
  198. MAILIMAP_NO_ERROR codes
  199. */
  200. LIBETPAN_EXPORT
  201. int mailimap_delete(mailimap * session, const char * mb);
  202. /*
  203. mailimap_examine()
  204. This function will select the mailbox for read-only operations.
  205. @param session IMAP session
  206. @param mb This is the name of the mailbox to select.
  207. @return the return code is one of MAILIMAP_ERROR_XXX or
  208. MAILIMAP_NO_ERROR codes
  209. */
  210. LIBETPAN_EXPORT
  211. int mailimap_examine(mailimap * session, const char * mb);
  212. /*
  213. mailimap_fetch()
  214. This function will retrieve data associated with the given message
  215. numbers.
  216. @param session IMAP session
  217. @param set set of message numbers
  218. @param fetch_type type of information to be retrieved
  219. @param result The result of this command is a clist
  220. and it is stored into (* result). Each element of the clist is a
  221. (struct mailimap_msg_att *).
  222. @return the return code is one of MAILIMAP_ERROR_XXX or
  223. MAILIMAP_NO_ERROR codes
  224. */
  225. LIBETPAN_EXPORT
  226. int
  227. mailimap_fetch(mailimap * session, struct mailimap_set * set,
  228. struct mailimap_fetch_type * fetch_type, clist ** result);
  229. /*
  230. mailimap_fetch()
  231. This function will retrieve data associated with the given message
  232. numbers.
  233. @param session IMAP session
  234. @param set set of message unique identifiers
  235. @param fetch_type type of information to be retrieved
  236. @param result The result of this command is a clist
  237. and it is stored into (* result). Each element of the clist is a
  238. (struct mailimap_msg_att *).
  239. @return the return code is one of MAILIMAP_ERROR_XXX or
  240. MAILIMAP_NO_ERROR codes
  241. */
  242. LIBETPAN_EXPORT
  243. int
  244. mailimap_uid_fetch(mailimap * session,
  245. struct mailimap_set * set,
  246. struct mailimap_fetch_type * fetch_type, clist ** result);
  247. /*
  248. mailimap_fetch_list_free()
  249. This function will free the result of a fetch command.
  250. @param fetch_list This is the clist containing
  251. (struct mailimap_msg_att *) elements to free.
  252. */
  253. LIBETPAN_EXPORT
  254. void mailimap_fetch_list_free(clist * fetch_list);
  255. /*
  256. mailimap_list()
  257. This function will return the list of the mailbox
  258. available on the server.
  259. @param session IMAP session
  260. @param mb This is the reference name that informs
  261. of the level of hierarchy
  262. @param list_mb mailbox name with possible wildcard
  263. @param result This will store a clist of (struct mailimap_mailbox_list *)
  264. in (* result)
  265. @return the return code is one of MAILIMAP_ERROR_XXX or
  266. MAILIMAP_NO_ERROR codes
  267. */
  268. LIBETPAN_EXPORT
  269. int mailimap_list(mailimap * session, const char * mb,
  270. const char * list_mb, clist ** result);
  271. /*
  272. mailimap_login()
  273. This function will authenticate the client.
  274. @param session IMAP session
  275. @param userid login of the user
  276. @param password password of the user
  277. @return the return code is one of MAILIMAP_ERROR_XXX or
  278. MAILIMAP_NO_ERROR codes
  279. */
  280. LIBETPAN_EXPORT
  281. int mailimap_login(mailimap * session,
  282. const char * userid, const char * password);
  283. /*
  284. mailimap_authenticate()
  285. This function will authenticate the client.
  286. TODO : documentation
  287. */
  288. LIBETPAN_EXPORT
  289. int mailimap_authenticate(mailimap * session, const char * auth_type,
  290. const char * server_fqdn,
  291. const char * local_ip_port,
  292. const char * remote_ip_port,
  293. const char * login, const char * auth_name,
  294. const char * password, const char * realm);
  295. /*
  296. mailimap_lsub()
  297. This function will return the list of the mailbox
  298. that the client has subscribed to.
  299. @param session IMAP session
  300. @param mb This is the reference name that informs
  301. of the level of hierarchy
  302. @param list_mb mailbox name with possible wildcard
  303. @param result This will store a list of (struct mailimap_mailbox_list *)
  304. in (* result)
  305. @return the return code is one of MAILIMAP_ERROR_XXX or
  306. MAILIMAP_NO_ERROR codes
  307. */
  308. LIBETPAN_EXPORT
  309. int mailimap_lsub(mailimap * session, const char * mb,
  310. const char * list_mb, clist ** result);
  311. /*
  312. mailimap_list_result_free()
  313. This function will free the clist of (struct mailimap_mailbox_list *)
  314. @param list This is the clist to free.
  315. */
  316. LIBETPAN_EXPORT
  317. void mailimap_list_result_free(clist * list);
  318. /*
  319. mailimap_rename()
  320. This function will change the name of a mailbox.
  321. @param session IMAP session
  322. @param mb current name
  323. @param new_name new name
  324. @return the return code is one of MAILIMAP_ERROR_XXX or
  325. MAILIMAP_NO_ERROR codes
  326. */
  327. LIBETPAN_EXPORT
  328. int mailimap_rename(mailimap * session,
  329. const char * mb, const char * new_name);
  330. /*
  331. mailimap_search()
  332. All mails that match the given criteria will be returned
  333. their numbers in the result list.
  334. @param session IMAP session
  335. @param charset This indicates the charset of the strings that appears
  336. in the searching criteria
  337. @param key This is the searching criteria
  338. @param result The result is a clist of (uint32_t *) and will be
  339. stored in (* result).
  340. @return the return code is one of MAILIMAP_ERROR_XXX or
  341. MAILIMAP_NO_ERROR codes
  342. */
  343. LIBETPAN_EXPORT
  344. int
  345. mailimap_search(mailimap * session, const char * charset,
  346. struct mailimap_search_key * key, clist ** result);
  347. /*
  348. mailimap_uid_search()
  349. All mails that match the given criteria will be returned
  350. their unique identifiers in the result list.
  351. @param session IMAP session
  352. @param charset This indicates the charset of the strings that appears
  353. in the searching criteria
  354. @param key This is the searching criteria
  355. @param result The result is a clist of (uint32_t *) and will be
  356. stored in (* result).
  357. @return the return code is one of MAILIMAP_ERROR_XXX or
  358. MAILIMAP_NO_ERROR codes
  359. */
  360. LIBETPAN_EXPORT
  361. int
  362. mailimap_uid_search(mailimap * session, const char * charset,
  363. struct mailimap_search_key * key, clist ** result);
  364. /*
  365. mailimap_search_result_free()
  366. This function will free the result of the a search.
  367. @param search_result This is a clist of (uint32_t *) returned
  368. by mailimap_uid_search() or mailimap_search()
  369. */
  370. LIBETPAN_EXPORT
  371. void mailimap_search_result_free(clist * search_result);
  372. /*
  373. mailimap_select()
  374. This function will select a given mailbox so that messages in the
  375. mailbox can be accessed.
  376. @param session IMAP session
  377. @param mb This is the name of the mailbox to select.
  378. @return the return code is one of MAILIMAP_ERROR_XXX or
  379. MAILIMAP_NO_ERROR codes
  380. */
  381. LIBETPAN_EXPORT
  382. int
  383. mailimap_select(mailimap * session, const char * mb);
  384. /*
  385. mailimap_status()
  386. This function will return informations about a given mailbox.
  387. @param session IMAP session
  388. @param mb This is the name of the mailbox
  389. @param status_att_list This is the list of mailbox information to return
  390. @param result List of returned values
  391. @return the return code is one of MAILIMAP_ERROR_XXX or
  392. MAILIMAP_NO_ERROR codes
  393. */
  394. LIBETPAN_EXPORT
  395. int
  396. mailimap_status(mailimap * session, const char * mb,
  397. struct mailimap_status_att_list * status_att_list,
  398. struct mailimap_mailbox_data_status ** result);
  399. /*
  400. mailimap_uid_store()
  401. This function will alter the data associated with some messages
  402. (flags of the messages).
  403. @param session IMAP session
  404. @param set This is a list of message numbers.
  405. @param store_att_flags This is the data to associate with the
  406. given messages
  407. @return the return code is one of MAILIMAP_ERROR_XXX or
  408. MAILIMAP_NO_ERROR codes
  409. */
  410. LIBETPAN_EXPORT
  411. int
  412. mailimap_store(mailimap * session,
  413. struct mailimap_set * set,
  414. struct mailimap_store_att_flags * store_att_flags);
  415. /*
  416. mailimap_uid_store()
  417. This function will alter the data associated with some messages
  418. (flags of the messages).
  419. @param session IMAP session
  420. @param set This is a list of message unique identifiers.
  421. @param store_att_flags This is the data to associate with the
  422. given messages
  423. @return the return code is one of MAILIMAP_ERROR_XXX or
  424. MAILIMAP_NO_ERROR codes
  425. */
  426. LIBETPAN_EXPORT
  427. int
  428. mailimap_uid_store(mailimap * session,
  429. struct mailimap_set * set,
  430. struct mailimap_store_att_flags * store_att_flags);
  431. /*
  432. mailimap_subscribe()
  433. This function adds the specified mailbox name to the
  434. server's set of "active" or "subscribed" mailboxes.
  435. @param session IMAP session
  436. @param mb This is the name of the mailbox
  437. @return the return code is one of MAILIMAP_ERROR_XXX or
  438. MAILIMAP_NO_ERROR codes
  439. */
  440. LIBETPAN_EXPORT
  441. int mailimap_subscribe(mailimap * session, const char * mb);
  442. /*
  443. mailimap_unsubscribe()
  444. This function removes the specified mailbox name to the
  445. server's set of "active" or "subscribed" mailboxes.
  446. @param session IMAP session
  447. @param mb This is the name of the mailbox
  448. @return the return code is one of MAILIMAP_ERROR_XXX or
  449. MAILIMAP_NO_ERROR codes
  450. */
  451. LIBETPAN_EXPORT
  452. int mailimap_unsubscribe(mailimap * session, const char * mb);
  453. /*
  454. mailimap_starttls()
  455. This function starts change the mode of the connection to
  456. switch to SSL connection.
  457. It won't change the stream connection to SSL rightway.
  458. See mailimap_socket_starttls() will switch the mailstream too.
  459. @param session IMAP session
  460. @return the return code is one of MAILIMAP_ERROR_XXX or
  461. MAILIMAP_NO_ERROR_XXX codes
  462. */
  463. LIBETPAN_EXPORT
  464. int mailimap_starttls(mailimap * session);
  465. /*
  466. mailimap_new()
  467. This function returns a new IMAP session.
  468. @param progr_rate When downloading messages, a function will be called
  469. each time the amount of bytes downloaded reaches a multiple of this
  470. value, this can be 0.
  471. @param progr_fun This is the function to call to notify the progress,
  472. this can be NULL.
  473. @return an IMAP session is returned.
  474. */
  475. LIBETPAN_EXPORT
  476. mailimap * mailimap_new(size_t imap_progr_rate,
  477. progress_function * imap_progr_fun);
  478. /*
  479. mailimap_free()
  480. This function will free the data structures associated with
  481. the IMAP session.
  482. @param session IMAP session
  483. */
  484. LIBETPAN_EXPORT
  485. void mailimap_free(mailimap * session);
  486. int mailimap_send_current_tag(mailimap * session);
  487. char * mailimap_read_line(mailimap * session);
  488. int mailimap_parse_response(mailimap * session,
  489. struct mailimap_response ** result);
  490. LIBETPAN_EXPORT
  491. void mailimap_set_progress_callback(mailimap * session,
  492. mailprogress_function * body_progr_fun,
  493. mailprogress_function * items_progr_fun,
  494. void * context);
  495. LIBETPAN_EXPORT
  496. void mailimap_set_msg_att_handler(mailimap * session,
  497. mailimap_msg_att_handler * handler,
  498. void * context);
  499. LIBETPAN_EXPORT
  500. void mailimap_set_timeout(mailimap * session, time_t timeout);;
  501. LIBETPAN_EXPORT
  502. time_t mailimap_get_timeout(mailimap * session);
  503. #ifdef __cplusplus
  504. }
  505. #endif
  506. #endif