libmpdclient: mpd/connection.h File Reference

libmpdclient 2.13

Functions
connection.h File Reference

MPD client library. More...

Go to the source code of this file.

## Functions
mpd_malloc struct mpd_connection * | mpd_connection_new (const char *host, unsigned port, unsigned timeout_ms)
mpd_malloc struct mpd_connection * | mpd_connection_new_async (struct mpd_async *async, const char *welcome)
void | mpd_connection_free (struct mpd_connection *connection)
const struct mpd_settings * | mpd_connection_get_settings (const struct mpd_connection *connection)
void | mpd_connection_set_keepalive (struct mpd_connection *connection, bool keepalive)
void | mpd_connection_set_timeout (struct mpd_connection *connection, unsigned timeout_ms)
mpd_pure int | mpd_connection_get_fd (const struct mpd_connection *connection)
mpd_pure struct mpd_async * | mpd_connection_get_async (struct mpd_connection *connection)
mpd_pure enum mpd_error | mpd_connection_get_error (const struct mpd_connection *connection)
mpd_pure const char * | mpd_connection_get_error_message (const struct mpd_connection *connection)
mpd_pure enum mpd_server_error | mpd_connection_get_server_error (const struct mpd_connection *connection)
mpd_pure unsigned | mpd_connection_get_server_error_location (const struct mpd_connection *connection)
mpd_pure int | mpd_connection_get_system_error (const struct mpd_connection *connection)
bool | mpd_connection_clear_error (struct mpd_connection *connection)
mpd_pure const unsigned * | mpd_connection_get_server_version (const struct mpd_connection *connection)
mpd_pure int | mpd_connection_cmp_server_version (const struct mpd_connection *connection, unsigned major, unsigned minor, unsigned patch)

## Detailed Description

MPD client library.

Do not include this header directly. Use mpd/client.h instead.

Definition in file connection.h.

## Function Documentation

## ◆ mpd_connection_new()

mpd_malloc struct mpd_connection* mpd_connection_new | ( | const char * | host,
|  | unsigned | port,
|  | unsigned | timeout_ms
| ) |  |

Opens a new connection to a MPD server. Both the name server lookup and the connect() call are done synchronously. After this function has returned, you should check if the connection was successful with mpd_connection_get_error().

Parameters

  host | the server's host name, IP address or Unix socket path. If the resolver returns more than one IP address for a host name, this functions tries all of them until one accepts the connection. NULL is allowed here, which will connect to the default host (using the MPD_HOST environment variable if present).
  port | the TCP port to connect to, 0 for default port (using the MPD_PORT environment variable if present). If "host" is a Unix socket path, this parameter is ignored.
  timeout_ms | the timeout in milliseconds, 0 for the default timeout (the environment variable MPD_TIMEOUT may specify a timeout in seconds); you may modify it later with mpd_connection_set_timeout()

Returns
  a mpd_connection object (which may have failed to connect), or NULL on out-of-memory

Since
  libmpdclient 2.3 added support for #MPD_HOST, #MPD_PORT and #MPD_TIMEOUT.

## ◆ mpd_connection_new_async()

mpd_malloc struct mpd_connection* mpd_connection_new_async | ( | struct mpd_async * | async,
|  | const char * | welcome
| ) |  |

Creates a mpd_connection object based on an existing asynchronous MPD connection. You should not continue to use the mpd_async object. Note that mpd_connection_free() also frees your mpd_async object!

This function does not block at all, which is why you have to pass the welcome message to it.

Parameters

  async | a mpd_async instance
  welcome | the first line sent by MPD (the welcome message)

Returns
  a mpd_connection object, or NULL on out-of-memory

## ◆ mpd_connection_free()

void mpd_connection_free | ( | struct mpd_connection * | connection | ) |

Close the connection and free all memory.

Parameters

  connection | the connection to MPD

## ◆ mpd_connection_get_settings()

const struct mpd_settings* mpd_connection_get_settings | ( | const struct mpd_connection * | connection | ) |

Returns the settings which were used to connect to the server. May be NULL if the settings are not known.

Since
  libmpdclient 2.4

## ◆ mpd_connection_set_keepalive()

void mpd_connection_set_keepalive | ( | struct mpd_connection * | connection,
|  | bool | keepalive
| ) |  |

