1 | |
---|
2 | WSDL callback API |
---|
3 | ================= |
---|
4 | |
---|
5 | Terminology |
---|
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 | |
---|
21 | Rationale |
---|
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 | |
---|
32 | The 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 | |
---|