xfersend

/* Copyright 1996 Acorn Computers Ltd
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
/****************************************************************************
 * 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.                         *
 *                                                                          *
 ***************************************************************************/

/* 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_print ----------------------------
 * Description:   Starts the file transfer protocol to the printer driver
 *                  (if one is loaded)
 *
 * Parameters:    int filetype -- type of file to print
 *                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 required
 *                void *handle -- handle to be passed to handler functions.
 *
 * Returns:       TRUE if data queued successfully.
 *
 * Other Info:    Call this function if you want to print something as the
 *                result of an action of the user. Xfersend_print() deals
 *                with the complexities of message-passing protocols to
 *                achieve the data transfer. There are two possibilities:
 *                (j) The data is queued by the printer manager for later
 *                printing - you will get a Message_PrintTypeOdd when it
 *                wants the printing to be done; or (ij) the printer driver
 *                demands instant printing, or is not loaded: then this
 *                function will call the xfersend_printproc to print the
 *                data immediately. Refer to the above typedefs for an
 *                explanation of what the two 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 psss 0 as the printproc, it is assumed that you
 *                cannot print the file yourself. The printer manager will copy
 *                the file and try to print it using the normal protocol.
 *                   The estimated file size is not essential, but may
 *                improve performance.
 */

BOOL xfersend_print (int filetype, char *name, int estsize,
   xfersend_saveproc, xfersend_sendproc, xfersend_printproc, void *handle);

/* ----------------------------- xfersend_pipe -----------------------------
 * Description:   Allows the user to export application data, without an
 *                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
 *                void *handle -- handle to be passed to handler functions.
 *                wimp_t task  -  handle of task to pass data to.
 * Returns:       TRUE if data exported successfully.
 * Other Info:    This function works similarly to xfersend, except it is
 *                not normally used as the result of an icon drag.
 *                Typical use may be to export data to another application
 *                (using the same technique as xfersend), following a
 *                request for data from that application (maybe as a result
 *                of receiving an application-specific wimp message).
 *
 */

BOOL xfersend_pipe(int filetype, char *name, int estsize,
                   xfersend_saveproc, xfersend_sendproc, xfersend_printproc,
                   void *handle, wimp_t task);


/* ------------------------ 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);

/* --------------------------- xfersend_close_on_xfer ----------------------
 * Description:   Tells xfersend whether to close "parent" window after
 *                icon-drag export.
 *
 * Parameters:    BOOL do_we_close -- TRUE means close window after export.
 *                wimp_w w -- handle of window to close (presumably "parent"
 *                            window.
 * Returns:       void.
 * Other Info:    The default is to not close the window after export.
 *                Once used, this function should be called before each
 *                call to xfersend().
 *
 */

void xfersend_close_on_xfer(BOOL do_we_close, wimp_w w);


/* --------------------------- xfersend_clear_unknowns ----------------------
 * Description:   Removes any unknown event processors registered by xfersend
 *                or xfersend_pipe.
 *
 * Parameters:    void.
 * Returns:       void.
 * Other Info:    xfersend and xfersend_pipe use unknown event processors to
 *                deal with inter-application data transfer.  These may be
 *                left around after completion of the transfer (especially if
 *                the transfer failed).  This function should be called when it
 *                is known that the transfer has ended.
 *
 */

void xfersend_clear_unknowns(void);


/* --------------------------- xfersend_read_last_ref -----------------------
 * Description:   Returns the my_ref value of the last wimp_MDATASAVE or
 *                wimp_MDATALOAD message sent by xfersend or xfersend_pipe.
 *
 * Parameters:    void.
 * Returns:       integer message reference
 * Other Info:    After saving a file to another application (ie. where the
 *                resulting file is not 'safe', the my_ref value of the
 *                final wimp_MDATALOAD should be stored with the document
 *                data, so that if a wimp_MDATASAVED is received, the
 *                document can be marked unmodified.  If the document is
 *                modified after being saved, the last_ref value should be
 *                reset to 0, so that a subsequent wimp_MDATASAVED message
 *                will not cause the document to be marked unmodified.
 *                NB: If RAM transfer is used, the my_ref of the datasave
 *                message should be stored instead.
 */

int xfersend_read_last_ref(void);

#endif

/* end xfersend.h */