'Send a CAPA command to retrieve the capabilities supported by
the server.
Not all servers support this command.  If the server does not
support this, it is treated as though it returned a successful
response listing no capabilities.  At some future time, this may be
changed to instead seek out information about a server\'s
capabilities in some other fashion (only if it proves useful to do
so, and only if there are servers still in use which do not support
CAPA but which do support POP3 extensions that are useful).
@type useCache: L{bool}
@param useCache: A flag that determines whether previously retrieved
results should be used if available.
@rtype: L{Deferred <defer.Deferred>} which successfully results in
L{dict} mapping L{bytes} to L{list} of L{bytes} and/or L{bytes} to
L{None}
@return: A deferred which fires with a mapping of capability name to
parameters.  For example::
C: CAPA
S: +OK Capability list follows
S: TOP
S: USER
S: SASL CRAM-MD5 KERBEROS_V4
S: RESP-CODES
S: LOGIN-DELAY 900
S: PIPELINING
S: EXPIRE 60
S: UIDL
S: IMPLEMENTATION Shlemazle-Plotz-v302
S: .
will be lead to a result of::
| {\'TOP\': None,
|  \'USER\': None,
|  \'SASL\': [\'CRAM-MD5\', \'KERBEROS_V4\'],
|  \'RESP-CODES\': None,
|  \'LOGIN-DELAY\': [\'900\'],
|  \'PIPELINING\': None,
|  \'EXPIRE\': [\'60\'],
|  \'UIDL\': None,
|  \'IMPLEMENTATION\': [\'Shlemazle-Plotz-v302\']}'

def capabilities(self, useCache=True):

    if (useCache and (self._capCache is not None)):
        return defer.succeed(self._capCache)
    cache = {}
    def consume(line):
        tmp = line.split()
        if (len(tmp) == 1):
            cache[tmp[0]] = None
        elif (len(tmp) > 1):
            cache[tmp[0]] = tmp[1:]
    def capaNotSupported(err):
        err.trap(ServerErrorResponse)
        return None
    def gotCapabilities(result):
        self._capCache = cache
        return cache
    d = self._consumeOrAppend('CAPA', None, consume, None)
    d.addErrback(capaNotSupported).addCallback(gotCapabilities)
    return d
