{
    "mode": "perldoc",
    "parameter": "XML::LibXML::InputCallback",
    "section": "",
    "url": "https://www.chedong.com/phpMan.php/perldoc/XML%3A%3ALibXML%3A%3AInputCallback/json",
    "generated": "2026-06-10T23:07:31Z",
    "synopsis": "use XML::LibXML;",
    "sections": {
        "NAME": {
            "content": "XML::LibXML::InputCallback - XML::LibXML Class for Input Callbacks\n",
            "subsections": []
        },
        "SYNOPSIS": {
            "content": "use XML::LibXML;\n",
            "subsections": []
        },
        "DESCRIPTION": {
            "content": "You may get unexpected results if you are trying to load external documents during libxml2\nparsing if the location of the resource is not a HTTP, FTP or relative location but a absolute\npath for example. To get around this limitation, you may add your own input handler to open,\nread and close particular types of locations or URI classes. Using this input callback handlers,\nyou can handle your own custom URI schemes for example.\n\nThe input callbacks are used whenever XML::LibXML has to get something other than externally\nparsed entities from somewhere. They are implemented using a callback stack on the Perl layer in\nanalogy to libxml2's native callback stack.\n\nThe XML::LibXML::InputCallback class transparently registers the input callbacks for the\nlibxml2's parser processes.\n\nHow does XML::LibXML::InputCallback work?\nThe libxml2 library offers a callback implementation as global functions only. To work-around\nthe troubles resulting in having only global callbacks - for example, if the same global\ncallback stack is manipulated by different applications running together in a single Apache\nWeb-server environment -, XML::LibXML::InputCallback comes with a object-oriented and a\nfunction-oriented part.\n\nUsing the function-oriented part the global callback stack of libxml2 can be manipulated. Those\nfunctions can be used as interface to the callbacks on the C- and XS Layer. At the\nobject-oriented part, operations for working with the \"pseudo-localized\" callback stack are\nimplemented. Currently, you can register and de-register callbacks on the Perl layer and\ninitialize them on a per parser basis.\n\nCallback Groups\nThe libxml2 input callbacks come in groups. One group contains a URI matcher (*match*), a data\nstream constructor (*open*), a data stream reader (*read*), and a data stream destructor\n(*close*). The callbacks can be manipulated on a per group basis only.\n\nThe Parser Process\nThe parser process works on an XML data stream, along which, links to other resources can be\nembedded. This can be links to external DTDs or XIncludes for example. Those resources are\nidentified by URIs. The callback implementation of libxml2 assumes that one callback group can\nhandle a certain amount of URIs and a certain URI scheme. Per default, callback handlers for\n*file://, *file:://*.gz*, *http:// and *ftp:// are registered.\n\nCallback groups in the callback stack are processed from top to bottom, meaning that callback\ngroups registered later will be processed before the earlier registered ones.\n\nWhile parsing the data stream, the libxml2 parser checks if a registered callback group will\nhandle a URI - if they will not, the URI will be interpreted as *file://URI*. To handle a URI,\nthe *match* callback will have to return '1'. If that happens, the handling of the URI will be\npassed to that callback group. Next, the URI will be passed to the *open* callback, which should\nreturn a *reference* to the data stream if it successfully opened the file, '0' otherwise. If\nopening the stream was successful, the *read* callback will be called repeatedly until it\nreturns an empty string. After the read callback, the *close* callback will be called to close\nthe stream.\n\nOrganisation of callback groups in XML::LibXML::InputCallback\nCallback groups are implemented as a stack (Array), each entry holds a reference to an array of\nthe callbacks. For the libxml2 library, the XML::LibXML::InputCallback callback implementation\nappears as one single callback group. The Perl implementation however allows one to manage\ndifferent callback stacks on a per libxml2-parser basis.\n",
            "subsections": [
                {
                    "name": "Using XML::LibXML::InputCallback",
                    "content": "After object instantiation using the parameter-less constructor, you can register callback\ngroups.\n\nmy $inputcallbacks = XML::LibXML::InputCallback->new();\n$inputcallbacks->registercallbacks([ $matchcb1, $opencb1,\n$readcb1, $closecb1 ] );\n$inputcallbacks->registercallbacks([ $matchcb2, $opencb2,\n$readcb2, $closecb2 ] );\n$inputcallbacks->registercallbacks( [ $matchcb3, $opencb3,\n$readcb3, $closecb3 ] );\n\n$parser->inputcallbacks( $inputcallbacks );\n$parser->parsefile( $somexmlfile );\n\nWhat about the old callback system prior to XML::LibXML::InputCallback?\nIn XML::LibXML versions prior to 1.59 - i.e. without the XML::LibXML::InputCallback module - you\ncould define your callbacks either using globally or locally. You still can do that using\nXML::LibXML::InputCallback, and in addition to that you can define the callbacks on a per parser\nbasis!\n\nIf you use the old callback interface through global callbacks, XML::LibXML::InputCallback will\ntreat them with a lower priority as the ones registered using the new interface. The global\ncallbacks will not override the callback groups registered using the new interface. Local\ncallbacks are attached to a specific parser instance, therefore they are treated with highest\npriority. If the *match* callback of the callback group registered as local variable is\nidentical to one of the callback groups registered using the new interface, that callback group\nwill be replaced.\n\nUsers of the old callback implementation whose *open* callback returned a plain string, will\nhave to adapt their code to return a reference to that string after upgrading to version >=\n1.59. The new callback system can only deal with the *open* callback returning a reference!\n"
                }
            ]
        },
        "INTERFACE DESCRIPTION": {
            "content": "",
            "subsections": [
                {
                    "name": "Global Variables",
                    "content": "$CURCB\nStores the current callback and can be used as shortcut to access the callback stack.\n\n@GLOBALCALLBACKS\nStores all callback groups for the current parser process.\n\n@CBSTACK\nStores the currently used callback group. Used to prevent parser errors when dealing with\nnested XML data.\n"
                },
                {
                    "name": "Global Callbacks",
                    "content": "callbackmatch\nImplements the interface for the *match* callback at C-level and for the selection of the\ncallback group from the callbacks defined at the Perl-level.\n\ncallbackopen\nForwards the *open* callback from libxml2 to the corresponding callback function at the\nPerl-level.\n\ncallbackread\nForwards the read request to the corresponding callback function at the Perl-level and\nreturns the result to libxml2.\n\ncallbackclose\nForwards the *close* callback from libxml2 to the corresponding callback function at the\nPerl-level..\n"
                },
                {
                    "name": "Class methods",
                    "content": ""
                },
                {
                    "name": "new",
                    "content": "A simple constructor.\n"
                },
                {
                    "name": "register_callbacks",
                    "content": "The four callbacks *have* to be given as array reference in the above order *match*, *open*,\n*read*, *close*!\n"
                },
                {
                    "name": "unregister_callbacks",
                    "content": "With no arguments given, \"unregistercallbacks()\" will delete the last registered callback\ngroup from the stack. If four callbacks are passed as array reference, the callback group to\nunregister will be identified by the *match* callback and deleted from the callback stack.\nNote that if several identical *match* callbacks are defined in different callback groups,\nALL of them will be deleted from the stack.\n"
                },
                {
                    "name": "init_callbacks",
                    "content": "Initializes the callback system for the provided parser before starting a parsing process.\n"
                },
                {
                    "name": "cleanup_callbacks",
                    "content": "Resets global variables and the libxml2 callback stack.\n"
                },
                {
                    "name": "lib_init_callbacks",
                    "content": "Used internally for callback registration at C-level.\n"
                },
                {
                    "name": "lib_cleanup_callbacks",
                    "content": "Used internally for callback resetting at the C-level.\n"
                }
            ]
        },
        "EXAMPLE CALLBACKS": {
            "content": "The following example is a purely fictitious example that uses a MyScheme::Handler object that\nresponds to methods similar to an IO::Handle.\n\n# Define the four callback functions\nsub matchuri {\nmy $uri = shift;\nreturn $uri =~ /^myscheme:/; # trigger our callback group at a 'myscheme' URIs\n}\n\nsub openuri {\nmy $uri = shift;\nmy $handler = MyScheme::Handler->new($uri);\nreturn $handler;\n}\n\n# The returned $buffer will be parsed by the libxml2 parser\nsub readuri {\nmy $handler = shift;\nmy $length = shift;\nmy $buffer;\nread($handler, $buffer, $length);\nreturn $buffer; # $buffer will be an empty string '' if read() is done\n}\n\n# Close the handle associated with the resource.\nsub closeuri {\nmy $handler = shift;\nclose($handler);\n}\n\n# Register them with a instance of XML::LibXML::InputCallback\nmy $inputcallbacks = XML::LibXML::InputCallback->new();\n$inputcallbacks->registercallbacks([ \\&matchuri, \\&openuri,\n\\&readuri, \\&closeuri ] );\n\n# Register the callback group at a parser instance\n$parser->inputcallbacks( $inputcallbacks );\n\n# $somexmlfile will be parsed using our callbacks\n$parser->parsefile( $somexmlfile );\n",
            "subsections": []
        },
        "AUTHORS": {
            "content": "Matt Sergeant, Christian Glahn, Petr Pajas\n",
            "subsections": []
        },
        "VERSION": {
            "content": "2.0134\n",
            "subsections": []
        },
        "COPYRIGHT": {
            "content": "2001-2007, AxKit.com Ltd.\n\n2002-2006, Christian Glahn.\n\n2006-2009, Petr Pajas.\n",
            "subsections": []
        },
        "LICENSE": {
            "content": "This program is free software; you can redistribute it and/or modify it under the same terms as\nPerl itself.\n",
            "subsections": []
        }
    },
    "summary": "XML::LibXML::InputCallback - XML::LibXML Class for Input Callbacks",
    "flags": [],
    "examples": [],
    "see_also": []
}