# APPWEB - Appweb API Native API

# Components

MaAppweb | Singleton Appweb service for the application.
MaServer | Appweb server object.
MaState | Current configuration parse state.

# Functions

void | maAddDirective(MaAppweb *appweb, cchar *directive, MaDirective proc)
| Define a new appweb configuration file directive.
void | maAddEndpoint(MaServer *server, HttpEndpoint *endpoint)
| Add a listening endpoint.
void | maAddServer(MaAppweb *appweb, struct MaServer *server)
| Add a server.
int | maApplyChangedGroup(MaAppweb *appweb)
| Apply the changed Appweb group ID.
int | maApplyChangedUser(MaAppweb *appweb)
| Apply the changed Appweb user ID.
int | maArchiveLog(cchar *path, int count, int maxSize)
| Archive a log file.
int | maConfigureServer(MaServer *server, cchar *configFile, cchar *home, cchar *documents, cchar *ip, int port)
| Configure a web server.
MaAppweb* | maCreateAppweb()
| Create the Appweb object.
MaServer* | maCreateServer(MaAppweb *appweb, cchar *name)
| Create a MaServer object.
HttpAuth* | maGetDefaultAuth(MaServer *server)
| Get the default authentication object for the server.
void | maGetUserGroup(MaAppweb *appweb)
| Get the user group.
int | maLoadModule(MaAppweb *appweb, cchar *name, cchar *libname)
| Load an appweb module.
struct MaServer* | maLookupServer(MaAppweb *appweb, cchar *name)
| Lookup a server.
int | maParseConfig(MaServer *server, cchar *path, int flags)
| Parse an Appweb configuration file.
int | maParseInit(MaAppweb *appweb)
| Initialize the config file parser.
int | maParsePlatform(cchar *platform, cchar **os, cchar **arch, cchar **profile)
| Parse a platform string.
MaState* | maPopState(MaState *state)
| Pop the state.
MaState* | maPushState(MaState *state)
| Push the state.
bool | maRenderDirListing(HttpConn *conn)
| Test if a directory listing should be rendered for the request.
int | maRunSimpleWebServer(cchar *ip, int port, cchar *home, cchar *documents)
| Create and run a simple web server listening on a single IP address.
int | maRunWebClient(cchar *method, cchar *uri, char **response)
| Run a web client request.
int | maRunWebServer(cchar *configFile)
| Create and run a web server based on a configuration file.
void | maSetAccessLog(HttpRoute *route, cchar *path, cchar *format)
| Define the access log.
void | maSetDefaultServer(MaAppweb *appweb, struct MaServer *server)
| Set the default server.
int | maSetHttpGroup(MaAppweb *appweb, cchar *group)
| Set the Http Group.
int | maSetHttpUser(MaAppweb *appweb, cchar *user)
| Set the Http User.
void | maSetServerAddress(MaServer *server, cchar *ip, int port)
| Set the server listen address.
int | maStartAccessLogging(HttpRoute *route)
| Start access logging.
int | maStartAppweb(MaAppweb *appweb)
| Start Appweb services.
int | maStartServer(MaServer *server)
| Start a server.
void | maStopAccessLogging(HttpRoute *route)
| Stop access logging.
int | maStopAppweb(MaAppweb *appweb)
| Stop Appweb services.
void | maStopServer(MaServer *server)
| Stop a server.
bool | maTokenize(MaState *state, cchar *str, cchar *fmt, ...)
| Tokenize a string based on route data.
bool | maValidateServer(MaServer *server)
| Validate the configuration of a server.

# Typedefs

MaDirective | Appweb configuration file directive parsing callback function.

# Defines

#define | MA_PARSE_NON_SERVER 0x1
| Command file being parsed by a utility program.
#define | MA_UNLOAD_TIMEOUT "5mins"
| Default module inactivity unload timeout.

# MaAppweb

MaAppweb

Singleton Appweb service for the application.

Description:
  There is one instance of MaAppweb per application. It manages a list of HTTP servers running in the application.

