ClowdsStoragePlugin Documentation Publicación alpha Igeko 05 de May de 2015
Índice general 1. Bienvenido a la documentación de Clowds 1 1.1. Para empezar bien.............................................. 1 2. Advertencias 3 2.1. Indicaciones Generales.......................................... 3 3. Lista de Funciones 5 3.1. getchanges()............................................... 5 3.2. downloadfile(qstring remotepath, QString localpath)......................... 5 3.3. uploadfile(qstring remotepath, QString localpath)........................... 6 4. Anexo 1. Clases recomendables 7 4.1. Clase JsonData.............................................. 7 4.2. Clase File................................................. 7 4.3. Clase MyO2............................................... 7 4.4. Clase Change............................................... 8 5. Anexo 2. Clase principal: campos y métodos útiles 9 5.1. QString accesstoken........................................... 9 5.2. QString nextchanges........................................... 9 5.3. QHash allevents............................................. 9 5.4. QHash > mychanges........................................... 10 5.5. QHash filesbyid............................................. 10 5.6. QHash filesbypath............................................ 10 5.7. QHash<QString, QList<CloudS..................................... 10 I
II
CAPÍTULO 1 Bienvenido a la documentación de Clowds Aquí encontrarás toda la información oficial actualizada sobre el desarrollo de plugins para Clowds. Ten paciencia, seguimos redactando nuevos tópicos. Si crees que falta algo o que podemos mejorar la información puedes dejar tus comentarios y aportaciones en el foro o enviarlos a developers@clowds.net 1.1 Para empezar bien.. Por favor lee primero que nada las Advertencias, son importantes. 1
ClowdsStoragePlugin Documentation, Publicación alpha 2 Capítulo 1. Bienvenido a la documentación de Clowds
CAPÍTULO 2 Advertencias No utilizar ninguna función de Qt que esté en una versión superior a la que Ubuntu tenga actualmente en su repositorio. Cambiar el nombre del proyecto DummyPlugin que viene por defecto en la plantilla por el del proyecto a desarrollar. Clowds distingue entre directorios y archivos con /. Cuando acaba en /, se trata de un directorio. 2.1 Indicaciones Generales Se sugiere trabajar con las distintas clases y objetos propuestos en el Anexo 1 y el Anexo 2 para facilitar el desarrollo del Plug-in. 3
ClowdsStoragePlugin Documentation, Publicación alpha 4 Capítulo 2. Advertencias
CAPÍTULO 3 Lista de Funciones 3.1 getchanges() Esta es la función principal del Plug-in, la más importante, y normalmente la que más código dedica. Su cometido es el de recibir información de los sucesos de la nube, procesar esos eventos, y traducirlos en cambios de Clowds (CloudStorageChange), para que el programa sepa qué hacer con ellos. Devuelve un QHash<QString, QList<CloudStorageChange> > el cual contendrá un registro de los cambios que se van a realizar. La clave será la ruta del fichero en Qstring, y su valor un CloudStorageChange, que es el cambio que ha sufrido. El primer paso será hacer la petición HTTP para obtener la lista de los eventos ocurridos en la nube e ir guardándolos en un QHash, por ejemplo allevents (ver ANEXO 2). Lo importante es que el QHash almacene los metadatos (normalmente en JSON). En el caso de que la nube pueda devolver más de un cambio por archivo, una buena manera de tratar esta lista de cambios sería hacer otro QHash, como mychanges (Ver ANEXO 2), en el que en cada valor almacene un QMap. Este QMap sería una lista de los eventos (metadatos), indexada por fecha. QHash < file_id, QMap<fecha, evento> > Con esto se conseguirá que por cada fichero haya una lista de todos sus cambios ordenados cronológicamente. La mecánica será recorrer todos esos cambios ordenados por fecha para ir procesando por cada fichero sus cambios uno a uno, del más antiguo al más reciente. Según los metadatos de cada evento, debemos ir asignando las Flags en función de qué clase de evento se trate: subir o crear es New, renombrar o mover es Moved, etc. 3.2 downloadfile(qstring remotepath, QString localpath) Esta función descarga desde la nube cada archivo que Clowds considere que debe descargar al sincronizar. Aquí sólo debes preocuparte de introducir la petición HTTP que requiera el sistema que estemos implementando para hacer la descarga de un sólo archivo. Hay que tener en cuenta que cada vez que Clowds ejecute la función, pasará por parámetro las variables remotepath y localpath. Generalmente son iguales, salvo que el sistema con el que estemos trabajando cifre los directorios. En ese caso, remotepath estará cifrada. El único momento en el que se ha de utilizar localpath, es cuando le indicamos la ruta de descarga. Para descargar el archivo: resources_->shrget(qurl, QFile); QUrl - URL de la petición. QFile - El archivo que se descargará en la carpeta de sincronización. Dependiendo del sistema con el que estemos trabajando, es posible que se requieran cabeceras, o parámetros en la URL. 5
ClowdsStoragePlugin Documentation, Publicación alpha 3.3 uploadfile(qstring remotepath, QString localpath) Esta función se encarga de subir los archivos que Clowds detecte como new en la carpeta de sincronización. Al sincronizar Clowds, se encargará de subir a la nube los archivos creados en local. Recordemos que cada vez que Clowds ejecute la función, pasará por parámetro las variables remotepath y localpath. Generalmente son iguales, salvo que el sistema con el que estemos 6 Capítulo 3. Lista de Funciones
CAPÍTULO 4 Anexo 1. Clases recomendables Nada de lo descrito en este Anexo es obligatorio para el funcionamiento de un Plug-in para Clowds. Son recomendaciones para facilitar su desarrollo. 4.1 Clase JsonData Esta clase sirve para tratar objetos QJsonObject. 4.2 Clase File Esta clase descompondrá los metadatos, y guardará los datos clave de cada archivo -tipo de fichero, nombre, ID, directorio padre, etc.- de forma que podamos trabajar con ellos fácilmente. Normalmente los servicios dan los metadatos en formato JSON, de manera que esta clase debe heredar de JsonData. En caso de que los metadatos estén en otro formato, habría que hacer una clase similar a JsonData para tratar ese formato, por ejemplo XmlData. Estructura de ejemplo: QString id - ID del fichero. QString path - Ruta completa del fichero, si es un directorio debe acabar en /. bool isfolder - Booleano que indica si el fichero es un directorio. True es un directorio, false es un archivo. QString parentid - ID del directorio padre del fichero. QString title - Nombre del fichero. Todos estos campos se rellenan en un constructor al que se le pasa un QJsonObject, en el caso de que los metadatos sean en formato JSON. 4.3 Clase MyO2 Esta clase hereda de O2. Se encarga de realizar la autenticación y autorización mediante OAuth2, si el servicio lo requiriera. En algunos servicios, como por ejemplo Bitcasa, usa aspectos de OAuth1 y de OAuth2. 7
ClowdsStoragePlugin Documentation, Publicación alpha 4.4 Clase Change Esta clase hereda de JsonData. Debe guardar los metadatos de cada evento y, aparte, la fecha del propio evento, para poder ordenar los cronológicamente. La forma de hacerlo depende del servicio que estemos implementando, por que hay algunos que ya los dan ordenados. Estructura: File file - Objeto File del fichero afectado del evento. QDateTime date - Fecha del evento. 8 Capítulo 4. Anexo 1. Clases recomendables
CAPÍTULO 5 Anexo 2. Clase principal: campos y métodos útiles Nada de lo descrito en este Anexo es obligatorio para el funcionamiento de un Plug-in para Clowds. Son recomendaciones para facilitar su desarrollo. Se sugiere que el nombre de la clase principal guarde relación con el nombre del servicio que se va a implementar. De aquí en adelante la llamaremos mycloud. 5.1 QString accesstoken Access Token En caso de utilizar OAuth2, puede ser útil guardar en esta variable el access token, ya que lo más normal es que tengas que introducirlo en cada petición HTTP para la autorización. 5.2 QString nextchanges Marcador de eventos Generalmente el servicio debe ponernos a disposición alguna forma de recibir los cambios desde un punto en concreto. En esta variable debemos guardar cada vez que hay cambios la última posición de los mismos, para tener un orden. Este valor debe registrarse además en la base de datos para guardar la posición al cerrar el programa y la volvemos a recuperar de la base de datos al iniciar de nuevo el programa. resources_->settingssetvalue(qstring key, QString value); 5.3 QHash allevents Lista de todos los eventos En esta lista se almacenarán temporalmente (sin importar su contenido) todos los cambios que reciba Clowds en cada llamada a getchanges(). Clave: ID del evento. Valor: Objeto Change, con el QJsonObject entero del evento. 9
ClowdsStoragePlugin Documentation, Publicación alpha 5.4 QHash > mychanges Lista de todos los cambios por cada archivo Este QHash es el que retorna getchanges(). De todos los eventos de allevents, solo se insertarán en mychanges aquellos eventos que sean cambios válidos para Clowds (Insertar, modificar, borrar, mover, restaurar de la papelera... ). Eventos como marcar un archivo como favorito, añadir o quitar etiquetas, son eventos inservibles para Clowds. Guardará de cada archivo, un QMap con todos sus cambios, indexados por fecha (recomendable UNIX Time Stamp) para ordenarlos cronológicamente. Clave: ID del archivo. Valor: QMap { Clave: Fecha (UNIX Time Stamp). Valor: Objeto Change. }. 5.5 QHash filesbyid Lista de archivos indexada por ID En este QHash se irán insertando los archivos que se vayan descargando o creando en la nube indexados por el ID del archivo, para poder tener un registro de todos los archivos que tenemos almacenados, y así poder conseguir información de cada uno de ellos en cualquier momento. Clave: ID del archivo [File::getId()] Valor: Archivo [File] 5.6 QHash filesbypath Lista de archivos indexada por la ruta del archivo En este QHash se irán insertando los archivos que se vayan descargando o creando en la nube indexados por la ruta (path) del archivo, para poder tener un registro de todos los archivos que tenemos almacenados, y así poder conseguir información de cada uno de ellos en cualquier momento. Clave: Ruta del archivo [File::getPath()] Valor: Archivo [File] 5.7 QHash<QString, QList<CloudS 10 Capítulo 5. Anexo 2. Clase principal: campos y métodos útiles