gsoc:2009:api

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision		Previous revision
gsoc:2009:api [2009/06/03 05:19] – vpjgsoc:2009:api [2017/09/22 13:28] (current) – external edit 127.0.0.1
Line 13: Line 13:
  
 ===== Documentation ===== ===== Documentation =====
 +
 +==== Versioning ====
 +Versions are in the format major.minor[.build[.revision]] in the string representation. These are stored in unsigned integers for ease of searching. The first 8 bits are used for the major, next 8 for the minor, next 8 for the build and the last 8 bits for the revision. It is possible to convert from the string representation to an unsigned integer using zend_eapi_toi and from an unsigned integer to the string format using zend_eapi_toa function.
 +
 +==== Macros ====
 +
 +<code c>
 +EAPI_SET_CALLBACK(ext_name, version, callback) 
 +</code>
 +Sets a callback - with reference to a extension and a version - should be called during MINIT. The callback will be called after all extensions have been initialized. Callback will be called with a reference to the API of the specified extension. See zend_eapi_set_callback.
 +^ ''ext_name'' | Extension name |
 +^ ''version'' | Version - if a null value will is passed the callback will be called with the latest version |
 +^ ''callback'' | Function pointer to the callback function |
 +
 +<code c>
 +EAPI_SET_EMPTY_CALLBACK(callback) 
 +</code>
 +Sets an empty callback - should be called during MINIT. The callback will be called after all extensions have been initialized. See zend_eapi_set_empty_callback.
 +^ ''callback'' | Function pointer to the callback function |
 +
 +<code c>
 +EAPI_CALLBACK_FUNCTION(callback) 
 +</code>
 +Defines the callback function. The callback function will be called with the following parameters: type, module_number, api (pointer to the api), ext_name, version,
 +^ ''callback'' | Name of the callback function |
 +
 +<code c>
 +EAPI_EMPTY_CALLBACK_FUNCTION(callback) 
 +</code>
 +Defines the empty callback function. The callback function will be called with the following parameters: typei and module_number,
 +^ ''callback'' | Name of the callback function |
 +
 ==== Functions ==== ==== Functions ====
 +All functions return ''SUCCESS'' on success and ''FAILURE'' on failure.
 +
 <code c> <code c>
-int zend_ext_api_register(char *ext_name, char *version, void *api)+int zend_eapi_register(char *ext_name, char * version_text, void *api, size_t size)
 </code> </code>
 Registers an API Registers an API
Line 21: Line 55:
 ^ ''version'' | API version in format major.minor[.build[.revision]] | ^ ''version'' | API version in format major.minor[.build[.revision]] |
 ^ ''api''    | A ponter to the API structure | ^ ''api''    | A ponter to the API structure |
 +^ ''size''    | Size of the API structure |
 +
 +<code c>
 +int zend_eapi_version_toi(char *version_text, uint *version_int)
 +</code>
 +Converts a version in text format to an integer.
 +^ ''version_text'' | Version as a string |
 +^ ''version_int'' | Version as a numerical value |
 +
 +<code c>
 +int zend_eapi_version_toa(uint version, char * version_text)
 +</code>
 +Converts a version in integer format to a string
 +^ ''version_text'' | Version as a string |
 +^ ''version_int'' | Version as a numerical value |
 +
 +<code c>
 +int zend_eapi_find_versions(char *ext_name, uint version, uint mask, uint *result, int *size, int buf_length)
 +</code>
 +Finds the set of versions available. Matches versions if ''(extension_version & mask) == (version & mask)''.
 +^ ''ext_name'' | Extension name |
 +^ ''version'' | Version to be searched for |
 +^ ''mask'' | A mask to specify which part of version should be matched |
 +^ ''result'' | Pointer to an array, which will be filled with matched versions |
 +^ ''size'' | Number of matches found |
 +^ ''buf_length'' | Capacity of the array results (memory allocated) |
 +
 +<code c>
 +int zend_eapi_get_latest_version(char *ext_name, uint *version)
 +</code>
 +Gives the latest version of the extension available
 +^ ''ext_name'' | Extension name |
 +^ ''version'' | Latest version as a numerical value |
 +
 +<code c>
 +int zend_eapi_exists(char *ext_name, char *version)
 +</code>
 +Checks if the API is available
 +^ ''ext_name'' | Extension name |
 +^ ''version'' | Version |
 +
 +<code c>
 +int zend_eapi_get(char *ext_name, char *version, void **api)
 +</code>
 +Retrieves the API
 +^ ''ext_name'' | Extension name |
 +^ ''version'' | Version |
 +^ ''api'' | API will be loaded here if it is available |
 +
 +<code c>
 +int zend_eapi_set_empty_callback(int type, int module_number, void (*callback)(EMPTY_CALLBACK_FUNC_ARGS))
 +</code>
 +Sets an empty callback - should be called during MINIT. The callback will be called after all extensions have been initialized. Use EAPI_SET_EMPTY_CALLBACK.
 +^ ''callback'' | Function pointer to the callback function |
 +
 +<code c>
 +int zend_eapi_set_callback(int type, int module_number, char *ext_name, char *version, void (*callback_func)(CALLBACK_FUNC_ARGS))
 +</code>
 +Sets a callback - with reference to a extension and a version - should be called during MINIT. The callback will be called after all extensions have been initialized. Callback will be called with a reference to the API of the specified extension. Use EAPI_SET_CALLBACK.
 +^ ''ext_name'' | Extension name |
 +^ ''version'' | Version - if a null value will is passed the callback will be called with the latest version |
 +^ ''callback'' | Function pointer to the callback function |
  
 ===== Timeline ===== ===== Timeline =====
