Documentation: services/ping.php

services/ping.php - Process ping requests

This script accepts following XML-RPC calls:

monitor.ping
pingback.ping
weblogUpdates.ping

Please note that technical specifications describe different ways to return information, and this may lead to various error codes depending on situation. Basically, we have implemented XML-RPC return codes where applicable, plus specific recommendations where applicable. For example, if no data is provided to this script, the sender will be returned a structure with attributes 'faultCode' and 'faultString'. But if inadequate parameters are given to a 'pingback.ping' call, a simple error code will be returned.

monitor.ping

Syntax: monitor.ping() returns (int, string)

This entry point is used to centralize the monitoring of yacs servers.

The returned structure is made of an integer and a string. The value 0 means that the pinged server has checked its internal state and that this state is OK. Else an error code and a printable label are returned.

You can prevent a server to monitor you by disabling monitoring in the related server profile.

pingback.ping

Syntax: pingback.ping(source_uri, target_uri) returns string or int

This entry point is used to link a remote page (the source_uri) to one page at the server receiving the call (the target_uri). We are claiming to fully support the pingback server interface here, as described in the pingback specification.

According to the specification we are returning either the string 'Thank you for the ping', or an error code. Following error codes have been defined:

0 generic fault code
16 The source URI does not exists
17 The source URI does not contain a link to the target URI, and so cannot be used as a source
32 The specific target URI does not exist
33 The specified target URI cannot be used as a target. It either does not exist, or it is not a pingback-enabled resource.
48 The pingback has already been registered
49 Access denied
50 The server could not communicate with an upstream server, or received an error from an upstream server.

Note that YACS also has a client implementation of the pingback specification into links/links.php.

How does pingback work?

Ok, for those new to pingback here is an overview of the protocol:

Alice posts to her blog, including the URL http://www.bob.com/post5.
Alice's blogging system (AliceBlog) gets all external URLs referenced in the post (in this case, just the one to Bob).
AliceBlog requests http://www.bob.com/post5 and parses it for a <link> tag matching <link rel="pingback" href="http://foo/xmlrpcserver" />.
If it doesn't find one, or the response of the request doesn't seem to support it, then abort the ping trial for this link.
Perform an XML-RPC ping to the URL found in the <link>. AliceBlog doesn't care if it succeeds or not, really; that's the end of its bit.
BobBlog receives the XML-RPC ping, naming the URL of Alice's post (AliceURL), and the URL it linked to (BobURL).
BobBlog should check that BobURL is part of Bob's blog.
BobBlog requests the URL of Alice's post, and confirms that it mentions BobURL.
BobBlog parses the title of AliceURL.
BobBlog stashes the details of the ping somewhere in its database, against the entry which is BobURL..

You can prevent a server to flood you by disabling pings in the related server profile.

weblogUpdates.ping

Syntax: weblogUpdates.ping(blog_name, blog_url) returns (flerror = boolean, message = string)

It takes two parameters, both strings. The first is the name of the weblog, the second is its URL.

It returns a struct that indicates success or failure. It has two elements, flerror and message. If flerror is false, it worked. If it's true, message contains an English-language description of the reason for the failure.

If the call succeeds, an entry for this server will be created or updated in the database (see servers/index.php) for the provided URL. Note that an existing profile is updated only if ping is still allowed for it.

This entry point is used to centralize change information. By letting the receiving server know about updates, efficient aggregation mechanisms can be put in place.

To tell a YACS server that a weblog has changed, call weblogUpdates.ping at path /yacs/services/ping.php.

You can prevent a server to flood you by disabling pings in the related server profile.

This script is a reference file of this system.

Voir aussi:

Licence: GNU Lesser General Public License

Auteurs:

Bernard Paques bernard.paques@bigfoot.com