server.h File Reference
`#include "lscp/socket.h"`
`#include "lscp/event.h"`

Go to the source code of this file.

## Data Structures

struct | _lscp_connect_t
struct | _lscp_connect_list_t
struct | _lscp_server_t

## Typedefs

typedef enum _lscp_server_mode_t | lscp_server_mode_t
typedef enum _lscp_connect_mode_t | lscp_connect_mode_t
typedef struct _lscp_connect_t | lscp_connect_t
typedef struct _lscp_connect_list_t | lscp_connect_list_t
typedef lscp_status_t(* | lscp_server_proc_t )(lscp_connect_t *pConnect, const char *pchBuffer, int cchBuffer, void *pvData)
typedef struct _lscp_server_t | lscp_server_t

## Enumerations

enum | _lscp_server_mode_t { LSCP_SERVER_THREAD = 0, LSCP_SERVER_SELECT = 1 }
enum | _lscp_connect_mode_t { LSCP_CONNECT_OPEN = 0, LSCP_CONNECT_CLOSE = 1 }

## Functions

const char * | lscp_server_package (void)
const char * | lscp_server_version (void)
const char * | lscp_server_build (void)
lscp_server_t * | lscp_server_create (int iPort, lscp_server_proc_t pfnCallback, void *pvData)
lscp_server_t * | lscp_server_create_ex (int iPort, lscp_server_proc_t pfnCallback, void *pvData, lscp_server_mode_t mode)
lscp_status_t | lscp_server_join (lscp_server_t *pServer)
lscp_status_t | lscp_server_destroy (lscp_server_t *pServer)
lscp_status_t | lscp_server_broadcast (lscp_server_t *pServer, lscp_event_t event, const char *pchData, int cchData)
lscp_status_t | lscp_server_result (lscp_connect_t *pConnect, const char *pchBuffer, int cchBuffer)
lscp_status_t | lscp_server_subscribe (lscp_connect_t *pConnect, lscp_event_t event)
lscp_status_t | lscp_server_unsubscribe (lscp_connect_t *pConnect, lscp_event_t event)

## Typedef Documentation

typedef struct _lscp_connect_list_t lscp_connect_list_t

Client connection list struct.

typedef enum _lscp_connect_mode_t lscp_connect_mode_t

Connection mode notification.

typedef struct _lscp_connect_t lscp_connect_t

Client connection descriptor struct.

typedef enum _lscp_server_mode_t lscp_server_mode_t

Server thread model.

typedef lscp_status_t(* lscp_server_proc_t)(lscp_connect_t *pConnect, const char *pchBuffer, int cchBuffer, void *pvData)

Server callback procedure prototype.

typedef struct _lscp_server_t lscp_server_t

Server descriptor struct.

## Enumeration Type Documentation

enum _lscp_connect_mode_t

Connection mode notification.

Enumerator
LSCP_CONNECT_OPEN |
LSCP_CONNECT_CLOSE |

enum _lscp_server_mode_t

Server thread model.

Enumerator
LSCP_SERVER_THREAD |
LSCP_SERVER_SELECT |

## Function Documentation

lscp_status_t lscp_server_broadcast | ( | lscp_server_t * | pServer,
|  | lscp_event_t | event,
|  | const char * | pchData,
|  | int | cchData
| ) |  |

Send an event notification message to all subscribed clients.

Parameters

  pServer | Pointer to server instance structure.
  event | Event type flag to send to all subscribed clients.
  pchData | Pointer to event data to be sent to all clients.
  cchData | Length of the event data to be sent in bytes.

Returns
  LSCP_OK on success, LSCP_FAILED otherwise.

References _lscp_connect_t::client, _lscp_server_t::connects, _lscp_connect_t::events, _lscp_connect_list_t::first, LSCP_BUFSIZ, lscp_event_to_text(), LSCP_FAILED, lscp_mutex_lock, lscp_mutex_unlock, LSCP_OK, _lscp_connect_list_t::mutex, _lscp_connect_t::next, and _lscp_socket_agent_t::sock.

Referenced by main().

const char* lscp_server_build | ( | void |  | ) |

Retrieve the current server library build timestamp string.

Referenced by server_callback(), and server_usage().

lscp_server_t* lscp_server_create | ( | int | iPort,
|  | lscp_server_proc_t | pfnCallback,
|  | void * | pvData
| ) |  |

Create a server instance, listening on the given port for client connections. A server callback function must be suplied that will handle every and each client request.

