1 /*
2  * Copyright (C) 1995 Advanced RISC Machines Limited. All rights reserved.
3  *
4  * This software may be freely used, copied, modified, and distributed
5  * provided that the above copyright notice is preserved in all copies of the
6  * software.
7  */
8 
9 /* -*-C-*-
10  *
11  * $Revision: 1.3 $
12  *     $Date: 2004/12/27 14:00:54 $
13  *
14  *
15  * msgbuild.h - utilities for assembling and interpreting ADP messages
16  */
17 
18 #ifndef angel_msgbuild_h
19 #define angel_msgbuild_h
20 #include <stdarg.h>
21 #include "channels.h"
22 
23 /*
24  * msgbuild
25  * --------
26  * We use a "varargs" function to enable a description of how the
27  * final message should look to be provided. We use a function rather
28  * than in-line macros to keep the size of Angel small.
29  *
30  * The "buffer" pointer is the starting point from where the data will
31  * be written. Note: If a NULL pointer is passed then no data will be
32  * written, but the size information will be returned. This allows
33  * code to call this routine with a NULL "buffer" pointer to ascertain
34  * whether the pointer they are passing contains enough space for the
35  * message being constructed.
36  *
37  * The "format" string should contain sequences of the following
38  * tokens:
39  *      %w - insert 32bit word value
40  *      %p - insert 32bit target pointer value
41  *      %h - insert 16bit value
42  *      %b - insert 8bit byte value
43  *
44  * The return parameter is the final byte length of the data written.
45  */
46 unsigned int msgbuild(unsigned char *buffer, const char *format, ...);
47 unsigned int vmsgbuild(unsigned char *buffer, const char *format,
48                        va_list args);
49 
50 /*---------------------------------------------------------------------------*/
51 
52 /*
53  * msgsend
54  * -------
55  * As for msgbuild except that it allocates a buffer, formats the data as
56  * for msgbuild and transmits the packet. Returns 0 if successful non 0 if ot
57  * fails.
58  * Not for use on cooked channels e.g. debug channels only.
59  */
60 extern int msgsend(ChannelID chan, const char *format, ...);
61 
62 /*---------------------------------------------------------------------------*/
63 
64 /*
65  * Unpack_message
66  * --------------
67  *    This basically does the opposite of msg_build, it takes a message, and
68  * a scanf type format string (but much cut down functionality) and returns
69  * the arguments in the message.
70  */
71 extern unsigned int unpack_message(unsigned char *buffer, const char *format, ...);
72 
73 #endif /* ndef angel_msgbuild_h */
74 
75 /* EOF msgbuild.h */
76