meanwhile 1.1.1
mw_srvc_ft.h File Reference

A file transfer is a simple way to get large chunks of binary data from one client to another. More...

#include "mw_common.h"

Go to the source code of this file.

Data Structures

struct  mwFileTransferHandler
 

Macros

#define mwFileTransfer_cancel(ft)
 cancel an open file transfer
 
#define mwFileTransfer_getSent(ft)
 count of bytes sent/received over this file transfer so far
 
#define mwFileTransfer_isCancelLocal(ft)
 
#define mwFileTransfer_isCancelRemote(ft)
 
#define mwFileTransfer_isDone(ft)
 
#define mwFileTransfer_isNew(ft)
 
#define mwFileTransfer_isOpen(ft)
 
#define mwFileTransfer_isPending(ft)
 
#define mwFileTransfer_isState(ft, state)
 
#define mwFileTransfer_reject(ft)
 reject an incoming file transfer
 
#define mwService_FILE_TRANSFER   0x00000038
 

Enumerations

enum  mwFileTranferCode {
  mwFileTransfer_SUCCESS = 0x00000000 ,
  mwFileTransfer_REJECTED = 0x08000606
}
 
enum  mwFileTransferState {
  mwFileTransfer_NEW ,
  mwFileTransfer_PENDING ,
  mwFileTransfer_OPEN ,
  mwFileTransfer_CANCEL_LOCAL ,
  mwFileTransfer_CANCEL_REMOTE ,
  mwFileTransfer_DONE ,
  mwFileTransfer_ERROR ,
  mwFileTransfer_UNKNOWN
}
 

Functions

int mwFileTransfer_accept (struct mwFileTransfer *ft)
 accept an incoming file transfer
 
int mwFileTransfer_ack (struct mwFileTransfer *ft)
 acknowledge the receipt of a chunk of data from an inbound file transfer.
 
int mwFileTransfer_close (struct mwFileTransfer *ft, guint32 code)
 Close a file transfer.
 
void mwFileTransfer_free (struct mwFileTransfer *ft)
 deallocate a file transfer.
 
gpointer mwFileTransfer_getClientData (struct mwFileTransfer *ft)
 
const char * mwFileTransfer_getFileName (struct mwFileTransfer *ft)
 the publicized file name.
 
guint32 mwFileTransfer_getFileSize (struct mwFileTransfer *ft)
 total bytes intended to be sent/received
 
const char * mwFileTransfer_getMessage (struct mwFileTransfer *ft)
 the message sent along with an offered file transfer
 
guint32 mwFileTransfer_getRemaining (struct mwFileTransfer *ft)
 bytes remaining to be received/send
 
struct mwServiceFileTransfermwFileTransfer_getService (struct mwFileTransfer *ft)
 
enum mwFileTransferState mwFileTransfer_getState (struct mwFileTransfer *ft)
 the status of this file transfer
 
const struct mwIdBlockmwFileTransfer_getUser (struct mwFileTransfer *ft)
 the user on the other end of the file transfer
 
struct mwFileTransfermwFileTransfer_new (struct mwServiceFileTransfer *srvc, const struct mwIdBlock *who, const char *msg, const char *filename, guint32 filesize)
 
int mwFileTransfer_offer (struct mwFileTransfer *ft)
 initiate an outgoing file transfer
 
void mwFileTransfer_removeClientData (struct mwFileTransfer *ft)
 
int mwFileTransfer_send (struct mwFileTransfer *ft, struct mwOpaque *data)
 send a chunk of data over an outbound file transfer.
 
void mwFileTransfer_setClientData (struct mwFileTransfer *ft, gpointer data, GDestroyNotify clean)
 
struct mwFileTransferHandlermwServiceFileTransfer_getHandler (struct mwServiceFileTransfer *srvc)
 
const GList * mwServiceFileTransfer_getTransfers (struct mwServiceFileTransfer *srvc)
 
struct mwServiceFileTransfermwServiceFileTransfer_new (struct mwSession *session, struct mwFileTransferHandler *handler)
 

Detailed Description

A file transfer is a simple way to get large chunks of binary data from one client to another.

Macro Definition Documentation

◆ mwFileTransfer_cancel

#define mwFileTransfer_cancel ( ft)
Value:
@ mwFileTransfer_SUCCESS
Definition mw_srvc_ft.h:91
int mwFileTransfer_close(struct mwFileTransfer *ft, guint32 code)
Close a file transfer.

cancel an open file transfer

◆ mwFileTransfer_getSent

#define mwFileTransfer_getSent ( ft)
Value:
guint32 mwFileTransfer_getRemaining(struct mwFileTransfer *ft)
bytes remaining to be received/send
guint32 mwFileTransfer_getFileSize(struct mwFileTransfer *ft)
total bytes intended to be sent/received

count of bytes sent/received over this file transfer so far

◆ mwFileTransfer_isCancelLocal

#define mwFileTransfer_isCancelLocal ( ft)
Value:
@ mwFileTransfer_CANCEL_LOCAL
Definition mw_srvc_ft.h:60
#define mwFileTransfer_isState(ft, state)
Definition mw_srvc_ft.h:68

◆ mwFileTransfer_isCancelRemote

