/**************************************************************************** * This source file was written by Acorn Computers Limited. It is part of * * the RISCOS library for writing applications in C for RISC OS. It may be * * used freely in the creation of programs for Archimedes. It should be * * used with Acorn's C Compiler Release 3 or later. * * * ***************************************************************************/ /*----- Licensing note ----------------------------------------------------* * * This file is part of Straylight's Steel library. * * Steel is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2, or (at your option) * any later version. * * Steel 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 General Public License for more details. * * You should have received a copy of the GNU General Public License * along with Steel. If not, write to the Free Software Foundation, * 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */ /* Title: xfersend.h * Purpose: general purpose export of data by dragging icon * */ #ifndef __xfersend_h #define __xfersend_h #ifndef BOOL #define BOOL int #define TRUE 1 #define FALSE 0 #endif #ifndef __wimp_h #include "wimp.h" #endif /******************* CALLER-SUPPLIED FUNCTION TYPES ************************/ /* ------------------------ xfersend_saveproc ------------------------------ * Description: A function of this type should save to the given file and * return TRUE if successful. Handle is passed to the * function by xfersend(). * * Parameters: char *filename -- file to be saved * void *handle -- the handle you passed to xfersend() * Returns: The function must return TRUE if save was successful. * Other Info: none. * */ typedef BOOL (*xfersend_saveproc)(char *filename, void *handle); /* ----------------------- xfersend_sendproc ------------------------------- * Description: A function of this type should call xfersend_sendbuf() * to send one "buffer-full" of data no bigger than * *maxbuf. * * Parameters: void *handle -- handle which was passed to xfersend * int *maxbuf -- size of receiver's buffer * Returns: The function must return TRUE if data was successfully * transmitted. * Other Info: Note: Your sendproc will be called by functions in the * xfersend module to do an in-core data transfer, on * receipt of MRAMFetch messages from the receiving * application. If xfersend_sendbuf() returns FALSE, then * return FALSE **IMMEDIATELY**. * */ typedef BOOL (*xfersend_sendproc)(void *handle, int *maxbuf); /* --------------------------- xfersend_printproc -------------------------- * Description: A function of this type should either print the file * directly, or save it into the given filename, from * where it will be printed by the printer application. * * Parameters: char *filename -- file to save into, for printing * void *handle -- handle that was passed to xfersend() * Returns: The function should return either the file type of the * file it saved, or one of the reason codes #defined below. * * Other Info: This is called if the file icon has been dragged onto a * printer application. * */ typedef int (*xfersend_printproc)(char *filename, void *handle); #define xfersend_printPrinted -1 /* file dealt with internally */ #define xfersend_printFailed -2 /* had an error along the way */ /* The saveproc should report any errors it encounters itself. If saving to a file, it should convert the data into a type that can be printed by the printer application (i.e. text). */ /*************************** LIBRARY FUNCTIONS *****************************/ /* ----------------------------- xfersend ---------------------------------- * Description: Allows the user to export application data, by icon drag. * * Parameters: int filetype -- type of file to save to * char *name -- suggested file name * int estsize -- estimated size of the file * xfersend_saveproc -- caller-supplied function for saving * application data to a file * xfersend_sendproc -- caller-supplied function for in-core * data transfer (if application is able * to do this) * xfersend_printproc -- caller-supplied function for printing * application data, if "icon" is * dragged onto printer application * wimp_eventstr *e -- the event which started the export * (usually mouse drag) * void *handle -- handle to be passed to handler functions. * Returns: TRUE if data exported successfully. * Other Info: You should typically call this function in a window's * event handler, when you get a "mouse drag" event. * See the "saveas.c" code for an example of this. * xfersend deals with the complexities of message-passing * protocols to achieve the data transfer. Refer to the above * typedefs for an explanation of what the three * caller-supplied functions should do. * If "name" is 0 then a default name of "Selection" is * supplied. * If you pass 0 as the xfersend_sendproc, then no in-core * data transfer will be attempted * If you pass 0 as the xfersend_printproc, then the file * format for printing is assumed to be the same as for saving * The estimated file size is not essential, but may improve * performance. * */ BOOL xfersend(int filetype, char *name, int estsize, xfersend_saveproc, xfersend_sendproc, xfersend_printproc, wimp_eventstr *e, void *handle); /* ------------------------ xfersend_sendbuf ------------------------------- * Description: Sends the given buffer to a receiver. * * Parameters: char *buffer -- the buffer to be sent * int size -- the number of characters placed in the buffer * Returns: TRUE if send was successful. * Other Info: This function should be called by the caller-supplied * xfersend_sendproc (if such exists) to do in-core data * transfer (see notes on xfersend_sendproc above). * */ BOOL xfersend_sendbuf(char *buffer, int size); /* ------------------------ xfersend_file_is_safe -------------------------- * Description: Informs caller if the file's name can be reliably assumed * not to change (during data transfer!!) * * Parameters: void * Returns: TRUE if file is "safe". * Other Info: See also the xferrecv module. * */ BOOL xfersend_file_is_safe(void) ; /* Returns TRUE if file recipient will not modify it; changing the window title of the file can be done conditionally on this result. This can be called within your xfersend_saveproc,sendproc, or printproc, or immediately after the main xfersend. */ /* ---------------------------- xfersend_set_fileissafe -------------------- * Description: Allows caller to set an indication of whether a file's * name will remain unchanged during data transfer. * * Parameters: BOOL value -- TRUE means file is safe. * Returns: void. * Other Info: none. * */ void xfersend_set_fileissafe(BOOL value); /* * void xfersend_close_on_xfer(BOOL closeIt,wimp_w window) * * Use * Tells xfersend whether you want to close a window (say a save dbox) after the * data transfer. If you do, you have to specify the window as well. This isn't * my architecture, this is just a header for a function that Acorn didn't header, * but this may be useful to people who want to call xfersend direct, not through * saveas. * * Parameters * BOOL closeIt == if you want to close a window. * wimp_w window == the window to close. */ void xfersend_close_on_xfer(BOOL closeIt,wimp_w window); /* * BOOL xfersend_sendBlock(void *block,size_t length,int *maxbuf) * * Use * Sends a block to xfersend_sendbuf() a chunk at a time. * * Parameters * void *block == pointer to the block * size_t length == length of block * int *maxbuf == pointer to the length of the destination task's buffer * * Returns * TRUE if successful, FALSE if it failed. If this returns FALSE, you must * return FALSE immediately. */ BOOL xfersend_sendBlock(void *block,int length,int *maxbuf); #endif /* end xfersend.h */