source: trunk/third/soup/docs/wsdl-C-api @ 18149

Revision 18149, 3.8 KB checked in by ghudson, 22 years ago (diff)
This commit was generated by cvs2svn to compensate for changes in r18148, which included commits to RCS files with non-trunk default branches.
Line 
1
2WSDL callback API
3=================
4
5Terminology
6-----------
7
8        Application: the client or server as a whole.
9        Client: the process making a SOAP request.
10        Input parameter: a parameter listed as an input element in a
11                WSDL operation definition, which is sent from a client
12                to a server.
13        Output parameter: a parameter listed as an output element in a
14                WSDL operation definition, which is sent from a server
15                to a client.
16        Server: the process responding to a SOAP request.
17        Skeleton: the generated code linked into a server.
18        Stub: the generated code linked into a client.
19
20
21Rationale
22---------
23
24        I want to keep the "who owns the allocated memory" problem
25        simple.  The basic rule of thumb is "The application owns all
26        memory, even if it has been allocated by the generated code."
27        There is one exception, which is that output parameters are
28        allocated by the application in the server callback, and freed
29        by the generated server skeleton.
30
31
32The rules in detail
33-------------------
34
35        For stubs input parameters:
36
37                Numerical types (int, float etc) are passed as-is.
38
39                Strings are passed as guchar *, and owned by the
40                client.
41
42                Structs are passed as struct foo *, and owned by the
43                client.
44
45                Lists are passed as GSList * and owned by the client.
46                The contents point to memory owned by the client.
47
48        For synchronous stubs output parameters:
49
50                Numerical types are passed as pointers to memory owned
51                by the client.
52
53                Strings are passed as guchar **, and are assumed to be
54                not pointing to any allocated memory. The stubs will
55                allocate memory for the returned string and assign the
56                pointed-to pointer to this memory. This memory becomes
57                the responsibility of the client.
58       
59                Structs are passed as struct foo **, and are assumed
60                to be not pointing to any allocated memory. The stubs
61                allocate space for the returned struct and assign the
62                pointed-to pointer to this memory. This memory becomes
63                the responsibility of the client.
64
65                Lists are passed as GSList **, and are assumed to be
66                not pointing to any allocated memory. The stubs
67                allocate space for the contents and assign the
68                pointed-to pointer to this memory. This memory becomes
69                the responsibility of the client.
70
71        For asynchronous stubs callbacks:
72
73                Numerical types are passed as-is.
74
75                Strings are passed as guchar *, pointing to space
76                allocated by the stubs, and become the responsibility
77                of the client.
78
79                Structs are passed as struct foo *, pointing to space
80                allocated by the stubs, and become the responsibility
81                of the client.
82
83                Lists are passed as GSList *, with contents pointing
84                to space allocated by the stubs, and become the
85                responsibility of the client.
86
87        For skeleton input parameters:
88
89                Numerical types are passed as-is.
90
91                Strings are passed as guchar *, pointing to space
92                allocated by the skeleton, and become the
93                responsibility of the server.
94
95                Structs are passed as struct foo *, pointing to space
96                allocated by the skeleton, and become the
97                responsibility of the server.
98
99                Lists are passed as GSList *, with contents pointing
100                to space allocated by the skeleton, and become the
101                responsibility of the server.
102
103        For skeleton output parameters:
104
105                Numerical types are passed as pointers to memory owned
106                by the skeleton.
107
108                Strings are passed as guchar **. The server will
109                allocate memory for the string and assign the
110                pointed-to pointer to this memory. This memory will be
111                freed by the skeleton at some time in the future.
112
113                Structs are passed as struct foo **. The server will
114                allocate memory for the struct and assign the
115                pointed-to pointer to this memory. This memory will be
116                freed by the skeleton at some time in the future.
117
118                Lists are passed as GSList **. The server will
119                allocate memory for the list contents and assign the
120                pointed-to pointer to this memory. This memory will be
121                freed by the skeleton at some time in the future.
122
123
Note: See TracBrowser for help on using the repository browser.