See Also:
  Http, maAddServer, maApplyChangedGroup, maApplyChangedUser, maCreateAppweb, maGetUserGroup, maLoadModule, maLookupServer, maParseInit, maParsePlatform, maRenderDirListing, maSetDefaultServer, maSetHttpGroup, maSetHttpUser, maStartAppweb, maStopAppweb

API Stability:
  Internal.

Fields:

  struct MaServer * |  | defaultServer | Default server object.
  MprHash * |  | directives | Config file directives.
  int |  | gid | Group Id.
  cchar * |  | group | O/S application group name.
  int |  | groupChanged | Group name changed.
  Http * |  | http | Http service object.
  cchar * |  | localPlatform | Local (dev) platform os-arch-profile (lower case).
  cchar * |  | platform | Target platform os-arch-profile (lower case).
  cchar * |  | platformDir | Path to platform.
  MprList * |  | servers | List of server objects.
  int |  | skipModules | Don't load modules.
  int |  | staticLink | Target platform is using a static linking.
  int |  | uid | User Id.
  cchar * |  | user | O/S application user name.
  int |  | userChanged | User name changed.

void maAddDirective (MaAppweb *appweb, cchar *directive, MaDirective proc)

Define a new appweb configuration file directive.

Description:
  The appweb configuration file parse is extensible. New directives can be registered by this call. When encountered in the config file, the given callback proc will be invoked to parse.

Parameters:

  appweb | Appweb object created via maCreateAppweb
  directive | Directive name.
  proc | Directive callback procedure of the type MaDirective

API Stability:
  Stable.

See Also:
  Http, maAddServer, maApplyChangedGroup, maApplyChangedUser, maCreateAppweb, maGetUserGroup, maLoadModule, maLookupServer, maParseInit, maParsePlatform, maRenderDirListing, maSetDefaultServer, maSetHttpGroup, maSetHttpUser, maStartAppweb, maStopAppweb

void maAddEndpoint (MaServer *server, HttpEndpoint *endpoint)

Add a listening endpoint.

Parameters:

  server | Server object to modify.
  endpoint | Listening endpoint to add to the server.

API Stability:
  Stable.

See Also:
  Http, maAddServer, maApplyChangedGroup, maApplyChangedUser, maCreateAppweb, maGetUserGroup, maLoadModule, maLookupServer, maParseInit, maParsePlatform, maRenderDirListing, maSetDefaultServer, maSetHttpGroup, maSetHttpUser, maStartAppweb, maStopAppweb

void maAddServer (MaAppweb *appweb, struct MaServer *server)

Add a server.

Description:
  Add a server to the list of appweb managed web servers.

Parameters:

  appweb | Appweb object created via maCreateAppweb
  server | MaServer object.

Returns:
  Zero if successful, otherwise a negative Mpr error code. See the Appweb log for diagnostics.

API Stability:
  Stable.

See Also:
  Http, maApplyChangedGroup, maApplyChangedUser, maCreateAppweb, maGetUserGroup, maLoadModule, maLookupServer, maParseInit, maParsePlatform, maRenderDirListing, maSetDefaultServer, maSetHttpGroup, maSetHttpUser, maStartAppweb, maStopAppweb

int maApplyChangedGroup (MaAppweb *appweb)

Apply the changed Appweb group ID.

Description:
  Apply configuration changes and actually change the Appweb group id.

Parameters:

  appweb | Appweb object created via maCreateAppweb

Returns:
  Zero if successful, otherwise a negative Mpr error code. See the Appweb log for diagnostics.

API Stability:
  Stable.

See Also:
  Http, maAddServer, maApplyChangedUser, maCreateAppweb, maGetUserGroup, maLoadModule, maLookupServer, maParseInit, maParsePlatform, maRenderDirListing, maSetDefaultServer, maSetHttpGroup, maSetHttpUser, maStartAppweb, maStopAppweb

int maApplyChangedUser (MaAppweb *appweb)

Apply the changed Appweb user ID.

Description:
  Apply configuration changes and actually change the Appweb user id.

Parameters:

  appweb | Appweb object created via maCreateAppweb

