WL#2872: Make client library extensible

Make client library extensible so that the structures used in client programs 
never have to change again. This will allow the end user to upgrade shared 
MySQL client library without side effects.

Our include/mysql.h is too sensitive to changes. Most of the outside world uses
it, to compile against our DB. When we change things, those programs break.
In addition, its a bit ugly, and k-nt has some ideas about how to make it play
nicer with other programs, yet still be useful for us(in the way that we can
extend it or change it witohout the API user noticing)

The following Axioms must hold for the new client API:

- Almost all old clients should work with new API after recompilation.
  (Ie, no changes needed for old client code)

- A client should be able to use newer versions of the library without
  recompilation (but will of course not in this case be able to access new
  features).

- A client should be able to use an older version of the library, as long
  he is not using any new function calls that doesn't exist in the older
  library version. (If he us using new functions the shared library loader
  will complain about missing symbols).
  From this follows that if we at some point support any virtual function
  through an object, this function call should NOT crash if you do it
  with an older object that doesn't yet implement the function call.
  (Ie, all virtual function calls needs to be checked against client
  version to see if function call exists).


First, mysql.h should contain exactly and only the public interface that we
documented. We should hide as much as we can about things that the end-user
shouldn't be playing with.
	
This includes the structs, especially, that break ABI compatibility three times
this year so far. :(

We are going to do this in two steps:

First, add a 'void *extend' pointer to all public struct that may change.
All new fields that are needed should be allocated and accessed through this struct.

We can't change the fields for most of the current struct, including MYSQL, as
people are already using part of these.

This change will happen in 5.1 (The shared library version of the client library
needs to be updated)

------------------------

The main idea is to change struct st_mysql to "typedef void* MYSQL"
It would allow us to hide everything except that. You declare a MYSQL variable
and then call mysql_init on that variable. Inside mysql_init, we allocate the
memory we need for that struct and maybe other things
	
Currently it's a #typedef struct { ...big... } MYSQL
And now we put it all except the pointer on the heap instead of the stack.
	
Some programs have things like "MYSQL mysql; mysql_init(&mysql)" and we should
not break that.	
	
The alternative to void* is "typedef struct { void* impl; ..a few more variables
?.. } MYSQL"

Where "impl" is the pointer to the data that we can extend as we wish (like the
current struct several times so far
	
But unless we put any other variables in the MYSQL struct that is exactly the
same as void*
We don't see a reason to add variables, so far.

mysql_close will free the memory allocated by mysql_init

The new libraries will have a higher SHARED_LIBRARY_MAJOR_VERSION

magnus, I mean useful to us in that we can extend the newly-hidden struct it as
we please and the users can't notice.
	

There are also a number of other structs in the file. For example
"st_mysql_field", if we wan't to hide that we need to also implement some new
functions to get and set the variables of that struct. And that one explicigtgly
will probably have to be kept like it is as users are already peeking into the
FIELD structs.


There should probably also be a mysql_embed.h, many of the structs in mysql.h
are there because of embedded server.



Common clone:
bk-internal:/home/bk/mysql-5.1-maint-wl2872 created

As discussed on "#maintenence 2006-10-31 14:58:15  Our include/mysql.h is
too sensitive to changes. Most of the outside world uses it, to compile against
our DB." https://intranet.mysql.com/secure/apps/irclog.php?channel=40