Callbacks

  AddressCallback (addr, status, *user_data)
  AuthDomainBasicAuthCallback (domain, msg, username, password, *user_data)
  AuthDomainDigestAuthCallback (domain, msg, username, *user_data)
  AuthDomainFilter (domain, msg, *user_data)
  AuthDomainGenericAuthCallback (domain, msg, username, *user_data)
  ChunkAllocator (msg, max_len, *user_data)
  LoggerFilter (logger, msg, *user_data)
  LoggerPrinter (logger, level, direction, data, *user_data)
  MessageHeadersForeachFunc (name, value, *user_data)
  PasswordManagerCallback (password_manager, msg, auth, retrying, *user_data)
  ProxyResolverCallback (proxy_resolver, msg, arg, addr, *user_data)
  ProxyURIResolverCallback (resolver, status, proxy_uri, *user_data)
  ServerCallback (server, msg, path, query, client, *user_data)
  ServerWebsocketCallback (server, connection, path, client, *user_data)
  SessionCallback (session, msg, *user_data)
  SessionConnectProgressCallback (session, event, connection, *user_data)
  SocketCallback (sock, status, *user_data)

Details

Soup.AddressCallback(addr, status, *user_data)
Parameters:

The callback function passed to Soup.Address.resolve_async().

Soup.AuthDomainBasicAuthCallback(domain, msg, username, password, *user_data)
Parameters:
Returns:

True if username and password are valid
Return type:

bool

Callback used by Soup.AuthDomainBasic for authentication purposes. The application should verify that username and password and valid and return True or False.

If you are maintaining your own password database (rather than using the password to authenticate against some other system like PAM or a remote server), you should make sure you know what you are doing. In particular, don’t store cleartext passwords, or easily-computed hashes of cleartext passwords, even if you don’t care that much about the security of your server, because users will frequently use the same password for multiple sites, and so compromising any site with a cleartext (or easily-cracked) password database may give attackers access to other more-interesting sites as well.

Soup.AuthDomainDigestAuthCallback(domain, msg, username, *user_data)
Parameters:
Returns:

the encoded password, or None if username is not a valid user. domain will free the password when it is done with it.
Return type:

str or None

Callback used by Soup.AuthDomainDigest for authentication purposes. The application should look up username in its password database, and return the corresponding encoded password (see Soup.AuthDomainDigest.encode_password()).

Soup.AuthDomainFilter(domain, msg, *user_data)
Parameters:
Returns:

True if msg requires authentication, False if not.
Return type:

bool

The prototype for a Soup.AuthDomain filter; see Soup.AuthDomain.set_filter() for details.

Soup.AuthDomainGenericAuthCallback(domain, msg, username, *user_data)
Parameters:
Returns:

True if msg is authenticated, False if not.
Return type:

bool

The prototype for a Soup.AuthDomain generic authentication callback.

The callback should look up the user’s password, call Soup.AuthDomain.check_password(), and use the return value from that method as its own return value.

In general, for security reasons, it is preferable to use the auth-domain-specific auth callbacks (eg, Soup.AuthDomainBasicAuthCallback and Soup.AuthDomainDigestAuthCallback), because they don’t require keeping a cleartext password database. Most users will use the same password for many different sites, meaning if any site with a cleartext password database is compromised, accounts on other servers might be compromised as well. For many of the cases where Soup.Server is used, this is not really relevant, but it may still be worth considering.

Soup.ChunkAllocator(msg, max_len, *user_data)
Parameters:
Returns:

the new buffer (or None)
Return type:

Soup.Buffer or None

The prototype for a chunk allocation callback. This should allocate a new Soup.Buffer and return it for the I/O layer to read message body data off the network into.

If max_len is non-0, it indicates the maximum number of bytes that could be read, based on what is known about the message size. Note that this might be a very large number, and you should not simply try to allocate that many bytes blindly. If max_len is 0, that means that libsoup does not know how many bytes remain to be read, and the allocator should return a buffer of a size that it finds convenient.

If the allocator returns None, the message will be paused. It is up to the application to make sure that it gets unpaused when it becomes possible to allocate a new buffer.

Deprecated since version ???: Use Soup.Request if you want to read into your own buffers.

Soup.LoggerFilter(logger, msg, *user_data)
Parameters:
Returns:

a Soup.LoggerLogLevel value indicating how much of the message to log
Return type:

Soup.LoggerLogLevel

The prototype for a logging filter. The filter callback will be invoked for each request or response, and should analyze it and return a Soup.LoggerLogLevel value indicating how much of the message to log. Eg, it might choose between Soup.LoggerLogLevel.BODY and Soup.LoggerLogLevel.HEADERS depending on the Content-Type.

Soup.LoggerPrinter(logger, level, direction, data, *user_data)
Parameters:

The prototype for a custom printing callback.

level indicates what kind of information is being printed. Eg, it will be Soup.LoggerLogLevel.HEADERS if data is header data.

direction is either ‘<’, ‘>’, or ‘ ‘, and data is the single line to print; the printer is expected to add a terminating newline.

To get the effect of the default printer, you would do:

<informalexample><programlisting> printf (“%c %s\n”, direction, data); </programlisting></informalexample>

Soup.MessageHeadersForeachFunc(name, value, *user_data)
Parameters:

The callback passed to Soup.MessageHeaders.foreach().

Soup.PasswordManagerCallback(password_manager, msg, auth, retrying, *user_data)
Parameters:
Soup.ProxyResolverCallback(proxy_resolver, msg, arg, addr, *user_data)
Parameters:

Deprecated since version 2.28: Use Soup.ProxyURIResolver instead

Soup.ProxyURIResolverCallback(resolver, status, proxy_uri, *user_data)
Parameters:

Callback for Soup.ProxyURIResolver.get_proxy_uri_async()

Soup.ServerCallback(server, msg, path, query, client, *user_data)
Parameters:

A callback used to handle requests to a Soup.Server.

path and query contain the likewise-named components of the Request-URI, subject to certain assumptions. By default, Soup.Server decodes all percent-encoding in the URI path, such that “/foo% 2Fbar” is treated the same as “/foo/bar”. If your server is serving resources in some non-POSIX-filesystem namespace, you may want to distinguish those as two distinct paths. In that case, you can set the Soup.SERVER_RAW_PATHS property when creating the Soup.Server, and it will leave those characters undecoded. (You may want to call Soup.URI.normalize() to decode any percent-encoded characters that you aren’t handling specially.)

query contains the query component of the Request-URI parsed according to the rules for HTML form handling. Although this is the only commonly-used query string format in HTTP, there is nothing that actually requires that HTTP URIs use that format; if your server needs to use some other format, you can just ignore query, and call Soup.Message.get_uri() and parse the URI’s query field yourself.

See Soup.Server.add_handler() and Soup.Server.add_early_handler() for details of what handlers can/should do.

Soup.ServerWebsocketCallback(server, connection, path, client, *user_data)
Parameters:

A callback used to handle WebSocket requests to a Soup.Server. The callback will be invoked after sending the handshake response back to the client (and is only invoked if the handshake was successful).

path contains the path of the Request-URI, subject to the same rules as Soup.ServerCallback (qv).

Soup.SessionCallback(session, msg, *user_data)
Parameters:

Prototype for the callback passed to Soup.Session.queue_message(), qv.

Soup.SessionConnectProgressCallback(session, event, connection, *user_data)
Parameters:

Prototype for the progress callback passed to Soup.Session.connect_async().

New in version 2.62.

Soup.SocketCallback(sock, status, *user_data)
Parameters:

The callback function passed to Soup.Socket.connect_async().