API Stability:
  Stable.

See Also:
  Http, maAddServer, maApplyChangedGroup, maCreateAppweb, maGetUserGroup, maLoadModule, maLookupServer, maParseInit, maParsePlatform, maRenderDirListing, maSetDefaultServer, maSetHttpGroup, maSetHttpUser, maStartAppweb, maStopAppweb

int maArchiveLog (cchar *path, int count, int maxSize)

Archive a log file.

Description:
  The current log file is archived by appending ".1" to the log path name. If a "path.1" exists, it will be renamed first to "path.2" and so on up to "path.count".

Parameters:

  path | Current log file name.
  count | Number of archived log files to preserve.
  maxSize | Reserved.

Returns:
  Zero if successful, otherwise a negative Mpr error code. See the Appweb log for diagnostics.

API Stability:
  Stable.

See Also:
  Http, maAddServer, maApplyChangedGroup, maApplyChangedUser, maCreateAppweb, maGetUserGroup, maLoadModule, maLookupServer, maParseInit, maParsePlatform, maRenderDirListing, maSetDefaultServer, maSetHttpGroup, maSetHttpUser, maStartAppweb, maStopAppweb

MaAppweb * maCreateAppweb ()

Create the Appweb object.

Description:
  Appweb uses a singleton Appweb object to manage multiple web servers instances.

Returns:
  A Http object. Use mprFree to close and release.

API Stability:
  Stable.

See Also:
  Http, maAddServer, maApplyChangedGroup, maApplyChangedUser, maGetUserGroup, maLoadModule, maLookupServer, maParseInit, maParsePlatform, maRenderDirListing, maSetDefaultServer, maSetHttpGroup, maSetHttpUser, maStartAppweb, maStopAppweb

void maGetUserGroup (MaAppweb *appweb)

Get the user group.

Description:
  Get the user name and ID for appweb and update the MaAppweb object.

Parameters:

  appweb | Appweb object created via maCreateAppweb

API Stability:
  Internal.

See Also:
  Http, maAddServer, maApplyChangedGroup, maApplyChangedUser, maCreateAppweb, maLoadModule, maLookupServer, maParseInit, maParsePlatform, maRenderDirListing, maSetDefaultServer, maSetHttpGroup, maSetHttpUser, maStartAppweb, maStopAppweb

int maLoadModule (MaAppweb *appweb, cchar *name, cchar *libname)

Load an appweb module.

Description:
  Load an appweb module. If the module is already loaded, this call will return successfully without reloading. Modules can be dynamically loaded or may also be pre-loaded using static linking.

Parameters:

  appweb | Appweb object created via maCreateAppweb
  name | User name. Must be defined in the system password file.
  libname | Library path name.

Returns:
  Zero if successful, otherwise a negative Mpr error code. See the Appweb log for diagnostics.

API Stability:
  Stable.

See Also:
  Http, maAddServer, maApplyChangedGroup, maApplyChangedUser, maCreateAppweb, maGetUserGroup, maLookupServer, maParseInit, maParsePlatform, maRenderDirListing, maSetDefaultServer, maSetHttpGroup, maSetHttpUser, maStartAppweb, maStopAppweb

struct MaServer * MaServer* maLookupServer (MaAppweb *appweb, cchar *name)

Lookup a server.

Description:
  Lookup a server by name and return the MaServer object.

Parameters:

  appweb | Appweb object created via maCreateAppweb
  name | Server name.

Returns:
  MaServer object.

API Stability:
  Stable.

See Also:
  Http, maAddServer, maApplyChangedGroup, maApplyChangedUser, maCreateAppweb, maGetUserGroup, maLoadModule, maParseInit, maParsePlatform, maRenderDirListing, maSetDefaultServer, maSetHttpGroup, maSetHttpUser, maStartAppweb, maStopAppweb

int maParseConfig (MaServer *server, cchar *path, int flags)

Parse an Appweb configuration file.

Description:
  Parse the configuration file and configure the server. This creates a default host and route and then configures the server based on config file directives.