Enables (or disables) TCP keepalives.

Keepalives are enabled using the SO_KEEPALIVE socket option. They may be required for long-idled connections to persist on some networks that would otherwise terminate inactive TCP sessions.

The default value is false.

Parameters

  connection | the connection to MPD
  keepalive | whether TCP keepalives should be enabled

Since
  libmpdclient 2.10

## ◆ mpd_connection_set_timeout()

void mpd_connection_set_timeout | ( | struct mpd_connection * | connection,
|  | unsigned | timeout_ms
| ) |  |

Sets the timeout for synchronous operations. If the MPD server does not send a response during this time span, the operation is aborted by libmpdclient.

The initial value is the one passed to mpd_connection_new(). If you have used mpd_connection_new_async(), then the default value is 30 seconds.

Parameters

  connection | the connection to MPD
  timeout_ms | the desired timeout in milliseconds; must not be 0

## ◆ mpd_connection_get_fd()

mpd_pure int mpd_connection_get_fd | ( | const struct mpd_connection * | connection | ) |

Returns the file descriptor which should be polled by the caller. Do not use the file descriptor for anything except polling! The file descriptor never changes during the lifetime of this mpd_connection object.

## ◆ mpd_connection_get_async()

mpd_pure struct mpd_async* mpd_connection_get_async | ( | struct mpd_connection * | connection | ) |

Returns the underlying mpd_async object. This can be used to send commands asynchronously. During an asynchronous command, you must not use synchronous mpd_connection functions until the asynchronous response has been finished.

If an error occurs while using mpd_async, you must close the mpd_connection.

## ◆ mpd_connection_get_error()

mpd_pure enum mpd_error mpd_connection_get_error | ( | const struct mpd_connection * | connection | ) |

Returns the libmpdclient error code. MPD_ERROR_SUCCESS means no error occurred.

## ◆ mpd_connection_get_error_message()

mpd_pure const char* mpd_connection_get_error_message | ( | const struct mpd_connection * | connection | ) |

Returns the human-readable (English) libmpdclient error message. Calling this function is only valid if an error really occurred. Check with mpd_connection_get_error().

For MPD_ERROR_SERVER, the error message is encoded in UTF-8. MPD_ERROR_SYSTEM obtains its error message from the operating system, and thus the locale's character set (and probably language) is used. Keep that in mind when you print error messages.

## ◆ mpd_connection_get_server_error()

mpd_pure enum mpd_server_error mpd_connection_get_server_error | ( | const struct mpd_connection * | connection | ) |

Returns the error code returned from the server. Calling this function is only valid if mpd_connection_get_error() returned MPD_ERROR_SERVER.

## ◆ mpd_connection_get_server_error_location()

mpd_pure unsigned mpd_connection_get_server_error_location | ( | const struct mpd_connection * | connection | ) |

Returns the location of the server error, i.e. an index within the command list. Calling this function is only valid in a command list response, and if mpd_connection_get_error() returned MPD_ERROR_SERVER.

Since
  libmpdclient 2.4

## ◆ mpd_connection_get_system_error()

mpd_pure int mpd_connection_get_system_error | ( | const struct mpd_connection * | connection | ) |

Returns the error code from the operating system; on most operating systems, this is the errno value. Calling this function is only valid if mpd_connection_get_error() returned MPD_ERROR_SYSTEM.

May be 0 if the operating system did not specify an error code.

## ◆ mpd_connection_clear_error()

bool mpd_connection_clear_error | ( | struct mpd_connection * | connection | ) |

Attempts to recover from an error condition. This function must be called after a non-fatal error before you can continue using this object.

Returns
  true on success, false if the error is fatal and cannot be recovered

## ◆ mpd_connection_get_server_version()

mpd_pure const unsigned* mpd_connection_get_server_version | ( | const struct mpd_connection * | connection | ) |

Returns a three-tuple containing the major, minor and patch version of the MPD protocol.

## ◆ mpd_connection_cmp_server_version()

mpd_pure int mpd_connection_cmp_server_version | ( | const struct mpd_connection * | connection,
|  | unsigned | major,
|  | unsigned | minor,
|  | unsigned | patch
| ) |  |

Compares the MPD protocol version with the specified triple.

Returns
  -1 if the server is older, 1 if it is newer, 0 if it is equal