Line 26: Line 122:
 20th April to 23rd May – Community bonding period 20th April to 23rd May – Community bonding period
  
-    * Getting more familiarized with PHP core and Zend +  * Getting more familiarized with PHP core and Zend 
-    * Submitting the proposed API and design for suggestions +  * Submitting the proposed API and design for suggestions 
-    * Getting ideas from the developer community on how this should be developed +  * Getting ideas from the developer community on how this should be developed 
-    * Finalizing the design+  * Finalizing the design
  
 23rd May to 1st July – Implementing most important features 23rd May to 1st July – Implementing most important features
  
-    * The API registration and retrieval component will be developed +  * The API registration and retrieval component will be developed 
-    * The interface for setting up the callback function will not be implemented at this stage, instead a simpler interface (e.g. php_get_api) would be provided +  * The interface for setting up the callback function will not be implemented at this stage, instead a simpler interface (e.g. php_get_api) would be provided 
-    * Code written will be unit tested +  * Code written will be unit tested 
-    * This would be a standard to be distributed for testing+  * This would be a standard to be distributed for testing
  
 1st July to 10th July – Testing the implemented section 1st July to 10th July – Testing the implemented section
  
-    * The implemented features will be tested with help from the community +  * The implemented features will be tested with help from the community 
-    * Any bugs encountered will be fixed +  * Any bugs encountered will be fixed 
-    * Any suggestions for improvements will be considered and implemented+  * Any suggestions for improvements will be considered and implemented
  
 10th July to 1st August – Completing the implementation of all features 10th July to 1st August – Completing the implementation of all features
  
-    * All the functionality described above will be completed +  * All the functionality described above will be completed 
-    * Code written will be unit tested +  * Code written will be unit tested 
-    * Behavior of the component in various scenarios with interdependencies among extensions, will be tested thoroughly+  * Behavior of the component in various scenarios with interdependencies among extensions, will be tested thoroughly
  
 1st August to 4th August – Buffer 1st August to 4th August – Buffer
  
-    * Small buffer period so that any additional things that come up in the way could be implemented or if time taken for implementation exceeds time estimated +  * Small buffer period so that any additional things that come up in the way could be implemented or if time taken for implementation exceeds time estimated 
-    * The completed extension API and dependency interface will be made available for the developer community +  * The completed extension API and dependency interface will be made available for the developer community 
-    * Any improvements suggested will be considered and implemented+  * Any improvements suggested will be considered and implemented
  
 4th August to 17th August – Testing 4th August to 17th August – Testing
  
-    * Any bug fixes will be implemented +  * Any bug fixes will be implemented 
-    * All documentations will be completed +  * All documentations will be completed 
-    * It will be ready for distribution at the end of testing+  * It will be ready for distribution at the end of testing
  
 ===== Progress ===== ===== Progress =====
Line 66: Line 162:
 == 12th May == == 12th May ==
  