Parameters:

  server | MaServer object created via maCreateServer
  path | Configuration file pathname.
  flags | Parse control flags. Reserved. Set to zero.

Returns:
  Zero if successful, otherwise a negative Mpr error code. See the Appweb log for diagnostics.

API Stability:
  Stable.

See Also:
  Http, maAddServer, maApplyChangedGroup, maApplyChangedUser, maCreateAppweb, maGetUserGroup, maLoadModule, maLookupServer, maParseInit, maParsePlatform, maRenderDirListing, maSetDefaultServer, maSetHttpGroup, maSetHttpUser, maStartAppweb, maStopAppweb

int maParseInit (MaAppweb *appweb)

Initialize the config file parser.

Parameters:

  appweb | Appweb object created via maCreateAppweb

Returns:
  Zero if successful, otherwise a negative Mpr error code. See the Appweb log for diagnostics.

API Stability:
  Internal.

See Also:
  Http, maAddServer, maApplyChangedGroup, maApplyChangedUser, maCreateAppweb, maGetUserGroup, maLoadModule, maLookupServer, maParsePlatform, maRenderDirListing, maSetDefaultServer, maSetHttpGroup, maSetHttpUser, maStartAppweb, maStopAppweb

int maParsePlatform (cchar *platform, cchar **os, cchar **arch, cchar **profile)

Parse a platform string.

Parameters:

  platform | The platform string. Must be of the form: os-arch-profile.
  os | Parsed O/S portion.
  arch | Parsed architecture portion.
  profile | Parsed profile portion.

Returns:
  Zero if successful, otherwise a negative Mpr error code.

API Stability:
  Internal.

See Also:
  Http, maAddServer, maApplyChangedGroup, maApplyChangedUser, maCreateAppweb, maGetUserGroup, maLoadModule, maLookupServer, maParseInit, maRenderDirListing, maSetDefaultServer, maSetHttpGroup, maSetHttpUser, maStartAppweb, maStopAppweb

MaState * maPopState (MaState *state)

Pop the state.

Description:
  This is used when parsing config files to handle nested include files and block level directives.

Parameters:

  state | Current state.

Returns:
  The next lower level state object.

API Stability:
  Stable.

See Also:
  Http, maAddServer, maApplyChangedGroup, maApplyChangedUser, maCreateAppweb, maGetUserGroup, maLoadModule, maLookupServer, maParseInit, maParsePlatform, maRenderDirListing, maSetDefaultServer, maSetHttpGroup, maSetHttpUser, maStartAppweb, maStopAppweb

MaState * maPushState (MaState *state)

Push the state.

Description:
  This is used when parsing config files to handle nested include files and block level directives.

Parameters:

  state | Current state.

Returns:
  The state passed as a parameter which becomes the new top level state.

API Stability:
  Stable.

See Also:
  Http, maAddServer, maApplyChangedGroup, maApplyChangedUser, maCreateAppweb, maGetUserGroup, maLoadModule, maLookupServer, maParseInit, maParsePlatform, maRenderDirListing, maSetDefaultServer, maSetHttpGroup, maSetHttpUser, maStartAppweb, maStopAppweb

bool maRenderDirListing (HttpConn *conn)

Test if a directory listing should be rendered for the request.

Parameters:

  conn | Connection object.

Returns:
  True if a directory listing is configured to be rendered for this request.

API Stability:
  Internal.

See Also:
  Http, maAddServer, maApplyChangedGroup, maApplyChangedUser, maCreateAppweb, maGetUserGroup, maLoadModule, maLookupServer, maParseInit, maParsePlatform, maSetDefaultServer, maSetHttpGroup, maSetHttpUser, maStartAppweb, maStopAppweb

void maSetAccessLog (HttpRoute *route, cchar *path, cchar *format)

Define the access log.

Description:
  The access log is used to log details about requests to the web server. Errors are logged in the error log.

