====== Module API differences ======

===== Deprecated (InspIRCd API that won't work in U4) =====

<code>
        /** Called whenever an oper password is to be compared to what a user has input.
         * The password field (from the config file) is in 'password' and is to be compared against
         * 'input'. This method allows for encryption of oper passwords and much more besides.
         * You should return a nonzero value if you want to allow the comparison or zero if you wish
         * to do nothing.
         * @param password The oper's password
         * @param input The password entered
         * @param tagnumber The tag number (from the configuration file) of this oper's tag
         * @return 1 to match the passwords, 0 to do nothing. -1 to not match, and not continue.
         * @deprecated Replaced by OnPassComparison in U4
         */
        virtual int OnOperCompare(const std::string &password, const std::string &input, int tagnumber);
</code>

===== Eventually Insp API =====

<code>
        /** Called whenever the server retrieves a server-to-server query (ENCAP)
         * This will not get triggered when destination of ENCAP is for a user
         * (where the protocol acts like PUSH does currently). Nor will it get
         * triggered if destination is not us. There is -always- a second parameter,
         * which determines the type of the query. First is the pattern that you
         * reached the server through
         * @param from The name of the server sending the query
         * @param parameters An deque of std::string containing
         *                   the parameters for the command.
         * @return 1 if you have handled the query type and 0 if you haven't
         */
        virtual int OnEncapReceived(const std::string& from, std::deque<std::string>& parameters);
</code>

**Used by:** m_rping

===== U4 Specific =====

<code>
        /** Called whenever a user requests a channel list (/LIST), also SAFELIST
         * This is called before other channels are sent but after the initial header
         * @param user the user who did the /LIST
         * @param parameters parameters given to the /LIST
         * @param pcnt amount of parameters in the /LIST command
         * @param minusers minimum users in the channel (0 means there was no parameter)
         * @param maxusers maximum users in the channel (0 means there was no parameter)
         */
        virtual void OnChannelList(userrec* user, const char** parameters, int pcnt, int minusers, int maxusers);
</code>

**Used by:** cmd_list, m_safelist, m_officialchannels.cpp

<code>
        /** Called when a download is requested, asynchronously
         * The receiver will, if handled, run the OnDownloadFileCompleted or OnDownloadFileFailure
         * The receiver must stop downloading if OnCancelDownloadFileAsync is called
         * The receiver must handle caching by itself
         * @param url URL that is to be downloaded
         * @return 1 if you handled the download, 0 else
         */
        virtual int OnDownloadFileAsync(const std::string&url);
</code>

<code>
        /** Called when a download has finished
         * @param url The URL that has finished downloading
         * @param contents Contents of the download
         * @return 1 if you handled the request, 0 if you didn't
         */
        virtual int OnDownloadFileCompleted(const std::string& url, std::string &contents);
</code>

<code>
        /** Called when a download failed to download
         * @param url The URL that failed to download
         * @param error The error that happened
         * @return 1 if you handled the request, 0 if you didn't
         */
        virtual int OnDownloadFileFailure(const std::string& url, std::string &error);
</code>

<code>
        /** Called when an async download is supposed to be cancelled
         * @param url The download that should be cancelled
         * @return 1 if you handled the request, 0 if you didn't
         */
        virtual int OnCancelDownloadFileAsync(const std::string& url);
</code>

<code>
        /** Called when a download is requested, synchronously
          * @param url URL to be downloaded
          * @param contents Contents if the download succeeded
          * @param error The error that happened if an error happened
          * @return 0 if you didn't handle the request, -1 if you did and it failed, 1 if it succeded
         */
        virtual int OnDownloadFile(std::string& url, std::string& contents, std::string& error);
</code>

<code>
        /** Called when a password comparison is wished (/OPER, connect, etc)
          * @param user the user in question
          * @param authtype Auth type (sslclientcert, etc)
          * @param confpass Password/value in configuration
          * @param password The password given by the user
          * @return 0 if you didn't handle the request, -1 if you did and it didn't succeed, 1 if it succeded
          */
        virtual int OnPassComparison(userrec* user, const char* authtype, const char *confpass, const char* password);
</code>

**Used by:** m_oper_hash, m_ssl_oper_cert, cmd_oper, cmd_pass

<code>
        /** Called when a locally connected server introduces a remote server
          * @param prefix server introducing
          * @param servername server being introduced
          * @param serverreason string to put a reason for terminating link in, sent to server
          * @param operreason string to put a reason for terminating link in, sent to opers
          * @return 0 if you agree or didn't handle the request, -1 if you disagree to the linking, reason is in reason
          */
        virtual int OnRemoteServerIntroducing(const std::string& prefix, const std::string& servername,
               std::string& serverreason, std::string& operreason);
</code>

**Used by:** m_banserver, m_spanningtree

<code>
        /** Called just before checking a mask against a user's full host.
          * @param user the user who is joining, or whatever else
          * @param channel the channel the activity is taking place in
          * @param mask the ban mask as it was set in mode +b <blah>
          * @param bantype a string identifying the activity taking place
          * @return 0 if you didn't handle the request, -1 if you did and the user isn't banned by this mask, 1 if the user was banned
          */
        virtual int OnCheckBanMask(userrec* user, chanrec* channel, const char* mask, const char* bantype);
</code>

**Used by:** m_extban, m_banexception

<code>
        /** Called whenever a user joins a channel, to determine if banlist checks should go ahead for this bantype.
         * This method will always be called for each event that checks bans, whether or not the user actually matches a
         * channel ban, and determines the outcome of an if statement around the whole section of ban checking code.
         * @param user The user joining the channel
         * @param chan The channel being joined
         * @param bantype The event for which a ban check is occuring.
         * @return 1 to explicitly allow the event, 0 to proceed as normal
         */
        virtual int OnCheckBanWithType(userrec* user, chanrec* chan, const char* bantype);
</code>

**Used by:** m_extban, m_banexception