Funktionierender Prototyp des Serious Games zur Vermittlung von Wissen zu Software-Engineering-Arbeitsmodellen.
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.

interfaces.py 31KB

1 year ago
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978979980981982983984985986987988989990991992993994995996997998999100010011002100310041005100610071008100910101011101210131014101510161017101810191020102110221023102410251026102710281029103010311032103310341035103610371038103910401041104210431044104510461047104810491050
  1. # Copyright (c) Twisted Matrix Laboratories.
  2. # See LICENSE for details.
  3. """
  4. Interfaces for L{twisted.mail}.
  5. @since: 16.5
  6. """
  7. from zope.interface import Interface
  8. class IChallengeResponse(Interface):
  9. """
  10. An C{IMAPrev4} authorization challenge mechanism.
  11. """
  12. def getChallenge():
  13. """
  14. Return a client challenge.
  15. @return: A challenge.
  16. @rtype: L{bytes}
  17. """
  18. def setResponse(response):
  19. """
  20. Extract a username and possibly a password from a response and
  21. assign them to C{username} and C{password} instance variables.
  22. @param response: A decoded response.
  23. @type response: L{bytes}
  24. @see: L{credentials.IUsernamePassword} or
  25. L{credentials.IUsernameHashedPassword}
  26. """
  27. def moreChallenges():
  28. """
  29. Are there more challenges than just the first? If so, callers
  30. should challenge clients with the result of L{getChallenge},
  31. and check their response with L{setResponse} in a loop until
  32. this returns L{False}
  33. @return: Are there more challenges?
  34. @rtype: L{bool}
  35. """
  36. class IClientAuthentication(Interface):
  37. def getName():
  38. """
  39. Return an identifier associated with this authentication scheme.
  40. @rtype: L{bytes}
  41. """
  42. def challengeResponse(secret, challenge):
  43. """
  44. Generate a challenge response string.
  45. """
  46. class IServerFactoryPOP3(Interface):
  47. """
  48. An interface for querying capabilities of a POP3 server.
  49. Any cap_* method may raise L{NotImplementedError} if the particular
  50. capability is not supported. If L{cap_EXPIRE()} does not raise
  51. L{NotImplementedError}, L{perUserExpiration()} must be implemented,
  52. otherwise they are optional. If L{cap_LOGIN_DELAY()} is implemented,
  53. L{perUserLoginDelay()} must be implemented, otherwise they are optional.
  54. @type challengers: L{dict} of L{bytes} -> L{IUsernameHashedPassword
  55. <cred.credentials.IUsernameHashedPassword>}
  56. @ivar challengers: A mapping of challenger names to
  57. L{IUsernameHashedPassword <cred.credentials.IUsernameHashedPassword>}
  58. provider.
  59. """
  60. def cap_IMPLEMENTATION():
  61. """
  62. Return a string describing the POP3 server implementation.
  63. @rtype: L{bytes}
  64. @return: Server implementation information.
  65. """
  66. def cap_EXPIRE():
  67. """
  68. Return the minimum number of days messages are retained.
  69. @rtype: L{int} or L{None}
  70. @return: The minimum number of days messages are retained or none, if
  71. the server never deletes messages.
  72. """
  73. def perUserExpiration():
  74. """
  75. Indicate whether the message expiration policy differs per user.
  76. @rtype: L{bool}
  77. @return: C{True} when the message expiration policy differs per user,
  78. C{False} otherwise.
  79. """
  80. def cap_LOGIN_DELAY():
  81. """
  82. Return the minimum number of seconds between client logins.
  83. @rtype: L{int}
  84. @return: The minimum number of seconds between client logins.
  85. """
  86. def perUserLoginDelay():
  87. """
  88. Indicate whether the login delay period differs per user.
  89. @rtype: L{bool}
  90. @return: C{True} when the login delay differs per user, C{False}
  91. otherwise.
  92. """
  93. class IMailboxPOP3(Interface):
  94. """
  95. An interface for mailbox access.
  96. Message indices are 0-based.
  97. @type loginDelay: L{int}
  98. @ivar loginDelay: The number of seconds between allowed logins for the
  99. user associated with this mailbox.
  100. @type messageExpiration: L{int}
  101. @ivar messageExpiration: The number of days messages in this mailbox will
  102. remain on the server before being deleted.
  103. """
  104. def listMessages(index=None):
  105. """
  106. Retrieve the size of a message, or, if none is specified, the size of
  107. each message in the mailbox.
  108. @type index: L{int} or L{None}
  109. @param index: The 0-based index of the message.
  110. @rtype: L{int}, sequence of L{int}, or L{Deferred <defer.Deferred>}
  111. @return: The number of octets in the specified message, or, if an
  112. index is not specified, a sequence of the number of octets for
  113. all messages in the mailbox or a deferred which fires with
  114. one of those. Any value which corresponds to a deleted message
  115. is set to 0.
  116. @raise ValueError or IndexError: When the index does not correspond to
  117. a message in the mailbox. The use of ValueError is preferred.
  118. """
  119. def getMessage(index):
  120. """
  121. Retrieve a file containing the contents of a message.
  122. @type index: L{int}
  123. @param index: The 0-based index of a message.
  124. @rtype: file-like object
  125. @return: A file containing the message.
  126. @raise ValueError or IndexError: When the index does not correspond to
  127. a message in the mailbox. The use of ValueError is preferred.
  128. """
  129. def getUidl(index):
  130. """
  131. Get a unique identifier for a message.
  132. @type index: L{int}
  133. @param index: The 0-based index of a message.
  134. @rtype: L{bytes}
  135. @return: A string of printable characters uniquely identifying the
  136. message for all time.
  137. @raise ValueError or IndexError: When the index does not correspond to
  138. a message in the mailbox. The use of ValueError is preferred.
  139. """
  140. def deleteMessage(index):
  141. """
  142. Mark a message for deletion.
  143. This must not change the number of messages in this mailbox. Further
  144. requests for the size of the deleted message should return 0. Further
  145. requests for the message itself may raise an exception.
  146. @type index: L{int}
  147. @param index: The 0-based index of a message.
  148. @raise ValueError or IndexError: When the index does not correspond to
  149. a message in the mailbox. The use of ValueError is preferred.
  150. """
  151. def undeleteMessages():
  152. """
  153. Undelete all messages marked for deletion.
  154. Any message which can be undeleted should be returned to its original
  155. position in the message sequence and retain its original UID.
  156. """
  157. def sync():
  158. """
  159. Discard the contents of any message marked for deletion.
  160. """
  161. class IDomain(Interface):
  162. """
  163. An interface for email domains.
  164. """
  165. def exists(user):
  166. """
  167. Check whether a user exists in this domain.
  168. @type user: L{User}
  169. @param user: A user.
  170. @rtype: no-argument callable which returns L{IMessageSMTP} provider
  171. @return: A function which takes no arguments and returns a message
  172. receiver for the user.
  173. @raise SMTPBadRcpt: When the given user does not exist in this domain.
  174. """
  175. def addUser(user, password):
  176. """
  177. Add a user to this domain.
  178. @type user: L{bytes}
  179. @param user: A username.
  180. @type password: L{bytes}
  181. @param password: A password.
  182. """
  183. def getCredentialsCheckers():
  184. """
  185. Return credentials checkers for this domain.
  186. @rtype: L{list} of L{ICredentialsChecker
  187. <twisted.cred.checkers.ICredentialsChecker>} provider
  188. @return: Credentials checkers for this domain.
  189. """
  190. class IAlias(Interface):
  191. """
  192. An interface for aliases.
  193. """
  194. def createMessageReceiver():
  195. """
  196. Create a message receiver.
  197. @rtype: L{IMessageSMTP} provider
  198. @return: A message receiver.
  199. """
  200. class IAliasableDomain(IDomain):
  201. """
  202. An interface for email domains which can be aliased to other domains.
  203. """
  204. def setAliasGroup(aliases):
  205. """
  206. Set the group of defined aliases for this domain.
  207. @type aliases: L{dict} of L{bytes} -> L{IAlias} provider
  208. @param aliases: A mapping of domain name to alias.
  209. """
  210. def exists(user, memo=None):
  211. """
  212. Check whether a user exists in this domain or an alias of it.
  213. @type user: L{User}
  214. @param user: A user.
  215. @type memo: L{None} or L{dict} of
  216. L{AliasBase <twisted.mail.alias.AliasBase>}
  217. @param memo: A record of the addresses already considered while
  218. resolving aliases. The default value should be used by all external
  219. code.
  220. @rtype: no-argument callable which returns L{IMessageSMTP} provider
  221. @return: A function which takes no arguments and returns a message
  222. receiver for the user.
  223. @raise SMTPBadRcpt: When the given user does not exist in this domain
  224. or an alias of it.
  225. """
  226. class IMessageDelivery(Interface):
  227. def receivedHeader(helo, origin, recipients):
  228. """
  229. Generate the Received header for a message.
  230. @type helo: 2-L{tuple} of L{bytes} and L{bytes}.
  231. @param helo: The argument to the HELO command and the client's IP
  232. address.
  233. @type origin: L{Address}
  234. @param origin: The address the message is from
  235. @type recipients: L{list} of L{User}
  236. @param recipients: A list of the addresses for which this message
  237. is bound.
  238. @rtype: L{bytes}
  239. @return: The full C{"Received"} header string.
  240. """
  241. def validateTo(user):
  242. """
  243. Validate the address for which the message is destined.
  244. @type user: L{User}
  245. @param user: The address to validate.
  246. @rtype: no-argument callable
  247. @return: A L{Deferred} which becomes, or a callable which takes no
  248. arguments and returns an object implementing L{IMessageSMTP}. This
  249. will be called and the returned object used to deliver the message
  250. when it arrives.
  251. @raise SMTPBadRcpt: Raised if messages to the address are not to be
  252. accepted.
  253. """
  254. def validateFrom(helo, origin):
  255. """
  256. Validate the address from which the message originates.
  257. @type helo: 2-L{tuple} of L{bytes} and L{bytes}.
  258. @param helo: The argument to the HELO command and the client's IP
  259. address.
  260. @type origin: L{Address}
  261. @param origin: The address the message is from
  262. @rtype: L{Deferred} or L{Address}
  263. @return: C{origin} or a L{Deferred} whose callback will be
  264. passed C{origin}.
  265. @raise SMTPBadSender: Raised of messages from this address are
  266. not to be accepted.
  267. """
  268. class IMessageDeliveryFactory(Interface):
  269. """
  270. An alternate interface to implement for handling message delivery.
  271. It is useful to implement this interface instead of L{IMessageDelivery}
  272. directly because it allows the implementor to distinguish between different
  273. messages delivery over the same connection. This can be used to optimize
  274. delivery of a single message to multiple recipients, something which cannot
  275. be done by L{IMessageDelivery} implementors due to their lack of
  276. information.
  277. """
  278. def getMessageDelivery():
  279. """
  280. Return an L{IMessageDelivery} object.
  281. This will be called once per message.
  282. """
  283. class IMessageSMTP(Interface):
  284. """
  285. Interface definition for messages that can be sent via SMTP.
  286. """
  287. def lineReceived(line):
  288. """
  289. Handle another line.
  290. """
  291. def eomReceived():
  292. """
  293. Handle end of message.
  294. return a deferred. The deferred should be called with either:
  295. callback(string) or errback(error)
  296. @rtype: L{Deferred}
  297. """
  298. def connectionLost():
  299. """
  300. Handle message truncated.
  301. semantics should be to discard the message
  302. """
  303. class IMessageIMAPPart(Interface):
  304. def getHeaders(negate, *names):
  305. """
  306. Retrieve a group of message headers.
  307. @type names: L{tuple} of L{str}
  308. @param names: The names of the headers to retrieve or omit.
  309. @type negate: L{bool}
  310. @param negate: If True, indicates that the headers listed in C{names}
  311. should be omitted from the return value, rather than included.
  312. @rtype: L{dict}
  313. @return: A mapping of header field names to header field values
  314. """
  315. def getBodyFile():
  316. """
  317. Retrieve a file object containing only the body of this message.
  318. """
  319. def getSize():
  320. """
  321. Retrieve the total size, in octets, of this message.
  322. @rtype: L{int}
  323. """
  324. def isMultipart():
  325. """
  326. Indicate whether this message has subparts.
  327. @rtype: L{bool}
  328. """
  329. def getSubPart(part):
  330. """
  331. Retrieve a MIME sub-message
  332. @type part: L{int}
  333. @param part: The number of the part to retrieve, indexed from 0.
  334. @raise IndexError: Raised if the specified part does not exist.
  335. @raise TypeError: Raised if this message is not multipart.
  336. @rtype: Any object implementing L{IMessageIMAPPart}.
  337. @return: The specified sub-part.
  338. """
  339. class IMessageIMAP(IMessageIMAPPart):
  340. def getUID():
  341. """
  342. Retrieve the unique identifier associated with this message.
  343. """
  344. def getFlags():
  345. """
  346. Retrieve the flags associated with this message.
  347. @rtype: C{iterable}
  348. @return: The flags, represented as strings.
  349. """
  350. def getInternalDate():
  351. """
  352. Retrieve the date internally associated with this message.
  353. @rtype: L{bytes}
  354. @return: An RFC822-formatted date string.
  355. """
  356. class IMessageIMAPFile(Interface):
  357. """
  358. Optional message interface for representing messages as files.
  359. If provided by message objects, this interface will be used instead the
  360. more complex MIME-based interface.
  361. """
  362. def open():
  363. """
  364. Return a file-like object opened for reading.
  365. Reading from the returned file will return all the bytes of which this
  366. message consists.
  367. """
  368. class ISearchableIMAPMailbox(Interface):
  369. def search(query, uid):
  370. """
  371. Search for messages that meet the given query criteria.
  372. If this interface is not implemented by the mailbox,
  373. L{IMailboxIMAP.fetch} and various methods of L{IMessageIMAP} will be
  374. used instead.
  375. Implementations which wish to offer better performance than the default
  376. implementation should implement this interface.
  377. @type query: L{list}
  378. @param query: The search criteria
  379. @type uid: L{bool}
  380. @param uid: If true, the IDs specified in the query are UIDs; otherwise
  381. they are message sequence IDs.
  382. @rtype: L{list} or L{Deferred}
  383. @return: A list of message sequence numbers or message UIDs which match
  384. the search criteria or a L{Deferred} whose callback will be invoked
  385. with such a list.
  386. @raise IllegalQueryError: Raised when query is not valid.
  387. """
  388. class IMailboxIMAPListener(Interface):
  389. """
  390. Interface for objects interested in mailbox events
  391. """
  392. def modeChanged(writeable):
  393. """
  394. Indicates that the write status of a mailbox has changed.
  395. @type writeable: L{bool}
  396. @param writeable: A true value if write is now allowed, false
  397. otherwise.
  398. """
  399. def flagsChanged(newFlags):
  400. """
  401. Indicates that the flags of one or more messages have changed.
  402. @type newFlags: L{dict}
  403. @param newFlags: A mapping of message identifiers to tuples of flags
  404. now set on that message.
  405. """
  406. def newMessages(exists, recent):
  407. """
  408. Indicates that the number of messages in a mailbox has changed.
  409. @type exists: L{int} or L{None}
  410. @param exists: The total number of messages now in this mailbox. If the
  411. total number of messages has not changed, this should be L{None}.
  412. @type recent: L{int}
  413. @param recent: The number of messages now flagged C{\\Recent}. If the
  414. number of recent messages has not changed, this should be L{None}.
  415. """
  416. class IMessageIMAPCopier(Interface):
  417. def copy(messageObject):
  418. """
  419. Copy the given message object into this mailbox.
  420. The message object will be one which was previously returned by
  421. L{IMailboxIMAP.fetch}.
  422. Implementations which wish to offer better performance than the default
  423. implementation should implement this interface.
  424. If this interface is not implemented by the mailbox,
  425. L{IMailboxIMAP.addMessage} will be used instead.
  426. @rtype: L{Deferred} or L{int}
  427. @return: Either the UID of the message or a Deferred which fires with
  428. the UID when the copy finishes.
  429. """
  430. class IMailboxIMAPInfo(Interface):
  431. """
  432. Interface specifying only the methods required for C{listMailboxes}.
  433. Implementations can return objects implementing only these methods for
  434. return to C{listMailboxes} if it can allow them to operate more
  435. efficiently.
  436. """
  437. def getFlags():
  438. """
  439. Return the flags defined in this mailbox
  440. Flags with the \\ prefix are reserved for use as system flags.
  441. @rtype: L{list} of L{str}
  442. @return: A list of the flags that can be set on messages in this
  443. mailbox.
  444. """
  445. def getHierarchicalDelimiter():
  446. """
  447. Get the character which delimits namespaces for in this mailbox.
  448. @rtype: L{bytes}
  449. """
  450. class IMailboxIMAP(IMailboxIMAPInfo):
  451. def getUIDValidity():
  452. """
  453. Return the unique validity identifier for this mailbox.
  454. @rtype: L{int}
  455. """
  456. def getUIDNext():
  457. """
  458. Return the likely UID for the next message added to this mailbox.
  459. @rtype: L{int}
  460. """
  461. def getUID(message):
  462. """
  463. Return the UID of a message in the mailbox
  464. @type message: L{int}
  465. @param message: The message sequence number
  466. @rtype: L{int}
  467. @return: The UID of the message.
  468. """
  469. def getMessageCount():
  470. """
  471. Return the number of messages in this mailbox.
  472. @rtype: L{int}
  473. """
  474. def getRecentCount():
  475. """
  476. Return the number of messages with the 'Recent' flag.
  477. @rtype: L{int}
  478. """
  479. def getUnseenCount():
  480. """
  481. Return the number of messages with the 'Unseen' flag.
  482. @rtype: L{int}
  483. """
  484. def isWriteable():
  485. """
  486. Get the read/write status of the mailbox.
  487. @rtype: L{int}
  488. @return: A true value if write permission is allowed, a false value
  489. otherwise.
  490. """
  491. def destroy():
  492. """
  493. Called before this mailbox is deleted, permanently.
  494. If necessary, all resources held by this mailbox should be cleaned up
  495. here. This function _must_ set the \\Noselect flag on this mailbox.
  496. """
  497. def requestStatus(names):
  498. """
  499. Return status information about this mailbox.
  500. Mailboxes which do not intend to do any special processing to generate
  501. the return value, C{statusRequestHelper} can be used to build the
  502. dictionary by calling the other interface methods which return the data
  503. for each name.
  504. @type names: Any iterable
  505. @param names: The status names to return information regarding. The
  506. possible values for each name are: MESSAGES, RECENT, UIDNEXT,
  507. UIDVALIDITY, UNSEEN.
  508. @rtype: L{dict} or L{Deferred}
  509. @return: A dictionary containing status information about the requested
  510. names is returned. If the process of looking this information up
  511. would be costly, a deferred whose callback will eventually be
  512. passed this dictionary is returned instead.
  513. """
  514. def addListener(listener):
  515. """
  516. Add a mailbox change listener
  517. @type listener: Any object which implements C{IMailboxIMAPListener}
  518. @param listener: An object to add to the set of those which will be
  519. notified when the contents of this mailbox change.
  520. """
  521. def removeListener(listener):
  522. """
  523. Remove a mailbox change listener
  524. @type listener: Any object previously added to and not removed from
  525. this mailbox as a listener.
  526. @param listener: The object to remove from the set of listeners.
  527. @raise ValueError: Raised when the given object is not a listener for
  528. this mailbox.
  529. """
  530. def addMessage(message, flags, date):
  531. """
  532. Add the given message to this mailbox.
  533. @type message: A file-like object
  534. @param message: The RFC822 formatted message
  535. @type flags: Any iterable of L{bytes}
  536. @param flags: The flags to associate with this message
  537. @type date: L{bytes}
  538. @param date: If specified, the date to associate with this message.
  539. @rtype: L{Deferred}
  540. @return: A deferred whose callback is invoked with the message id if
  541. the message is added successfully and whose errback is invoked
  542. otherwise.
  543. @raise ReadOnlyMailbox: Raised if this Mailbox is not open for
  544. read-write.
  545. """
  546. def expunge():
  547. """
  548. Remove all messages flagged \\Deleted.
  549. @rtype: L{list} or L{Deferred}
  550. @return: The list of message sequence numbers which were deleted, or a
  551. L{Deferred} whose callback will be invoked with such a list.
  552. @raise ReadOnlyMailbox: Raised if this Mailbox is not open for
  553. read-write.
  554. """
  555. def fetch(messages, uid):
  556. """
  557. Retrieve one or more messages.
  558. @type messages: C{MessageSet}
  559. @param messages: The identifiers of messages to retrieve information
  560. about
  561. @type uid: L{bool}
  562. @param uid: If true, the IDs specified in the query are UIDs; otherwise
  563. they are message sequence IDs.
  564. @rtype: Any iterable of two-tuples of message sequence numbers and
  565. implementors of C{IMessageIMAP}.
  566. """
  567. def store(messages, flags, mode, uid):
  568. """
  569. Set the flags of one or more messages.
  570. @type messages: A MessageSet object with the list of messages requested
  571. @param messages: The identifiers of the messages to set the flags of.
  572. @type flags: sequence of L{str}
  573. @param flags: The flags to set, unset, or add.
  574. @type mode: -1, 0, or 1
  575. @param mode: If mode is -1, these flags should be removed from the
  576. specified messages. If mode is 1, these flags should be added to
  577. the specified messages. If mode is 0, all existing flags should be
  578. cleared and these flags should be added.
  579. @type uid: L{bool}
  580. @param uid: If true, the IDs specified in the query are UIDs; otherwise
  581. they are message sequence IDs.
  582. @rtype: L{dict} or L{Deferred}
  583. @return: A L{dict} mapping message sequence numbers to sequences of
  584. L{str} representing the flags set on the message after this
  585. operation has been performed, or a L{Deferred} whose callback will
  586. be invoked with such a L{dict}.
  587. @raise ReadOnlyMailbox: Raised if this mailbox is not open for
  588. read-write.
  589. """
  590. class ICloseableMailboxIMAP(Interface):
  591. """
  592. A supplementary interface for mailboxes which require cleanup on close.
  593. Implementing this interface is optional. If it is implemented, the protocol
  594. code will call the close method defined whenever a mailbox is closed.
  595. """
  596. def close():
  597. """
  598. Close this mailbox.
  599. @return: A L{Deferred} which fires when this mailbox has been closed,
  600. or None if the mailbox can be closed immediately.
  601. """
  602. class IAccountIMAP(Interface):
  603. """
  604. Interface for Account classes
  605. Implementors of this interface should consider implementing
  606. C{INamespacePresenter}.
  607. """
  608. def addMailbox(name, mbox=None):
  609. """
  610. Add a new mailbox to this account
  611. @type name: L{bytes}
  612. @param name: The name associated with this mailbox. It may not contain
  613. multiple hierarchical parts.
  614. @type mbox: An object implementing C{IMailboxIMAP}
  615. @param mbox: The mailbox to associate with this name. If L{None}, a
  616. suitable default is created and used.
  617. @rtype: L{Deferred} or L{bool}
  618. @return: A true value if the creation succeeds, or a deferred whose
  619. callback will be invoked when the creation succeeds.
  620. @raise MailboxException: Raised if this mailbox cannot be added for
  621. some reason. This may also be raised asynchronously, if a
  622. L{Deferred} is returned.
  623. """
  624. def create(pathspec):
  625. """
  626. Create a new mailbox from the given hierarchical name.
  627. @type pathspec: L{bytes}
  628. @param pathspec: The full hierarchical name of a new mailbox to create.
  629. If any of the inferior hierarchical names to this one do not exist,
  630. they are created as well.
  631. @rtype: L{Deferred} or L{bool}
  632. @return: A true value if the creation succeeds, or a deferred whose
  633. callback will be invoked when the creation succeeds.
  634. @raise MailboxException: Raised if this mailbox cannot be added. This
  635. may also be raised asynchronously, if a L{Deferred} is returned.
  636. """
  637. def select(name, rw=True):
  638. """
  639. Acquire a mailbox, given its name.
  640. @type name: L{bytes}
  641. @param name: The mailbox to acquire
  642. @type rw: L{bool}
  643. @param rw: If a true value, request a read-write version of this
  644. mailbox. If a false value, request a read-only version.
  645. @rtype: Any object implementing C{IMailboxIMAP} or L{Deferred}
  646. @return: The mailbox object, or a L{Deferred} whose callback will be
  647. invoked with the mailbox object. None may be returned if the
  648. specified mailbox may not be selected for any reason.
  649. """
  650. def delete(name):
  651. """
  652. Delete the mailbox with the specified name.
  653. @type name: L{bytes}
  654. @param name: The mailbox to delete.
  655. @rtype: L{Deferred} or L{bool}
  656. @return: A true value if the mailbox is successfully deleted, or a
  657. L{Deferred} whose callback will be invoked when the deletion
  658. completes.
  659. @raise MailboxException: Raised if this mailbox cannot be deleted. This
  660. may also be raised asynchronously, if a L{Deferred} is returned.
  661. """
  662. def rename(oldname, newname):
  663. """
  664. Rename a mailbox
  665. @type oldname: L{bytes}
  666. @param oldname: The current name of the mailbox to rename.
  667. @type newname: L{bytes}
  668. @param newname: The new name to associate with the mailbox.
  669. @rtype: L{Deferred} or L{bool}
  670. @return: A true value if the mailbox is successfully renamed, or a
  671. L{Deferred} whose callback will be invoked when the rename
  672. operation is completed.
  673. @raise MailboxException: Raised if this mailbox cannot be renamed. This
  674. may also be raised asynchronously, if a L{Deferred} is returned.
  675. """
  676. def isSubscribed(name):
  677. """
  678. Check the subscription status of a mailbox
  679. @type name: L{bytes}
  680. @param name: The name of the mailbox to check
  681. @rtype: L{Deferred} or L{bool}
  682. @return: A true value if the given mailbox is currently subscribed to,
  683. a false value otherwise. A L{Deferred} may also be returned whose
  684. callback will be invoked with one of these values.
  685. """
  686. def subscribe(name):
  687. """
  688. Subscribe to a mailbox
  689. @type name: L{bytes}
  690. @param name: The name of the mailbox to subscribe to
  691. @rtype: L{Deferred} or L{bool}
  692. @return: A true value if the mailbox is subscribed to successfully, or
  693. a Deferred whose callback will be invoked with this value when the
  694. subscription is successful.
  695. @raise MailboxException: Raised if this mailbox cannot be subscribed
  696. to. This may also be raised asynchronously, if a L{Deferred} is
  697. returned.
  698. """
  699. def unsubscribe(name):
  700. """
  701. Unsubscribe from a mailbox
  702. @type name: L{bytes}
  703. @param name: The name of the mailbox to unsubscribe from
  704. @rtype: L{Deferred} or L{bool}
  705. @return: A true value if the mailbox is unsubscribed from successfully,
  706. or a Deferred whose callback will be invoked with this value when
  707. the unsubscription is successful.
  708. @raise MailboxException: Raised if this mailbox cannot be unsubscribed
  709. from. This may also be raised asynchronously, if a L{Deferred} is
  710. returned.
  711. """
  712. def listMailboxes(ref, wildcard):
  713. """
  714. List all the mailboxes that meet a certain criteria
  715. @type ref: L{bytes}
  716. @param ref: The context in which to apply the wildcard
  717. @type wildcard: L{bytes}
  718. @param wildcard: An expression against which to match mailbox names.
  719. '*' matches any number of characters in a mailbox name, and '%'
  720. matches similarly, but will not match across hierarchical
  721. boundaries.
  722. @rtype: L{list} of L{tuple}
  723. @return: A list of C{(mailboxName, mailboxObject)} which meet the given
  724. criteria. C{mailboxObject} should implement either
  725. C{IMailboxIMAPInfo} or C{IMailboxIMAP}. A Deferred may also be
  726. returned.
  727. """
  728. class INamespacePresenter(Interface):
  729. def getPersonalNamespaces():
  730. """
  731. Report the available personal namespaces.
  732. Typically there should be only one personal namespace. A common name
  733. for it is C{\"\"}, and its hierarchical delimiter is usually C{\"/\"}.
  734. @rtype: iterable of two-tuples of strings
  735. @return: The personal namespaces and their hierarchical delimiters. If
  736. no namespaces of this type exist, None should be returned.
  737. """
  738. def getSharedNamespaces():
  739. """
  740. Report the available shared namespaces.
  741. Shared namespaces do not belong to any individual user but are usually
  742. to one or more of them. Examples of shared namespaces might be
  743. C{\"#news\"} for a usenet gateway.
  744. @rtype: iterable of two-tuples of strings
  745. @return: The shared namespaces and their hierarchical delimiters. If no
  746. namespaces of this type exist, None should be returned.
  747. """
  748. def getUserNamespaces():
  749. """
  750. Report the available user namespaces.
  751. These are namespaces that contain folders belonging to other users
  752. access to which this account has been granted.
  753. @rtype: iterable of two-tuples of strings
  754. @return: The user namespaces and their hierarchical delimiters. If no
  755. namespaces of this type exist, None should be returned.
  756. """
  757. __all__ = [
  758. # IMAP
  759. "IAccountIMAP",
  760. "ICloseableMailboxIMAP",
  761. "IMailboxIMAP",
  762. "IMailboxIMAPInfo",
  763. "IMailboxIMAPListener",
  764. "IMessageIMAP",
  765. "IMessageIMAPCopier",
  766. "IMessageIMAPFile",
  767. "IMessageIMAPPart",
  768. "ISearchableIMAPMailbox",
  769. "INamespacePresenter",
  770. # SMTP
  771. "IMessageDelivery",
  772. "IMessageDeliveryFactory",
  773. "IMessageSMTP",
  774. # Domains and aliases
  775. "IDomain",
  776. "IAlias",
  777. "IAliasableDomain",
  778. # POP3
  779. "IMailboxPOP3",
  780. "IServerFactoryPOP3",
  781. # Authentication
  782. "IClientAuthentication",
  783. ]