Parameters:

  route | HttpRoute object for which to define the logging characteristics.
  path | Pathname for the log file.

  format

  Log file format. The format string argument defines how Appweb will record HTTP accesses to the access log. The following log format specifiers are supported:
  - %% - Percent sign
  - %a - Remote IP address
  - %b - Response bytes written to the client include headers. If zero, "-" is written.
  - %B - Response bytes written excluding headers
  - %h - Remote hostname
  - %O - Bytes written include headers. If zero bytes, "0" is written.
  - %r - First line of the request
  - %s - HTTP response status code
  - %t - Time the request was completed
  - %u - Authenticated username
  - %{header}i - HTTP header value

API Stability:
  Stable.

See Also:
  Http, maAddServer, maApplyChangedGroup, maApplyChangedUser, maCreateAppweb, maGetUserGroup, maLoadModule, maLookupServer, maParseInit, maParsePlatform, maRenderDirListing, maSetDefaultServer, maSetHttpGroup, maSetHttpUser, maStartAppweb, maStopAppweb

void maSetDefaultServer (MaAppweb *appweb, struct MaServer *server)

Set the default server.

Parameters:

  appweb | Appweb object created via maCreateAppweb
  server | MaServer object.

API Stability:
  Internal.

See Also:
  Http, maAddServer, maApplyChangedGroup, maApplyChangedUser, maCreateAppweb, maGetUserGroup, maLoadModule, maLookupServer, maParseInit, maParsePlatform, maRenderDirListing, maSetHttpGroup, maSetHttpUser, maStartAppweb, maStopAppweb

int maSetHttpGroup (MaAppweb *appweb, cchar *group)

Set the Http Group.

Description:
  Define the group name under which to run the Appweb service.

Parameters:

  appweb | Appweb object created via maCreateAppweb
  group | Group name. Must be defined in the system group file.

Returns:
  Zero if successful, otherwise a negative Mpr error code. See the Appweb log for diagnostics.

API Stability:
  Stable.

See Also:
  Http, maAddServer, maApplyChangedGroup, maApplyChangedUser, maCreateAppweb, maGetUserGroup, maLoadModule, maLookupServer, maParseInit, maParsePlatform, maRenderDirListing, maSetDefaultServer, maSetHttpUser, maStartAppweb, maStopAppweb

int maSetHttpUser (MaAppweb *appweb, cchar *user)

Set the Http User.

Description:
  Define the user name under which to run the Appweb service.

Parameters:

  appweb | Appweb object created via maCreateAppweb
  user | User name. Must be defined in the system password file.

Returns:
  Zero if successful, otherwise a negative Mpr error code. See the Appweb log for diagnostics.

API Stability:
  Stable.

See Also:
  Http, maAddServer, maApplyChangedGroup, maApplyChangedUser, maCreateAppweb, maGetUserGroup, maLoadModule, maLookupServer, maParseInit, maParsePlatform, maRenderDirListing, maSetDefaultServer, maSetHttpGroup, maStartAppweb, maStopAppweb

void maSetServerAddress (MaServer *server, cchar *ip, int port)

Set the server listen address.

Description:
  Set the internet addresses for all endpoints managed by the server.

Parameters:

  server | MaServer object created via maCreateServer
  ip | IP address to set for the server.
  port | Port number to use for the server.

API Stability:
  Stable.

See Also:
  Http, maAddServer, maApplyChangedGroup, maApplyChangedUser, maCreateAppweb, maGetUserGroup, maLoadModule, maLookupServer, maParseInit, maParsePlatform, maRenderDirListing, maSetDefaultServer, maSetHttpGroup, maSetHttpUser, maStartAppweb, maStopAppweb

int maStartAccessLogging (HttpRoute *route)

Start access logging.

Description:
  Start access logging for a host.

Parameters:

  route | HttpRoute object.

Returns:
  Zero if successful, otherwise a negative Mpr error code. See the Appweb log for diagnostics.

API Stability:
  Stable.

See Also:
  Http, maAddServer, maApplyChangedGroup, maApplyChangedUser, maCreateAppweb, maGetUserGroup, maLoadModule, maLookupServer, maParseInit, maParsePlatform, maRenderDirListing, maSetDefaultServer, maSetHttpGroup, maSetHttpUser, maStartAppweb, maStopAppweb

