Support IPv6

Author: chrislim2888

Developers_Guide.txt

@@ -1,62 +1,75 @@
-Developers guide for IP2Location C API's
-======================================
+Developers' Guide for IP2Location C Library
+===========================================
+
+This guide explains the usage and the behavior of the below functions in the IP2Location C library 
 
-This guide explains the usage and the behavior of below functions in IP2Location C library 
 (1) IP2Location_open_mem
 (2) IP2Location_close
 (3) IP2Location_delete_shm
 
-Important enum, 
-enum IP2Location_mem_type
-{
+Enumeration in IP2Location C Library
+------------------------------------
+enum IP2Location_mem_type {
     IP2LOCATION_FILE_IO,
     IP2LOCATION_CACHE_MEMORY,
     IP2LOCATION_SHARED_MEMORY
 };
 
-========
-(1) int IP2Location_open_mem(IP2Location *loc, enum IP2Location_mem_type);
+Functions in IP2Location C Library
+-----------------------------------
+Function (1) 
+
+   int IP2Location_open_mem(IP2Location *loc, enum IP2Location_mem_type);
+
+loc - is of type IP2Location pointer, which is returned by function IP2Location_open. 
+IP2Location_mem_type - is of type IP2Location_mem_type enum. This argument specifies how the iplocation DB file will be loaded. It may be  IP2LOCATION_FILE_IO, IP2LOCATION_CACHE_MEMORY and  IP2LOCATION_SHARED_MEMORY. 
+
+If IP2LOCATION_FILE_IO is passed as argument, records will be searched directly from the DB file on the hard disk.
+If IP2LOCATION_CACHE_MEMORY is passed as argument, ip2location DB will be loaded into the memory and search will be performed on the DB present in the memory.
+If IP2LOCATION_SHARED_MEMORY is passed as argument, ip2location DB will be loaded into the memory and it will be shared across multiple processes. Please check at the end of this guide to know how this memory is shared and how to release the resource when it's no longer needed.
+
+IP2Location_open_mem call must always be paired with a call to IP2Location_close; if IP2Location_open_mem is called more than once without calling IP2Location_close(), -1 will be returned.
+
+RETURN value:
+For any error IP2Location_open_mem will return -1, and will not set any errno variable.
+
 
- loc - is of type IP2Location pointer, which is returned by function IP2Location_open. 
- IP2Location_mem_type - is of type IP2Location_mem_type enum. This argument specifies to where the iplocation DB file will be loaded. It may be  IP2LOCATION_FILE_IO, IP2LOCATION_CACHE_MEMORY and  IP2LOCATION_SHARED_MEMORY. 
+Function (2)
 
- If IP2LOCATION_FILE_IO is passed as agrument, DB will be in the hard disk file and records will be searched from the hard disk file.
- If IP2LOCATION_CACHE_MEMORY is passed as argument, ip2location DB will be loaded into the memory and search will be performed on the DB present in the memory.
- If IP2LOCATION_SHARED_MEMORY is passed as argument, ip2location DB will be loaded into the memory and it could be shared across multiple processes. Please check at the end of this guide to know how this memory is shared and how to clean it.
+   uint32_t IP2Location_close(IP2Location *loc); 
 
- IP2Location_open_mem call must always be alternated with IP2Location_close, if IP2Location_open_mem is called more than once without calling IP2Location_close(), -1 will be returned.
+loc - is of type  IP2Location pointer, which is returned by function IP2Location_open and it must be one used in IP2Location_open_mem. 
 
- RETURN value:
- For any error IP2Location_open_mem will return -1, and will not set any errno variable.
+Calling this function will close the DB file and free the allocated cache memory or detach from the shared memory. (Shared memory will not be deleted from this call.)
 
-=========
- (2) uint32_t IP2Location_close(IP2Location *loc); 
- loc - is of type  IP2Location pointer, which is returned by function IP2Location_open and it must be one used in IP2Location_open_mem. 
+RETURN value:
+This function always return zero.
 
- Call to this function will close the DB file and free the allocated cache memory or detach from the shared memory. (Shared memory will not be deleted from this call.)
 
- RETURN value:
-	This function always return zero.
+Function (3)
 
-=========
- (3) void IP2Location_delete_shm();
- 
- This function will delete the shared memory created from IP2Location_open_mem in Linux, Unix and MAC OS. In windows its just a empty function call. Please read the next section.
- RETURN value:
-	void
-=========
- Note: Key used for the shared memory is "/IP2location_Shm", please make sure it will not conflict with any other shared memory.
- 
- IP2LOCATION_SHARED_MEMORY – If IP2Location_open_mem is called with this as second argument, shared memory will be created if do not exist already or will attached to already existing shared memeoy. 
+   void IP2Location_delete_shm();
+
+This function will delete the shared memory created from IP2Location_open_mem in Linux, Unix and MAC OS. In Windows, it's just an empty function call. Please read the next section.
+
+RETURN value:
+void
+
+Note: Key used for the shared memory is "/IP2location_Shm", please make sure it does not conflict with any other shared memory.
+
+IP2LOCATION_SHARED_MEMORY – If IP2Location_open_mem is called with this as the second argument, shared memory will be created if it does not already exists else the existing shared memory will be read instead. 
 
 In Windows: 
-If calling process of IP2Location_close function is the only attached process of the shared memory, call to IP2Location_close, along with closing the DB file and detaching from the shared memory it will delete the shared memory. If this is not the last process attached to the shared memory it will just detach from the shared memory.
-Call to IP2Location_delete_shm in windows have not effect. 
+Whenever the IP2Location_close() function is called by the sole process attached to the shared memory, then the DB file will be closed and the shared memory will be deleted.
+If there are other processes attached to the shared memory, then the caller process will just detach itself from the shared memory while leaving the shared memory intact.
+Call to IP2Location_delete_shm in Windows have no effect as Windows does not support shared memory. 
+
+In Linux, Unix and MacOS:
+Call to IP2Location_close will not deleted the shared memory, it will only detach the process from using that memory. To delete the shared memory IP2Location_delete_shm() must be called. 
+
+When IP2Location_delete_shm() function is called, and if any other process(es) is attached to shared memory, it will only delete the name of the shared memory but the other process(es) will continue to use memory and memory will be freed only after last attached process is detached from it. 
 
-In Linux, Unix and MAC OS:
-Call to IP2Location_close will not deleted the shared memory, it will only detach the process from using that memory. To delete the shared memory IP2Location_delete_shm must be called. 
+After calling IP2Location_delete_shm(), the next call to IP2Location_open_mem() with IP2LOCATION_SHARED_MEMORY option will result in a new shared memory and will not reuse the old one if one exists and used by any other process. Please refer shm_open and shm_unlink man pages for more info. 
 
- When IP2Location_delete_shm function is called, and if any other process(es) is attached to shared memory, it will only delete the name of the shared memory but the other process(es) will continue to use memory and memory will be freed only after last attached process is detached from it. 
 
- If any process after call to IP2Location_delete_shm, call IP2Location_open_mem again with IP2LOCATION_SHARED_MEMORY option, it will create a new shared memory and will not use the old one if one exists and used by any other process. 
- Please refer shm_open and shm_unlink man pages for more info. 
+Version 7.0.0  05/08/2014