Fix documentation of avahi_{entry_group|client}_new(): clarify that the specified...

git-svn-id: file:///home/lennart/svn/public/avahi/trunk@1359 941a03a8-eaeb-0310-b9a0-b1bbd8fe43fe

diff --git a/avahi-client/client.h b/avahi-client/client.h
index f102f05934b3d55f32aebb85b7728ae41767b003..6a12e9a2de12726e14f5563cab239cfd8131090f 100644 (file)
--- a/avahi-client/client.h
+++ b/avahi-client/client.h
@@ -62,7 +62,7 @@ typedef void (*AvahiClientCallback) (
 AvahiClient* avahi_client_new (
     const AvahiPoll *poll_api /**< The abstract event loop API to use */,
     AvahiClientFlags flags /**< Some flags to modify the behaviour of  the client library */,
-    AvahiClientCallback callback /**< A callback that is called whenever the state of the client changes. This may be NULL */,
+    AvahiClientCallback callback /**< A callback that is called whenever the state of the client changes. This may be NULL. Please note that this function is called for the first time from within the avahi_client_new() context! Thus, in the callback you should not make use of global variables that are initialized only after your call to avahi_client_new(). A common mistake is to store the AvahiClient pointer returned by avahi_client_new() in a global variable and assume that this global variable already contains the valid pointer when the callback is called for the first time. A work-around for this is to always use the AvahiClient pointer passed to the callback function instead of the global pointer.  */,
     void *userdata /**< Some arbitrary user data pointer that will be passed to the callback function */,
     int *error /**< If creation of the client fails, this integer will contain the error cause. May be NULL if you aren't interested in the reason why avahi_client_new() failed. */);
 

diff --git a/avahi-client/publish.h b/avahi-client/publish.h
index 053ea8885e1b7b02522e625c58305840f223714a..98f4f9850a79269d41520db81d1d1133dc1f323a 100644 (file)
--- a/avahi-client/publish.h
+++ b/avahi-client/publish.h
@@ -53,7 +53,7 @@ typedef void (*AvahiEntryGroupCallback) (
 /** Create a new AvahiEntryGroup object */
 AvahiEntryGroup* avahi_entry_group_new(
     AvahiClient* c,
-    AvahiEntryGroupCallback callback /**< This callback is called whenever the state of this entry group changes. May not be NULL. */,
+    AvahiEntryGroupCallback callback /**< This callback is called whenever the state of this entry group changes. May not be NULL. Please note that this function is called for the first time from within the avahi_entry_group_new() context! Thus, in the callback you should not make use of global variables that are initialized only after your call to avahi_entry_group_new(). A common mistake is to store the AvahiEntryGroup pointer returned by avahi_entry_group_new() in a global variable and assume that this global variable already contains the valid pointer when the callback is called for the first time. A work-around for this is to always use the AvahiEntryGroup pointer passed to the callback function instead of the global pointer. */,
     void *userdata /**< This arbitrary user data pointer will be passed to the callback functon */);
 
 /** Clean up and free an AvahiEntryGroup object */