int maStartAppweb (MaAppweb *appweb)

Start Appweb services.

Description:
  This starts listening for requests on all configured servers.

Parameters:

  appweb | Appweb object created via maCreateAppweb

Returns:
  Zero if successful, otherwise a negative Mpr error code. See the Appweb log for diagnostics.

API Stability:
  Stable.

See Also:
  Http, maAddServer, maApplyChangedGroup, maApplyChangedUser, maCreateAppweb, maGetUserGroup, maLoadModule, maLookupServer, maParseInit, maParsePlatform, maRenderDirListing, maSetDefaultServer, maSetHttpGroup, maSetHttpUser, maStopAppweb

int maStartServer (MaServer *server)

Start a server.

Parameters:

  server | Object created via maCreateServer

Returns:
  Zero if successful, otherwise a negative Mpr error code. See the Appweb log for diagnostics.

API Stability:
  Stable.

See Also:
  Http, maAddServer, maApplyChangedGroup, maApplyChangedUser, maCreateAppweb, maGetUserGroup, maLoadModule, maLookupServer, maParseInit, maParsePlatform, maRenderDirListing, maSetDefaultServer, maSetHttpGroup, maSetHttpUser, maStartAppweb, maStopAppweb

void maStopAccessLogging (HttpRoute *route)

Stop access logging.

Parameters:

  route | HttpRoute object.

API Stability:
  Stable.

See Also:
  Http, maAddServer, maApplyChangedGroup, maApplyChangedUser, maCreateAppweb, maGetUserGroup, maLoadModule, maLookupServer, maParseInit, maParsePlatform, maRenderDirListing, maSetDefaultServer, maSetHttpGroup, maSetHttpUser, maStartAppweb, maStopAppweb

int maStopAppweb (MaAppweb *appweb)

Stop Appweb services.

Description:
  This stops listening for requests on all configured servers. Shutdown is somewhat graceful.

Parameters:

  appweb | Appweb object created via maCreateAppweb

Returns:
  Zero if successful, otherwise a negative Mpr error code. See the Appweb log for diagnostics.

API Stability:
  Stable.

See Also:
  Http, maAddServer, maApplyChangedGroup, maApplyChangedUser, maCreateAppweb, maGetUserGroup, maLoadModule, maLookupServer, maParseInit, maParsePlatform, maRenderDirListing, maSetDefaultServer, maSetHttpGroup, maSetHttpUser, maStartAppweb

void maStopServer (MaServer *server)

Stop a server.

Parameters:

  server | Object created via maCreateServer

API Stability:
  Stable.

See Also:
  Http, maAddServer, maApplyChangedGroup, maApplyChangedUser, maCreateAppweb, maGetUserGroup, maLoadModule, maLookupServer, maParseInit, maParsePlatform, maRenderDirListing, maSetDefaultServer, maSetHttpGroup, maSetHttpUser, maStartAppweb, maStopAppweb

bool maTokenize (MaState *state, cchar *str, cchar *fmt, ...)

Tokenize a string based on route data.

Description:
  This is a utility routine to parse a string into tokens given a format specifier. Mandatory tokens can be specified with "%" format specifier. Optional tokens are specified with "?" format. Values wrapped in quotes will have the outermost quotes trimmed.

Parameters:

  state | Current config parsing state.
  str | String to expand.

  fmt

  Format string specifier Supported tokens:
  - B - Boolean. Parses: on/off, true/false, yes/no.
  - N - Number. Parses numbers in base 10.
  - S - String. Removes quotes.
  - P - Path string. Removes quotes and expands ${PathVars}. Resolved relative to host->dir (ServerRoot).
  - W - Parse words into a list
  - %! - Optional negate. Set value to HTTP_ROUTE_NOT present, otherwise zero.

Returns:
  True if the string can be successfully parsed.

API Stability:
  Stable.