-    * Setup the development environment +  * Setup the development environment 
-    * Working on the GIT repository - [[git://github.com/vpj/PHP-Extension-API.git]] +  * Working on the GIT repository - [[git://github.com/vpj/PHP-Extension-API.git]] 
-    * Made a few changes to the proposed design +  * Made a few changes to the proposed design 
-      - All the code will be a part of zend and hence all function will be prefixed with zend_ and not php_ +    * All the code will be a part of zend and hence all function will be prefixed with zend_ and not php_ 
-      - Prefixed all the functions with zend_ext_api instead of function names like php_register_api+    * Prefixed all the functions with zend_ext_api instead of function names like php_register_api
  
 == 15th May == == 15th May ==
  
-    * Discussing how different versions of API's should be maintained +  * Discussing how different versions of API's should be maintained 
-    * Coded the basic functionality +  * Coded the basic functionality 
-      - Memory leaks and exception handling were not considered (TODO's were added to make sure these will be addressed later)+    * Memory leaks and exception handling were not considered (TODO's were added to make sure these will be addressed later)
  
 == 23rd May == == 23rd May ==
  
-    * Two hashtables are used - one to store the API's and the other to store the available versions +  * Two hashtables are used - one to store the API's and the other to store the available versions 
-    * A simple list is used to store the set of versions available +  * A simple list is used to store the set of versions available 
-    * Versions are represented in major.minor[.build[.revision]] or major.minor[.maintenance[.build]] formats; i.e. "x.x.x.x" +  * Versions are represented in major.minor[.build[.revision]] or major.minor[.maintenance[.build]] formats; i.e. "x.x.x.x" 
-      - These are converted to a 32 bit integer for indexing +    * These are converted to a 32 bit integer for indexing 
-      - Bit masks could be used to identify ranges of versions easily+    * Bit masks could be used to identify ranges of versions easily
  
 == 31st May == == 31st May ==
  
-    * Included a function to get the latest version of an extension available +  * Included a function to get the latest version of an extension available 
-    * Functions to convert version from major.minor[.build[.revision]] format to an uint and vice versa are provided. +  * Functions to convert version from major.minor[.build[.revision]] format to an uint and vice versa are provided. 
-      - when representing the version in uint first 8 bits will be used for major and the next 8 for minor and so on +    * when representing the version in uint first 8 bits will be used for major and the next 8 for minor and so on 
-    * A few memory leaks were fixed+  * A few memory leaks were fixed 
 + 
 +== 5th June == 
 + 
 +  * Added some documentation of the interface 
 +  * Did some testing 
 + 
 +== 27th June == 
 + 
 +  * Coded the callback registration 
 +    * Callbacks are called from php_module_startup (main/main.c) 
 +    * Tested callbacks 
 +    * Update sample usage code 
 + 
 +== 10th July == 
 + 
 +  * Callbacks 
 +    * Module number is passed to the callback 
 +    * Callbacks can be registered for the latest API version 
 +  * Testing 
 +    * Two extension with a set of standard unit test cases were added to the git repository 
 +    * API interface was tested with the extensions mbstring and exif 
 +  * Name 
 +    * eapi is used instead of ext_api 
 + 
 +== 20th July == 
 +  * Callbacks with no extension specified 
 +  * Used dependency interface on mbstring/exif 
 + 
 +== 31st July == 
 +  * Setting callbacks accept module_number / type (through macros) 
 +  * Callbacks are called with module_number / type. e.g. usage - INIs could be registered from the callback 
 +  * Functions to search versions of an extension 
 +  * Example usage of the dependency interface : [[http://www.xvpj.net/2009/06/26/how-to-use-php-extension-api-dependancy-interface/]] 
 +  * How dependency interface is implemented on mbstring / exif : [[http://www.xvpj.net/2009/07/29/eapi2/]]
  
 +== 16th August ==
 +  * Received some suggestions from the community (mailing list)
 +  * Fixed a problem with win32 build - included zend_eapi.c in config.w32
 +  * TSRMLS parameters are passed to callbacks to improve performance
 +  * Added support for extensions loaded through dl()
 +    * When a extension (say ext_dl) is loaded through dl() the callbacks of other extensions (already loaded) are called, if they require the ext_dl and the versions match
 +    * Callbacks of ext_dl are called if the required extensions are available
 +    * Did some testing with dl()
gsoc/2009/api.1244006396.txt.gz · Last modified: 2017/09/22 13:28 (external edit)

Page Tools