#define mwFileTransfer_isCancelRemote ( ft)
Value:
@ mwFileTransfer_CANCEL_REMOTE
Definition mw_srvc_ft.h:61

◆ mwFileTransfer_isDone

#define mwFileTransfer_isDone ( ft)
Value:
@ mwFileTransfer_DONE
Definition mw_srvc_ft.h:62

◆ mwFileTransfer_isNew

#define mwFileTransfer_isNew ( ft)
Value:
@ mwFileTransfer_NEW
file transfer is not open
Definition mw_srvc_ft.h:57

◆ mwFileTransfer_isOpen

#define mwFileTransfer_isOpen ( ft)
Value:
@ mwFileTransfer_OPEN
file transfer is open
Definition mw_srvc_ft.h:59

◆ mwFileTransfer_isPending

#define mwFileTransfer_isPending ( ft)
Value:
@ mwFileTransfer_PENDING
file transfer is opening
Definition mw_srvc_ft.h:58

◆ mwFileTransfer_isState

#define mwFileTransfer_isState ( ft,
state )
Value:
(mwFileTransfer_getState(ft) == (state))
enum mwFileTransferState mwFileTransfer_getState(struct mwFileTransfer *ft)
the status of this file transfer

◆ mwFileTransfer_reject

#define mwFileTransfer_reject ( ft)
Value:
@ mwFileTransfer_REJECTED
Definition mw_srvc_ft.h:92

reject an incoming file transfer

◆ mwService_FILE_TRANSFER

#define mwService_FILE_TRANSFER   0x00000038

Enumeration Type Documentation

◆ mwFileTranferCode

Enumerator
mwFileTransfer_SUCCESS 
mwFileTransfer_REJECTED 

◆ mwFileTransferState

Enumerator
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

Function Documentation

◆ mwFileTransfer_accept()

int mwFileTransfer_accept ( struct mwFileTransfer * ft)

accept an incoming file transfer

◆ mwFileTransfer_ack()

int mwFileTransfer_ack ( struct mwFileTransfer * ft)

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.

See also
mwFileTransferHandler::ft_recv

◆ mwFileTransfer_close()

int mwFileTransfer_close ( struct mwFileTransfer * ft,
guint32 code )

Close a file transfer.

This will trigger the ft_close function of the session's handler.

See also
mwFileTransfer_reject
mwFileTransfer_cancel

◆ mwFileTransfer_free()

void mwFileTransfer_free ( struct mwFileTransfer * ft)

deallocate a file transfer.

will call mwFileTransfer_close if necessary

◆ mwFileTransfer_getClientData()

gpointer mwFileTransfer_getClientData ( struct mwFileTransfer * ft)

◆ mwFileTransfer_getFileName()

const char * mwFileTransfer_getFileName ( struct mwFileTransfer * ft)

the publicized file name.

Not necessarily related to any actual file on either system

◆ mwFileTransfer_getFileSize()

guint32 mwFileTransfer_getFileSize ( struct mwFileTransfer * ft)

total bytes intended to be sent/received

◆ mwFileTransfer_getMessage()

const char * mwFileTransfer_getMessage ( struct mwFileTransfer * ft)

the message sent along with an offered file transfer

◆ mwFileTransfer_getRemaining()

guint32 mwFileTransfer_getRemaining ( struct mwFileTransfer * ft)

bytes remaining to be received/send

◆ mwFileTransfer_getService()

struct mwServiceFileTransfer * mwFileTransfer_getService ( struct mwFileTransfer * ft)

◆ mwFileTransfer_getState()

enum mwFileTransferState mwFileTransfer_getState ( struct mwFileTransfer * ft)

the status of this file transfer

◆ mwFileTransfer_getUser()

const struct mwIdBlock * mwFileTransfer_getUser ( struct mwFileTransfer * ft)

the user on the other end of the file transfer

◆ mwFileTransfer_new()

struct mwFileTransfer * mwFileTransfer_new ( struct mwServiceFileTransfer * srvc,
const struct mwIdBlock * who,
const char * msg,
const char * filename,
guint32 filesize )

◆ mwFileTransfer_offer()

int mwFileTransfer_offer ( struct mwFileTransfer * ft)

initiate an outgoing file transfer

◆ mwFileTransfer_removeClientData()

void mwFileTransfer_removeClientData ( struct mwFileTransfer * ft)

◆ mwFileTransfer_send()

int mwFileTransfer_send ( struct mwFileTransfer * ft,
struct mwOpaque * data )

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.

See also
mwFileTransferHandler::ft_ack

◆ mwFileTransfer_setClientData()

void mwFileTransfer_setClientData ( struct mwFileTransfer * ft,
gpointer data,
GDestroyNotify clean )

◆ mwServiceFileTransfer_getHandler()

struct mwFileTransferHandler * mwServiceFileTransfer_getHandler ( struct mwServiceFileTransfer * srvc)

◆ mwServiceFileTransfer_getTransfers()

const GList * mwServiceFileTransfer_getTransfers ( struct mwServiceFileTransfer * srvc)

◆ mwServiceFileTransfer_new()

struct mwServiceFileTransfer * mwServiceFileTransfer_new ( struct mwSession * session,
struct mwFileTransferHandler * handler )