See Also:
  Http, maAddServer, maApplyChangedGroup, maApplyChangedUser, maCreateAppweb, maGetUserGroup, maLoadModule, maLookupServer, maParseInit, maParsePlatform, maRenderDirListing, maSetDefaultServer, maSetHttpGroup, maSetHttpUser, maStartAppweb, maStopAppweb

bool maValidateServer (MaServer *server)

Validate the configuration of a server.

Parameters:

  server | Server object to validate.

Returns:
  True if the configuration is valid.

API Stability:
  Stable.

See Also:
  Http, maAddServer, maApplyChangedGroup, maApplyChangedUser, maCreateAppweb, maGetUserGroup, maLoadModule, maLookupServer, maParseInit, maParsePlatform, maRenderDirListing, maSetDefaultServer, maSetHttpGroup, maSetHttpUser, maStartAppweb, maStopAppweb

# MaServer

MaServer

Appweb server object.

Description:
  An application may have any number of HTTP servers, each managed by an MaServer instance.

API Stability:
  Evolving.

See Also:
  maAddEndpoint, maConfigureServer, maCreateServer, maParseConfig, maRunSimpleWebServer, maRunWebServer, maSetServerAddress, maStartServer, maStopServer, maValidateServer

API Stability:
  Internal.

Fields:

  MaAppweb * |  | appweb | Appweb control object.
  HttpHost * |  | defaultHost | Default host for this server.
  MprList * |  | endpoints | List of HttpEndpoints.
  Http * |  | http | Http service object (copy of appweb->http).
  HttpLimits * |  | limits | Limits for this server.
  char * |  | name | Unique name for this server.

int maConfigureServer (MaServer *server, cchar *configFile, cchar *home, cchar *documents, cchar *ip, int port)

Configure a web server.

Description:
  This will configure a web server based on either a configuration file or using the supplied IP address and port.

Parameters:

  server | MaServer object created via maCreateServer
  configFile | File name of the Appweb configuration file (appweb.conf) that defines the web server configuration.
  home | Admin directory for the server. This overrides the value in the config file.
  documents | Default directory for web documents to serve. This overrides the value in the config file.
  ip | IP address to listen on. This overrides the value specified in the config file.
  port | Port address to listen on. This overrides the value specified in the config file.

Returns:
  Zero if successful, otherwise a negative Mpr error code. See the Appweb log for diagnostics.

API Stability:
  Stable.

See Also:
  MaServer, maAddEndpoint, maCreateServer, maParseConfig, maRunSimpleWebServer, maRunWebServer, maSetServerAddress, maStartServer, maStopServer, maValidateServer

MaServer * maCreateServer (MaAppweb *appweb, cchar *name)

Create a MaServer object.

Description:
  Create new MaServer object. This routine creates a bare MaServer object, loads any required static modules and performs minimal configuration. To use the server object created, more configuration will be required before starting Http services. If you want a one-line embedding of Appweb, use maRunWebServer or maRunSimpleWebServer

Parameters:

  appweb | Http object returned from maCreateAppweb
  name | Name of the web server. This name is used as the initial server name.

Returns:
  MaServer A newly created MaServer object. Use mprFree to free and release.

API Stability:
  Stable.

See Also:
  MaServer, maAddEndpoint, maConfigureServer, maParseConfig, maRunSimpleWebServer, maRunWebServer, maSetServerAddress, maStartServer, maStopServer, maValidateServer

HttpAuth * maGetDefaultAuth (MaServer *server)

Get the default authentication object for the server.

Description:
  The server has a default host, which in turn has a default route. Each route has an authentication object to control access to server resources. This call retrieves that authentication object for use with the HttpAuth APIs.

Parameters:

  server | MaServer object.

Returns:
  HttpAuth object.

API Stability:
  Stable.

See Also:
  MaServer, maAddEndpoint, maConfigureServer, maCreateServer, maParseConfig, maRunSimpleWebServer, maRunWebServer, maSetServerAddress, maStartServer, maStopServer, maValidateServer

int maRunSimpleWebServer (cchar *ip, int port, cchar *home, cchar *documents)

Create and run a simple web server listening on a single IP address.

