Source code for aioxmpp.httpupload

########################################################################
# File name: __init__.py
# This file is part of: aioxmpp
#
# LICENSE
#
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU Lesser General Public License as
# published by the Free Software Foundation, either version 3 of the
# License, or (at your option) any later version.
#
# This program is distributed in the hope that it will be useful, but
# WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
# Lesser General Public License for more details.
#
# You should have received a copy of the GNU Lesser General Public
# License along with this program.  If not, see
# <http://www.gnu.org/licenses/>.
#
########################################################################
"""
:mod:`~aioxmpp.httpupload` --- HTTP Upload support (:xep:`363`)
###############################################################

The :xep:`363` HTTP Upload protocol allows an XMPP client to obtain a PUT and
GET URL for storage on the server. It can upload a file (once) using the PUT
URL and distribute access to the file via the GET url.

This module does *not* handle the HTTP part of the interaction. We recommend
to use :mod:`aiohttp` for this, but you can use any HTTP library which supports
GET, PUT and sending custom headers.

Example use::

    client = <your aioxmpp.Client>
    http_upload_service = <JID of the HTTP Upload service>
    slot = await client.send(aioxmpp.IQ(
        type_=aioxmpp.IQType.GET,
        to=http_upload_service,
        payload=aioxmpp.httpupload.Request(
            filename,
            size,
            content_type,
        )
    ))
    # http_put_file is provided by you via an HTTP library
    await http_put_file(
        slot.put.url,
        slot.put.headers,
        filename
    )

.. autofunction:: request_slot

.. autoclass:: Request

.. module:: aioxmpp.httpupload.xso

.. currentmodule:: aioxmpp.httpupload.xso

.. autoclass:: Slot()

.. autoclass:: Get()

.. autoclass:: Put()
"""
import asyncio

from ..structs import JID, IQType
from ..stanza import IQ
from .xso import Request


async def request_slot(client,
                       service: JID,
                       filename: str,
                       size: int,
                       content_type: str):
    """
    Request an HTTP upload slot.

    :param client: The client to request the slot with.
    :type client: :class:`aioxmpp.Client`
    :param service: Address of the HTTP upload service.
    :type service: :class:`~aioxmpp.JID`
    :param filename: Name of the file (without path), may be used by the server
        to generate the URL.
    :type filename: :class:`str`
    :param size: Size of the file in bytes
    :type size: :class:`int`
    :param content_type: The MIME type of the file
    :type content_type: :class:`str`
    :return: The assigned upload slot.
    :rtype: :class:`.xso.Slot`

    Sends a :xep:`363` slot request to the XMPP service to obtain HTTP
    PUT and GET URLs for a file upload.

    The upload slot is returned as a :class:`~.xso.Slot` object.
    """

    payload = Request(filename, size, content_type)
    return await client.send(IQ(
        type_=IQType.GET,
        to=service,
        payload=payload
    ))