chiark - git - mdw - ssr/blob - StraySrc/Libraries/Steel/h/xfersend

   1 /****************************************************************************
   2  * This source file was written by Acorn Computers Limited. It is part of   *
   3  * the RISCOS library for writing applications in C for RISC OS. It may be  *
   4  * used freely in the creation of programs for Archimedes. It should be     *
   5  * used with Acorn's C Compiler Release 3 or later.                         *
   6  *                                                                          *
   7  ***************************************************************************/
   8
   9 /*----- Licensing note ----------------------------------------------------*
  10  *
  11  * This file is part of Straylight's Steel library.
  12  *
  13  * Steel is free software; you can redistribute it and/or modify
  14  * it under the terms of the GNU General Public License as published by
  15  * the Free Software Foundation; either version 2, or (at your option)
  16  * any later version.
  17  *
  18  * Steel is distributed in the hope that it will be useful,
  19  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  20  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  21  * GNU General Public License for more details.
  22  *
  23  * You should have received a copy of the GNU General Public License
  24  * along with Steel.  If not, write to the Free Software Foundation,
  25  * 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
  26  */
  27
  28 /* Title:   xfersend.h
  29  * Purpose: general purpose export of data by dragging icon
  30  *
  31  */
  32
  33 #ifndef __xfersend_h
  34 #define __xfersend_h
  35
  36 #ifndef BOOL
  37 #define BOOL int
  38 #define TRUE 1
  39 #define FALSE 0
  40 #endif
  41
  42 #ifndef __wimp_h
  43 #include "wimp.h"
  44 #endif
  45
  46
  47 /******************* CALLER-SUPPLIED FUNCTION TYPES ************************/
  48
  49 /* ------------------------ xfersend_saveproc ------------------------------
  50  * Description:   A function of this type should save to the given file and
  51  *                return TRUE if successful. Handle is passed to the
  52  *                function by xfersend().
  53  *
  54  * Parameters:    char *filename -- file to be saved
  55  *                void *handle -- the handle you passed to xfersend()
  56  * Returns:       The function must return TRUE if save was successful.
  57  * Other Info:    none.
  58  *
  59  */
  60
  61 typedef BOOL (*xfersend_saveproc)(char *filename, void *handle);
  62
  63
  64 /* ----------------------- xfersend_sendproc -------------------------------
  65  * Description:   A function of this type should call xfersend_sendbuf()
  66  *                to send one "buffer-full" of data no bigger than
  67  *                *maxbuf.
  68  *
  69  * Parameters:    void *handle -- handle which was passed to xfersend
  70  *                int *maxbuf -- size of receiver's buffer
  71  * Returns:       The function must return TRUE if data was successfully
  72  *                transmitted.
  73  * Other Info:    Note: Your sendproc will be called by functions in the
  74  *                xfersend module to do an in-core data transfer, on
  75  *                receipt of MRAMFetch messages from the receiving
  76  *                application. If xfersend_sendbuf() returns FALSE, then
  77  *                return FALSE **IMMEDIATELY**.
  78  *
  79  */
  80
  81 typedef BOOL (*xfersend_sendproc)(void *handle, int *maxbuf);
  82
  83
  84 /* --------------------------- xfersend_printproc --------------------------
  85  * Description:   A function of this type should either print the file
  86  *                directly, or save it into the given filename, from
  87  *                where it will be printed by the printer application.
  88  *
  89  * Parameters:    char *filename -- file to save into, for printing
  90  *                void *handle -- handle that was passed to xfersend()
  91  * Returns:       The function should return either the file type of the
  92  *                file it saved, or one of the reason codes #defined below.
  93  *
  94  * Other Info:    This is called if the file icon has been dragged onto a
  95  *                printer application.
  96  *
  97  */
  98
  99 typedef int (*xfersend_printproc)(char *filename, void *handle);
 100
 101 #define xfersend_printPrinted -1    /* file dealt with internally */
 102 #define xfersend_printFailed  -2    /* had an error along the way */
 103
 104 /* The saveproc should report any errors it encounters itself. If saving
 105    to a file, it should convert the data into a type that can be printed by
 106    the printer application (i.e. text). */
 107
 108
 109 /*************************** LIBRARY FUNCTIONS *****************************/
 110
 111
 112 /* ----------------------------- xfersend ----------------------------------
 113  * Description:   Allows the user to export application data, by icon drag.
 114  *
 115  * Parameters:    int filetype -- type of file to save to
 116  *                char *name -- suggested file name
 117  *                int estsize -- estimated size of the file
 118  *                xfersend_saveproc -- caller-supplied function for saving
 119  *                                     application data to a file
 120  *                xfersend_sendproc -- caller-supplied function for in-core
 121  *                                     data transfer (if application is able
 122  *                                     to do this)
 123  *                xfersend_printproc -- caller-supplied function for printing
 124  *                                      application data, if "icon" is
 125  *                                      dragged onto printer application
 126  *                wimp_eventstr *e --  the event which started the export
 127  *                                     (usually mouse drag)
 128  *                void *handle -- handle to be passed to handler functions.
 129  * Returns:       TRUE if data exported successfully.
 130  * Other Info:    You should typically call this function in a window's
 131  *                event handler, when you get a "mouse drag" event.
 132  *                See the "saveas.c" code for an example of this.
 133  *                xfersend deals with the complexities of message-passing
 134  *                protocols to achieve the data transfer. Refer to the above
 135  *                typedefs for an explanation of what the three
 136  *                caller-supplied functions should do.
 137  *                If "name" is 0 then a default name of "Selection" is
 138  *                supplied.
 139  *                If you pass 0 as the xfersend_sendproc, then no in-core
 140  *                data transfer will be attempted
 141  *                If you pass 0 as the xfersend_printproc, then the file
 142  *                format for printing is assumed to be the same as for saving
 143  *                The estimated file size is not essential, but may improve
 144  *                performance.
 145  *
 146  */
 147
 148 BOOL xfersend(int filetype, char *name, int estsize,
 149               xfersend_saveproc, xfersend_sendproc, xfersend_printproc,
 150               wimp_eventstr *e, void *handle);
 151
 152
 153 /* ------------------------ xfersend_sendbuf -------------------------------
 154  * Description:   Sends the given buffer to a receiver.
 155  *
 156  * Parameters:    char *buffer -- the buffer to be sent
 157  *                int size -- the number of characters placed in the buffer
 158  * Returns:       TRUE if send was successful.
 159  * Other Info:    This function should be called by the caller-supplied
 160  *                xfersend_sendproc (if such exists) to do in-core data
 161  *                transfer (see notes on xfersend_sendproc above).
 162  *
 163  */
 164
 165 BOOL xfersend_sendbuf(char *buffer, int size);
 166
 167
 168 /* ------------------------ xfersend_file_is_safe --------------------------
 169  * Description:   Informs caller if the file's name can be reliably assumed
 170  *                not to change (during data transfer!!)
 171  *
 172  * Parameters:    void
 173  * Returns:       TRUE if file is "safe".
 174  * Other Info:    See also the xferrecv module.
 175  *
 176  */
 177
 178 BOOL xfersend_file_is_safe(void) ;
 179
 180 /* Returns TRUE if file recipient will not modify it; changing the
 181    window title of the file can be done conditionally on this result. This
 182    can be called within your xfersend_saveproc,sendproc, or printproc,
 183    or immediately after the main xfersend. */
 184
 185 /* ---------------------------- xfersend_set_fileissafe --------------------
 186  * Description:   Allows caller to set an indication of whether a file's
 187  *                name will remain unchanged during data transfer.
 188  *
 189  * Parameters:    BOOL value -- TRUE means file is safe.
 190  * Returns:       void.
 191  * Other Info:    none.
 192  *
 193  */
 194
 195 void xfersend_set_fileissafe(BOOL value);
 196
 197 /*
 198  * void xfersend_close_on_xfer(BOOL closeIt,wimp_w window)
 199  *
 200  * Use
 201  *  Tells xfersend whether you want to close a window (say a save dbox) after the
 202  *  data transfer.  If you do, you have to specify the window as well.  This isn't
 203  *  my architecture, this is just a header for a function that Acorn didn't header,
 204  *  but this may be useful to people who want to call xfersend direct, not through
 205  *  saveas.
 206  *
 207  * Parameters
 208  *  BOOL closeIt == if you want to close a window.
 209  *  wimp_w window == the window to close.
 210  */
 211
 212 void xfersend_close_on_xfer(BOOL closeIt,wimp_w window);
 213
 214 /*
 215  * BOOL xfersend_sendBlock(void *block,size_t length,int *maxbuf)
 216  *
 217  * Use
 218  *  Sends a block to xfersend_sendbuf() a chunk at a time.
 219  *
 220  * Parameters
 221  *  void *block == pointer to the block
 222  *  size_t length == length of block
 223  *  int *maxbuf == pointer to the length of the destination task's buffer
 224  *
 225  * Returns
 226  *  TRUE if successful, FALSE if it failed.  If this returns FALSE, you must
 227  *  return FALSE immediately.
 228  */
 229
 230 BOOL xfersend_sendBlock(void *block,int length,int *maxbuf);
 231
 232 #endif
 233
 234 /* end xfersend.h */