Description:
  Create a simple web server without using a configuration file. The server is created to listen on the specified IP address and port. This routine provides a one-line embedding of Appweb. If you want to use a config file, try the maRunWebServer instead.

Parameters:

  ip | IP address on which to listen. Set to "0.0.0.0" to listen on all interfaces.
  port | Port number to listen to.
  home | Home directory for the web server.
  documents | Directory containing the documents to serve.

Returns:
  Zero if successful, otherwise a negative Mpr error code. See the Appweb log for diagnostics.

API Stability:
  Stable.

See Also:
  MaServer, maAddEndpoint, maConfigureServer, maCreateServer, maParseConfig, maRunWebServer, maSetServerAddress, maStartServer, maStopServer, maValidateServer

int maRunWebClient (cchar *method, cchar *uri, char **response)

Run a web client request.

Description:
  Create a web server configuration based on the supplied config file. This routine provides a one-line embedding of Appweb. If you don't want to use a config file, try the maRunSimpleWebServer instead.

Parameters:

  method | HTTP method to use. GET, POST, PUT, DELETE etc.
  uri | HTTP URI to request.
  response | String reference to receive the response body.

Returns:
  Positive HTTP response code if the request completes. Otherwise a negative MPR error code.

API Stability:
  Prototype.

See Also:
  MaServer, maAddEndpoint, maConfigureServer, maCreateServer, maParseConfig, maRunSimpleWebServer, maRunWebServer, maSetServerAddress, maStartServer, maStopServer, maValidateServer

int maRunWebServer (cchar *configFile)

Create and run a web server based on a configuration file.

Description:
  Create a web server configuration based on the supplied config file. This routine provides a one-line embedding of Appweb. If you don't want to use a config file, try the maRunSimpleWebServer instead.

Parameters:

  configFile | File name of the Appweb configuration file (appweb.conf) that defines the web server configuration.

Returns:
  Zero if successful, otherwise a negative Mpr error code. See the Appweb log for diagnostics.

API Stability:
  Stable.

See Also:
  MaServer, maAddEndpoint, maConfigureServer, maCreateServer, maParseConfig, maRunSimpleWebServer, maSetServerAddress, maStartServer, maStopServer, maValidateServer

# MaState

MaState

Current configuration parse state.

API Stability:
  Evolving.

See Also:
  MaDirective, maAddDirective, maArchiveLog, maPopState, maPushState, maSetAccessLog, maStartAccessLogging, maStopAccessLogging, maTokenize

API Stability:
  Internal.

Fields:

  HttpAuth * |  | auth | Quick alias for route->auth.
  char * |  | configDir | Directory containing config file.
  struct MaState * |  | current | Current state.
  int |  | enabled | True if the current block is enabled.
  MprFile * |  | file | Config file handle.
  char * |  | filename | Config file name.
  int |  | flags | Parsing flags.
  HttpHost * |  | host | Current host.
  char * |  | key | Current directive being parsed.
  HttpLimits * |  | limits | Current limits (host->limits).
  int |  | lineNumber | Current line number.
  struct MaState * |  | prev | Previous (inherited) state.
  HttpRoute * |  | route | Current route.
  MaServer * |  | server | Current server.
  struct MaState * |  | top | Top level state.

## Functions

## Typedefs

typedef int( MaDirective)(MaState *state, cchar *key, cchar *value).

Appweb configuration file directive parsing callback function.

Description:
  Directive callbacks are invoked to parse a directive. Directive callbacks are registered using maAddDirective

Parameters:

  state | Current config parse state.
  key | Directive key name.
  value | Directive key value.

Returns:
  Zero if successful, otherwise a negative Mpr error code. See the Appweb log for diagnostics.

API Stability:
  Stable.

See Also:
  Http, maAddServer, maApplyChangedGroup, maApplyChangedUser, maCreateAppweb, maGetUserGroup, maLoadModule, maLookupServer, maParseInit, maParsePlatform, maRenderDirListing, maSetDefaultServer, maSetHttpGroup, maSetHttpUser, maStartAppweb, maStopAppweb