WSDL callback API
=================

Terminology
-----------

	Application: the client or server as a whole.
	Client: the process making a SOAP request.
	Input parameter: a parameter listed as an input element in a
		WSDL operation definition, which is sent from a client
		to a server.
	Output parameter: a parameter listed as an output element in a
		WSDL operation definition, which is sent from a server
		to a client.
	Server: the process responding to a SOAP request.
	Skeleton: the generated code linked into a server.
	Stub: the generated code linked into a client.


Rationale
---------

	I want to keep the "who owns the allocated memory" problem
	simple.  The basic rule of thumb is "The application owns all
	memory, even if it has been allocated by the generated code."
	There is one exception, which is that output parameters are
	allocated by the application in the server callback, and freed
	by the generated server skeleton.


The rules in detail
-------------------

	For stubs input parameters:

		Numerical types (int, float etc) are passed as-is.

		Strings are passed as guchar *, and owned by the
		client.

		Structs are passed as struct foo *, and owned by the
		client.

		Lists are passed as GSList * and owned by the client.
		The contents point to memory owned by the client.

	For synchronous stubs output parameters:

		Numerical types are passed as pointers to memory owned
		by the client.

		Strings are passed as guchar **, and are assumed to be
		not pointing to any allocated memory. The stubs will
		allocate memory for the returned string and assign the
		pointed-to pointer to this memory. This memory becomes
		the responsibility of the client.
	
		Structs are passed as struct foo **, and are assumed
		to be not pointing to any allocated memory. The stubs
		allocate space for the returned struct and assign the
		pointed-to pointer to this memory. This memory becomes
		the responsibility of the client.

		Lists are passed as GSList **, and are assumed to be
		not pointing to any allocated memory. The stubs
		allocate space for the contents and assign the
		pointed-to pointer to this memory. This memory becomes
		the responsibility of the client.

	For asynchronous stubs callbacks:

		Numerical types are passed as-is.

		Strings are passed as guchar *, pointing to space
		allocated by the stubs, and become the responsibility
		of the client.

		Structs are passed as struct foo *, pointing to space
		allocated by the stubs, and become the responsibility
		of the client.

		Lists are passed as GSList *, with contents pointing
		to space allocated by the stubs, and become the
		responsibility of the client.

	For skeleton input parameters:

		Numerical types are passed as-is.

		Strings are passed as guchar *, pointing to space
		allocated by the skeleton, and become the
		responsibility of the server.

		Structs are passed as struct foo *, pointing to space
		allocated by the skeleton, and become the
		responsibility of the server.

		Lists are passed as GSList *, with contents pointing
		to space allocated by the skeleton, and become the
		responsibility of the server.

	For skeleton output parameters:

		Numerical types are passed as pointers to memory owned
		by the skeleton.

		Strings are passed as guchar **. The server will
		allocate memory for the string and assign the
		pointed-to pointer to this memory. This memory will be
		freed by the skeleton at some time in the future.

		Structs are passed as struct foo **. The server will
		allocate memory for the struct and assign the
		pointed-to pointer to this memory. This memory will be
		freed by the skeleton at some time in the future.

		Lists are passed as GSList **. The server will
		allocate memory for the list contents and assign the
		pointed-to pointer to this memory. This memory will be
		freed by the skeleton at some time in the future.