Parameters

  iPort | Port number where the server will bind for listening.
  pfnCallback | Callback function to receive and handle client requests.
  pvData | Server context opaque data, that will be passed to the callback function without change.

Returns
  The new server instance pointer lscp_server_t if successfull, which shall be used on all subsequent server calls, NULL otherwise.

References lscp_server_create_ex(), and LSCP_SERVER_SELECT.

Referenced by main().

lscp_server_t* lscp_server_create_ex | ( | int | iPort,
|  | lscp_server_proc_t | pfnCallback,
|  | void * | pvData,
|  | lscp_server_mode_t | mode
| ) |  |

Create a server instance, listening on the given port for client connections. A server callback function must be suplied that will handle every and each client request. A server threading model maybe specified either as multi-threaded (one thread per client) or single thread multiplex mode (one thread serves all clients).

Parameters

  iPort | Port number where the server will bind for listening.
  pfnCallback | Callback function to receive and handle client requests.
  pvData | Server context opaque data, that will be passed to the callback function without change.
  mode | Server mode of operation, regarding the internal threading model, either LSCP_SERVER_THREAD for a multi-threaded server, or LSCP_SERVER_SELECT for a single-threaded multiplexed server.

Returns
  The new server instance pointer if successfull, which shall be used on all subsequent server calls, NULL otherwise.

References _lscp_socket_agent_t::addr, _lscp_server_t::agent, closesocket, _lscp_server_t::connects, INVALID_SOCKET, LSCP_OK, lscp_socket_agent_free(), lscp_socket_agent_init(), lscp_socket_agent_start(), lscp_socket_getopts(), lscp_socket_perror(), _lscp_server_t::mode, _lscp_server_t::pfnCallback, _lscp_server_t::pvData, _lscp_socket_agent_t::sock, and SOCKET_ERROR.

Referenced by lscp_server_create().

lscp_status_t lscp_server_destroy | ( | lscp_server_t * | pServer | ) |

Terminate and destroy a server instance.

Parameters

  pServer | Pointer to server instance structure.

References _lscp_server_t::agent, _lscp_server_t::connects, LSCP_FAILED, LSCP_OK, and lscp_socket_agent_free().

Referenced by main().

lscp_status_t lscp_server_join | ( | lscp_server_t * | pServer | ) |

Wait for a server instance to terminate graciously.

Parameters

  pServer | Pointer to server instance structure.

References _lscp_server_t::agent, LSCP_FAILED, LSCP_OK, and lscp_socket_agent_join().

const char* lscp_server_package | ( | void |  | ) |

Retrieve the current server library version string.

References LSCP_PACKAGE.

Referenced by server_callback(), and server_usage().

lscp_status_t lscp_server_result | ( | lscp_connect_t * | pConnect,
|  | const char * | pchBuffer,
|  | int | cchBuffer
| ) |  |

Send response for the current client callback request.

Parameters

  pConnect | Pointer to client connection instance structure.
  pchBuffer | Pointer to data to be sent to the client as response.
  cchBuffer | Length of the response data to be sent in bytes.

Returns
  LSCP_OK on success, LSCP_FAILED otherwise.

References _lscp_connect_t::client, LSCP_FAILED, LSCP_OK, lscp_socket_perror(), and _lscp_socket_agent_t::sock.

Referenced by server_callback().

lscp_status_t lscp_server_subscribe | ( | lscp_connect_t * | pConnect,
|  | lscp_event_t | event
| ) |  |

Register client as a subscriber of event broadcast messages.

Parameters

  pConnect | Pointer to client connection instance structure.
  event | Event type flag of the requesting client subscription.

Returns
  LSCP_OK on success, LSCP_FAILED otherwise.

References _lscp_connect_t::events, LSCP_EVENT_NONE, LSCP_FAILED, and LSCP_OK.

Referenced by server_callback().

lscp_status_t lscp_server_unsubscribe | ( | lscp_connect_t * | pConnect,
|  | lscp_event_t | event
| ) |  |

Deregister client as subscriber of event broadcast messages.

Parameters

  pConnect | Pointer to client connection instance structure.
  event | Event type flag of the requesting client unsubscription.

Returns
  LSCP_OK on success, LSCP_FAILED otherwise.

References _lscp_connect_t::events, LSCP_EVENT_NONE, LSCP_FAILED, and LSCP_OK.

Referenced by server_callback().

const char* lscp_server_version | ( | void |  | ) |

Retrieve the current server library version string.

References LSCP_VERSION.

Referenced by server_callback(), and server_usage().