[ssr] / StraySrc / Libraries / Steel / h / xfersend

/****************************************************************************
 * 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 */
Commit	Line	Data
2ee739cc	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 */