Mercurial > pidgin
diff src/protocols/sametime/meanwhile/mw_srvc_ft.h @ 10969:3ef77720e577
[gaim-migrate @ 12790]
importing meanwhile library for use in the sametime plugin
committer: Tailor Script <tailor@pidgin.im>
author | Christopher O'Brien <siege@pidgin.im> |
---|---|
date | Sun, 05 Jun 2005 02:50:13 +0000 |
parents | |
children | 0110fc7c6a8a |
line wrap: on
line diff
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/src/protocols/sametime/meanwhile/mw_srvc_ft.h Sun Jun 05 02:50:13 2005 +0000 @@ -0,0 +1,235 @@ + +/* + Meanwhile - Unofficial Lotus Sametime Community Client Library + Copyright (C) 2004 Christopher (siege) O'Brien + + This library is free software; you can redistribute it and/or + modify it under the terms of the GNU Library General Public + License as published by the Free Software Foundation; either + version 2 of the License, or (at your option) any later version. + + This library 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 + Library General Public License for more details. + + You should have received a copy of the GNU Library General Public + License along with this library; if not, write to the Free + Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA +*/ + + +#ifndef _MW_SRVC_FT_H +#define _MW_SRVC_FT_H + + +#include "mw_common.h" + + +/** @file mw_srvc_ft.h + + A file transfer is a simple way to get large chunks of binary data + from one client to another. +*/ + + +/** @struct mwServiceFileTransfer + File transfer service +*/ +struct mwServiceFileTransfer; + + +/** @struct mwFileTransfer + A single file trasfer session + */ +struct mwFileTransfer; + + +#define mwService_FILE_TRANSFER 0x00000038 + + +enum mwFileTransferState { + mwFileTransfer_NEW, /**< file transfer is not open */ + mwFileTransfer_PENDING, /**< file transfer is opening */ + mwFileTransfer_OPEN, /**< file transfer is open */ + mwFileTransfer_CANCEL_LOCAL, + mwFileTransfer_CANCEL_REMOTE, + mwFileTransfer_DONE, + mwFileTransfer_ERROR, /**< error in file transfer */ + mwFileTransfer_UNKNOWN, /**< unknown state */ +}; + + +#define mwFileTransfer_isState(ft, state) \ + (mwFileTransfer_getState(ft) == (state)) + +#define mwFileTransfer_isNew(ft) \ + mwFileTransfer_isState((ft), mwFileTransfer_NEW) + +#define mwFileTransfer_isPending(ft) \ + mwFileTransfer_isState((ft), mwFileTransfer_PENDING) + +#define mwFileTransfer_isOpen(ft) \ + mwFileTransfer_isState((ft), mwFileTransfer_OPEN) + +#define mwFileTransfer_isDone(ft) \ + mwFileTransfer_isState((ft), mwFileTransfer_DONE) + +#define mwFileTransfer_isCancelLocal(ft) \ + mwFileTransfer_isState((ft), mwFileTransfer_CANCEL_LOCAL) + +#define mwFileTransfer_isCancelRemote(ft) \ + mwFileTransfer_isState((ft), mwFileTransfer_CANCEL_REMOTE) + + +enum mwFileTranferCode { + mwFileTransfer_SUCCESS = 0x00000000, + mwFileTransfer_REJECTED = 0x08000606, +}; + + +struct mwFileTransferHandler { + + /** an incoming file transfer has been offered */ + void (*ft_offered)(struct mwFileTransfer *ft); + + /** a file transfer has been fully initiated */ + void (*ft_opened)(struct mwFileTransfer *ft); + + /** a file transfer has been closed. Check the status of the file + transfer to determine if the transfer was complete or if it had + been interrupted */ + void (*ft_closed)(struct mwFileTransfer *ft, guint32 code); + + /** receive a chunk of a file from an inbound file transfer. */ + void (*ft_recv)(struct mwFileTransfer *ft, struct mwOpaque *data); + + /** received an ack for a sent chunk on an outbound file transfer. + this indicates that a previous call to mwFileTransfer_send has + reached the target and that the target has responded. */ + void (*ft_ack)(struct mwFileTransfer *ft); + + /** optional. called from mwService_free */ + void (*clear)(struct mwServiceFileTransfer *srvc); +}; + + +struct mwServiceFileTransfer * +mwServiceFileTransfer_new(struct mwSession *session, + struct mwFileTransferHandler *handler); + + +struct mwFileTransferHandler * +mwServiceFileTransfer_getHandler(struct mwServiceFileTransfer *srvc); + + +struct mwFileTransfer * +mwFileTransfer_new(struct mwServiceFileTransfer *srvc, + const struct mwIdBlock *who, const char *msg, + const char *filename, guint32 filesize); + + +/** deallocate a file transfer. will call mwFileTransfer_close if + necessary */ +void +mwFileTransfer_free(struct mwFileTransfer *ft); + + +/** the status of this file transfer */ +enum mwFileTransferState +mwFileTransfer_getState(struct mwFileTransfer *ft); + + +struct mwServiceFileTransfer * +mwFileTransfer_getService(struct mwFileTransfer *ft); + + +/** the user on the other end of the file transfer */ +const struct mwIdBlock * +mwFileTransfer_getUser(struct mwFileTransfer *ft); + + +/** the message sent along with an offered file transfer */ +const char * +mwFileTransfer_getMessage(struct mwFileTransfer *ft); + + +/** the publicized file name. Not necessarily related to any actual + file on either system */ +const char * +mwFileTransfer_getFileName(struct mwFileTransfer *ft); + + +/** total bytes intended to be sent/received */ +guint32 mwFileTransfer_getFileSize(struct mwFileTransfer *ft); + + +/** bytes remaining to be received/send */ +guint32 mwFileTransfer_getRemaining(struct mwFileTransfer *ft); + + +/** count of bytes sent/received over this file transfer so far */ +#define mwFileTransfer_getSent(ft) \ + (mwFileTransfer_getFileSize(ft) - mwFileTransfer_getRemaining(ft)) + + +/** initiate an outgoing file transfer */ +int mwFileTransfer_offer(struct mwFileTransfer *ft); + + +/** accept an incoming file transfer */ +int mwFileTransfer_accept(struct mwFileTransfer *ft); + + +/** reject an incoming file transfer */ +#define mwFileTransfer_reject(ft) \ + mwFileTransfer_close((ft), mwFileTransfer_REJECTED) + + +/** cancel an open file transfer */ +#define mwFileTransfer_cancel(ft) \ + mwFileTransfer_close((ft), mwFileTransfer_SUCCESS); + + +/** Close a file transfer. This will trigger the ft_close function of the + session's handler. + + @relates mwFileTransfer_reject + @relates mwFileTransfer_cancel +*/ +int mwFileTransfer_close(struct mwFileTransfer *ft, guint32 code); + + +/** send a chunk of data over an outbound file transfer. The client at + the other end of the transfer should respond with an acknowledgement + message, which can be caught in the service's handler. + + @relates mwFileTransferHandler::ft_ack +*/ +int mwFileTransfer_send(struct mwFileTransfer *ft, + struct mwOpaque *data); + + +/** acknowledge the receipt of a chunk of data from an inbound file + transfer. This should be done after every received chunk, or the + transfer will stall. However, not all clients will wait for an ack + after sending a chunk before sending the next chunk, so it is + possible to have the handler's ft_recv function triggered again + even if no ack was sent. + + @relates mwFileTransferHandler::ft_recv +*/ +int mwFileTransfer_ack(struct mwFileTransfer *ft); + + +void mwFileTransfer_setClientData(struct mwFileTransfer *ft, + gpointer data, GDestroyNotify clean); + + +gpointer mwFileTransfer_getClientData(struct mwFileTransfer *ft); + + +void mwFileTransfer_removeClientData(struct mwFileTransfer *ft); + + +#endif