You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@celix.apache.org by pn...@apache.org on 2018/05/27 18:52:43 UTC
[35/60] [abbrv] [partial] celix git commit: CELIX-424: Cleans up the
directory structure. Moves all libraries to the libs subdir and all bundles
to the bundles subdir
http://git-wip-us.apache.org/repos/asf/celix/blob/3bce889b/bundles/pubsub/test/test/tst_activator.cpp
----------------------------------------------------------------------
diff --git a/bundles/pubsub/test/test/tst_activator.cpp b/bundles/pubsub/test/test/tst_activator.cpp
new file mode 100644
index 0000000..04be892
--- /dev/null
+++ b/bundles/pubsub/test/test/tst_activator.cpp
@@ -0,0 +1,221 @@
+/**
+ *Licensed to the Apache Software Foundation (ASF) under one
+ *or more contributor license agreements. See the NOTICE file
+ *distributed with this work for additional information
+ *regarding copyright ownership. The ASF licenses this file
+ *to you under the Apache License, Version 2.0 (the
+ *"License"); you may not use this file except in compliance
+ *with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *Unless required by applicable law or agreed to in writing,
+ *software distributed under the License is distributed on an
+ *"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ *specific language governing permissions and limitations
+ *under the License.
+ */
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <unistd.h>
+
+#include "bundle_activator.h"
+#include "service_tracker.h"
+
+#include "pubsub/subscriber.h"
+#include "pubsub/publisher.h"
+
+#include "msg.h"
+#include "sync.h"
+
+#include <CppUTest/TestHarness.h>
+#include <CppUTestExt/MockSupport.h>
+#include <constants.h>
+
+
+static int tst_receive(void *handle, const char *msgType, unsigned int msgTypeId, void *msg, pubsub_multipart_callbacks_t *callbacks, bool *release);
+static int tst_pubAdded(void *handle, service_reference_pt reference, void *service);
+static int tst_pubRemoved(void *handle, service_reference_pt reference, void *service);
+
+struct activator {
+ pubsub_subscriber_t subSvc{};
+ service_registration_pt reg = nullptr;
+
+ service_tracker_pt tracker = nullptr;
+
+ pthread_mutex_t mutex{}; //protects below
+ pubsub_publisher_t* pubSvc = nullptr;
+
+ unsigned int syncId = 0;
+ bool gotSync = 0;
+
+ unsigned int msgId = 0;
+ unsigned int count = 0;
+
+ bool started = false;
+
+};
+
+static struct activator g_act; //global
+
+celix_status_t bundleActivator_create(__attribute__((unused)) bundle_context_pt context, __attribute__((unused)) void **userData) {
+ //memset(&g_act, 0, sizeof(g_act));
+ return CELIX_SUCCESS;
+}
+
+celix_status_t bundleActivator_start(__attribute__((unused)) void * userData, bundle_context_pt context) {
+ properties_pt props = properties_create();
+ properties_set(props, "pubsub.topic", "pong");
+ g_act.subSvc.handle = &g_act;
+ g_act.subSvc.receive = tst_receive;
+ bundleContext_registerService(context, PUBSUB_SUBSCRIBER_SERVICE_NAME, &g_act.subSvc, props, &g_act.reg);
+
+ char filter[512];
+ snprintf(filter, 512, "(&(%s=%s)(%s=%s))", OSGI_FRAMEWORK_OBJECTCLASS, PUBSUB_PUBLISHER_SERVICE_NAME, PUBSUB_PUBLISHER_TOPIC, "ping");
+
+ service_tracker_customizer_pt customizer = NULL;
+ serviceTrackerCustomizer_create(&g_act, NULL, tst_pubAdded, NULL, tst_pubRemoved, &customizer);
+ serviceTracker_createWithFilter(context, filter, customizer, &g_act.tracker);
+ serviceTracker_open(g_act.tracker);
+
+ g_act.started = true;
+
+ return CELIX_SUCCESS;
+}
+
+celix_status_t bundleActivator_stop(__attribute__((unused)) void * userData, bundle_context_pt __attribute__((unused)) context) {
+ serviceTracker_close(g_act.tracker);
+ return CELIX_SUCCESS;
+}
+
+celix_status_t bundleActivator_destroy(__attribute__((unused)) void * userData, bundle_context_pt __attribute__((unused)) context) {
+ serviceTracker_destroy(g_act.tracker);
+ return CELIX_SUCCESS;
+}
+
+static int tst_receive(void *handle, const char * /*msgType*/, unsigned int msgTypeId, void * /*msg*/, pubsub_multipart_callbacks_t* /*callbacks*/, bool* /*release*/) {
+ struct activator* act = static_cast<struct activator*>(handle);
+ pthread_mutex_lock(&act->mutex);
+ if (msgTypeId == act->syncId) {
+ act->gotSync = true;
+ } else if (msgTypeId == act->msgId) {
+ act->count += 1;
+ }
+ pthread_mutex_unlock(&act->mutex);
+ return CELIX_SUCCESS;
+}
+
+static int tst_pubAdded(void *handle, service_reference_pt /*reference*/, void *service) {
+ struct activator* act = static_cast<struct activator*>(handle);
+ pthread_mutex_lock(&act->mutex);
+ act->pubSvc = static_cast<pubsub_publisher_t*>(service);
+ act->pubSvc->localMsgTypeIdForMsgType(act->pubSvc->handle, MSG_NAME, &act->msgId);
+ act->pubSvc->localMsgTypeIdForMsgType(act->pubSvc->handle, SYNC_NAME, &act->syncId);
+
+ pthread_mutex_unlock(&act->mutex);
+ return CELIX_SUCCESS;
+
+}
+
+static int tst_pubRemoved(void *handle, service_reference_pt /*reference*/, void *service) {
+ struct activator* act = static_cast<struct activator*>(handle);
+ pthread_mutex_lock(&act->mutex);
+ if (act->pubSvc == service) {
+ act->pubSvc = NULL;
+ }
+ pthread_mutex_unlock(&act->mutex);
+ return CELIX_SUCCESS;
+}
+
+
+TEST_GROUP(PUBSUB_INT_GROUP)
+{
+ void setup() {
+ constexpr int TRIES = 25;
+ constexpr int TIMEOUT = 250000;
+
+ pthread_mutex_lock(&g_act.mutex);
+ CHECK_EQUAL(true, g_act.started);
+ g_act.gotSync = false;
+ pthread_mutex_unlock(&g_act.mutex);
+
+ //check if publisher is available
+ unsigned int syncId = 0;
+ for (int i = 0; i < TRIES; ++i) {
+ pthread_mutex_lock(&g_act.mutex);
+ syncId = g_act.syncId;
+ pthread_mutex_unlock(&g_act.mutex);
+ if (syncId == 0) {
+ printf("publisher still nullptr / sync msg type id is still 0, waiting for a while\n");
+ usleep(TIMEOUT);
+ } else {
+ break;
+ }
+ }
+ CHECK(syncId != 0);
+
+ //check if message are returned
+ sync_t syncMsg;
+ bool gotSync = false;
+ for (int i = 0; i < TRIES; ++i) {
+ printf("Sending sync message. Try %d/%d\n", i+1, TRIES);
+ pthread_mutex_lock(&g_act.mutex);
+ g_act.pubSvc->send(g_act.pubSvc->handle, g_act.syncId, &syncMsg);
+ pthread_mutex_unlock(&g_act.mutex);
+ usleep(TIMEOUT);
+ pthread_mutex_lock(&g_act.mutex);
+ gotSync = g_act.gotSync;
+ pthread_mutex_unlock(&g_act.mutex);
+ if (gotSync) {
+ break;
+ }
+ }
+ if (!gotSync) {
+ printf("No sync message received, bailing\n");
+ }
+ CHECK(gotSync);
+ }
+
+ void teardown() {
+ //nop
+ }
+};
+
+TEST(PUBSUB_INT_GROUP, sendRecvTest) {
+ pthread_mutex_lock(&g_act.mutex);
+ g_act.count = 0; //reset counter
+ pthread_mutex_unlock(&g_act.mutex);
+
+ constexpr int COUNT = 50;
+ msg_t msg;
+ for (int i = 0; i < COUNT; ++i) {
+ msg.seqNr = i+1;
+ printf("Sending test msg %d of %d\n", i+1, COUNT);
+ pthread_mutex_lock(&g_act.mutex);
+ g_act.pubSvc->send(g_act.pubSvc->handle, g_act.msgId, &msg);
+ pthread_mutex_unlock(&g_act.mutex);
+ usleep(100000);
+ }
+
+ constexpr int TRIES = 25;
+ constexpr int TIMEOUT = 250000;
+ for (int i = 0; i < TRIES; ++i) {
+ pthread_mutex_lock(&g_act.mutex);
+ int count = g_act.count;
+ pthread_mutex_unlock(&g_act.mutex);
+ if (count == COUNT) {
+ break;
+ } else {
+ printf("Current count is %i, should be %i. Waiting a little\n", count, COUNT);
+ usleep(TIMEOUT);
+ }
+ }
+
+ pthread_mutex_lock(&g_act.mutex);
+ int count = g_act.count;
+ pthread_mutex_unlock(&g_act.mutex);
+ CHECK_EQUAL(COUNT, count);
+}
http://git-wip-us.apache.org/repos/asf/celix/blob/3bce889b/bundles/remote_services/CMakeLists.txt
----------------------------------------------------------------------
diff --git a/bundles/remote_services/CMakeLists.txt b/bundles/remote_services/CMakeLists.txt
new file mode 100644
index 0000000..991d94a
--- /dev/null
+++ b/bundles/remote_services/CMakeLists.txt
@@ -0,0 +1,40 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+celix_subproject(REMOTE_SERVICE_ADMIN "Option to enable building the Remote Service Admin Service bundles" OFF)
+if (REMOTE_SERVICE_ADMIN)
+ add_subdirectory(remote_services_api)
+ add_subdirectory(examples)
+
+ add_subdirectory(rsa_spi)
+ add_subdirectory(rsa_common)
+ add_subdirectory(civetweb)
+
+ add_subdirectory(topology_manager)
+
+ add_subdirectory(discovery_common)
+ add_subdirectory(discovery_configured)
+ add_subdirectory(discovery_etcd)
+ add_subdirectory(discovery_shm)
+
+ #TODO refactor shm rsa to use dfi
+ #add_subdirectory(remote_service_admin_shm)
+ add_subdirectory(remote_service_admin_dfi)
+
+endif (REMOTE_SERVICE_ADMIN)
+
+
http://git-wip-us.apache.org/repos/asf/celix/blob/3bce889b/bundles/remote_services/README.md
----------------------------------------------------------------------
diff --git a/bundles/remote_services/README.md b/bundles/remote_services/README.md
new file mode 100644
index 0000000..15365b2
--- /dev/null
+++ b/bundles/remote_services/README.md
@@ -0,0 +1,166 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements. See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+
+Title: Apache Celix Remote Service Admin Service
+
+## Introduction
+
+The Remote Service Admin Service subproject contains an adapted implementation of the OSGi Enterprise Remote Service Admin Service Specification. The subproject consists of three parts, each described in more detail in the following sections.
+
+### Topology Manager
+
+The topology manager decides which services should be imported and exported according to a defined policy. Currently, only one policy is implemented in Celix, the *promiscuous* policy, which simply imports and exports all services.
+
+| **Bundle** | `topology_manager.zip` |
+|--|--|
+| **Configuration** | *None* |
+
+### Remote Service Admin
+
+The Remote Service Admin (RSA) provides the mechanisms to import and export services when instructed to do so by the Topology Manager.
+
+#### Endpoints and proxies
+
+To delegate a *received* method call to the actual service implementation, the RSA uses an "endpoint" bundle, which has all the knowledge about the marshalling and unmarshalling of data for the service. This endpoint bundle is specific to the used RSA implementation, and as such cannot be reused between various RSA implementations.
+
+Invoking a *remote* method is done by using "proxy" bundles. Similar as to endpoints, proxy bundles encapsulate all knowledge to marshall and unmarshall data for a remote method call and as such can not be shared between RSA implementations.
+
+Both proxy and endpoint bundles are loaded on demand when a service is imported or exported by the RSA. As such, these bundles **must** not be added to the list of "auto started" bundles, but placed in a separate location. By default, `endpoints` is used as location for locating proxy and/or endpoint bundles.
+
+Note that since endpoints and proxies need to be created manually, one has full control about the handling of specifics of marshalling and unmarshalling data and dealing with exceptions.
+
+#### HTTP/JSON
+
+Provides a RSA implementation that uses JSON to marshal requests and HTTP as transport mechanism for its remote method invocation. It is compatible with the *Remote Service Admin HTTP* implementation provided by [Amdatu Remote](https://amdatu.atlassian.net/wiki/display/AMDATUDEV/Amdatu+Remote).
+
+| **Bundle** | `remote_service_admin_http.zip` |
+|--|--|
+| **Configuration** | `RSA_PORT`: defines the port on which the HTTP server should listen for incoming requests. Defaults to port `8888`; |
+| | `ENDPOINTS`: defines the location in which service endpoints and/or proxies can be found. Defaults to `endpoints` in the current working directory |
+
+#### Shared memory (SHM)
+
+Provides a RSA implementation that uses shared memory for its remote method invocation. Note that this only works when all remote services are located on the same machine.
+
+| **Bundle** | `remote_service_admin_shm.zip` |
+|--|--|
+| **Configuration** | `ENDPOINTS`: defines the location in which service endpoints and/or proxies can be found. Defaults to `endpoints` in the current working directory |
+
+### Discovery
+
+Actively discovers the presence of remote exported services and provides information about local exported services, as given by the Topology Manager, to others.
+
+#### Shared memory (SHM) based discovery
+
+Provides service discovery for the RSA SHM implementation.
+
+| **Bundle** | `discovery_shm.zip` |
+|--|--|
+| **Configuration** | *None* |
+
+#### Configured discovery
+
+Provides a service discovery with preconfigured discovery endpoints, allowing a static mesh of nodes for remote service invocation to be created. The configured discovery bundle in Celix is compatible with the configured discovery implementation provided by [Amdatu Remote](https://amdatu.atlassian.net/wiki/display/AMDATUDEV/Amdatu+Remote).
+
+| **Bundle** | `discovery_configured.zip` |
+|--|--|
+| **Configuration** | `DISCOVERY_CFG_POLL_ENDPOINTS`: defines a comma-separated list of discovery endpoints that should be used to query for remote services. Defaults to `http://localhost:9999/org.apache.celix.discovery.configured`; |
+| | `DISCOVERY_CFG_POLL_INTERVAL`: defines the interval (in seconds) in which the discovery endpoints should be polled. Defaults to `10` seconds. |
+| | `DISCOVERY_CFG_SERVER_PORT`: defines the port on which the HTTP server should listen for incoming requests from other configured discovery endpoints. Defaults to port `9999`; |
+| | `DISCOVERY_CFG_SERVER_PATH`: defines the path on which the HTTP server should accept requests from other configured discovery endpoints. Defaults to `/org.apache.celix.discovery.configured`. |
+
+Note that for configured discovery, the "Endpoint Description Extender" XML format defined in the OSGi Remote Service Admin specification (section 122.8 of OSGi Enterprise 5.0.0) is used.
+
+See [etcd discovery](discovery_etcd/README.md)
+
+#### etcd discovery
+
+| **Bundle** | `discovery_etcd.zip` |
+
+Provides a service discovery using etcd distributd key/value store.
+
+See [etcd discovery](discovery_etcd/README.md)
+
+## Usage
+
+To develop for the Remote Service Admin implementation of Celix, one needs the following:
+
+1. A service **interface**, describes the actual service and methods[^1] that can be called. The service interface is needed at development time to allow a consistent definition;
+2. A service **implementation**, when exporting it as remote service. A service endpoint is needed to delegate remote requests to your service implementation;
+3. A service **endpoint**, which will be installed by Celix when exporting a local service. The endpoint is responsible for calling the actual Celix service. Endpoint bundles are not needed when *only* importing services in Celix;
+4. A service **proxy**, which will be installed by Celix when importing a remote service. The proxy is responsible for marshalling and unmarshalling method invocations. Proxy bundles are not needed when *only* exposing services from Celix;
+5. A service **client** or user, which invokes methods on the local or remote service. The client is oblivious to the fact whether the service is running locally or remote.
+
+The Celix source repository provides a simple calculator example that shows all of the described parts:
+
+1. [The calculator service interface](http://svn.apache.org/repos/asf/celix/trunk/remote_services/calculator_service/public/include/calculator_service.h), providing three methods: one for adding two numbers, one for subtracting two numbers, and lastly, a method that calculates the square root of a number;
+2. [A calculator service implementation](http://svn.apache.org/repos/asf/celix/trunk/remote_services/calculator_service/private/src/calculator_impl.c) that simply implements the three previously described functions. To mark this service as "remote service", you need to add the `service.exported.interfaces` service property to its service registration. This way, the RSA implementation can expose it as remote service to others;
+3. [A service endpoint](http://svn.apache.org/repos/asf/celix/trunk/remote_services/calculator_endpoint/private/src/calculator_endpoint_impl.c), which is called by the RSA implementation to delegate a method invocation to an actual method in the service implementation. The service endpoint should be registered as `remote_endpoint` service, along with the `remote.interface` service property denoting which service interface this endpoint is capable of handling;
+4. [A service proxy (factory)](http://svn.apache.org/repos/asf/celix/trunk/remote_services/calculator_proxy/private/src/calculator_proxy_impl.c), called by the service client when it wants to invoke a method on a remoted service. The service proxy should be registered as `remote_proxy_factory` service along with the `proxy.interface` service property denoting which service interface the service proxy is capable of handling;
+5. [A service client](http://svn.apache.org/repos/asf/celix/trunk/remote_services/calculator_shell/private/src/add_command.c), that exposes the three calculator methods to as Celix shell commands. The implementation simply retrieves the calculator service as it would do with any other Celix service.
+
+If you have access to the Celix source repository, you can run the calculator example using various discovery implementations by invoking the `deploy` target. You can find the example deployments in the `CELIX_BUILD/deploy` directory. For example, to run the calculator example using the configured discovery mechanism, you should open two terminals. In the first terminal, type:
+
+ remote-service-cfg$ export RSA_PORT=18888
+ remote-service-cfg$ sh run.sh
+ ...
+ RSA: Export services (org.apache.celix.calc.api.Calculator)
+ ...
+ -> _
+
+In the second terminal, type:
+
+ remote-service-cfg-client$ export RSA_PORT=28888
+ remote-service-cfg-client$ sh run.sh
+ ...
+ RSA: Import service org.apache.celix.calc.api.Calculator
+ ...
+ -> _
+
+Now, if all went well, the client (second terminal) has three new shell commands, `add`, `sub` and `sqrt`, which you can use to invoke the calculator service:
+
+ -> add 3 5
+ CALCULATOR_SHELL: Add: 3.000000 + 5.000000 = 8.000000
+ -> _
+
+On the server side (first terminal), you can follow each invocation as well:
+
+ CALCULATOR_ENDPOINT: Handle request "add(DD)D" with data "{"m": "add(DD)D", "a": [3.0, 5.0]}"
+ CALCULATOR: Add: 3.000000 + 5.000000 = 8.000000
+
+Note that the `RSA_PORT` property needs to be unique for at least the client in order to communicate correctly when running the examples on the same machine.
+
+## Building
+
+To build the Remote Service Admin Service the CMake build option "`BUILD_REMOTE_SERVICE_ADMIN`" has to be enabled.
+
+## Dependencies
+
+The Remote Service Admin Service depends on the following subprojects:
+
+- Framework
+- Utils
+
+Also the following libraries are required for building and/or using the Remote Service Admin Service subproject:
+
+- Jansson (build and runtime)
+- cURL (build and runtime)
+
+
+## Notes
+
+[^1]: Although C does not use the term "method", we use this term to align with the terminology used in the RSA specification.
http://git-wip-us.apache.org/repos/asf/celix/blob/3bce889b/bundles/remote_services/civetweb/CMakeLists.txt
----------------------------------------------------------------------
diff --git a/bundles/remote_services/civetweb/CMakeLists.txt b/bundles/remote_services/civetweb/CMakeLists.txt
new file mode 100644
index 0000000..46b9637
--- /dev/null
+++ b/bundles/remote_services/civetweb/CMakeLists.txt
@@ -0,0 +1,26 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+
+add_library(civetweb OBJECT
+ src/civetweb.c
+ src/md5.inl
+)
+target_include_directories(civetweb PUBLIC include)
+
+#Setup target aliases to match external usage
+add_library(Celix::civetweb ALIAS civetweb)
http://git-wip-us.apache.org/repos/asf/celix/blob/3bce889b/bundles/remote_services/civetweb/include/civetweb.h
----------------------------------------------------------------------
diff --git a/bundles/remote_services/civetweb/include/civetweb.h b/bundles/remote_services/civetweb/include/civetweb.h
new file mode 100644
index 0000000..61a8e98
--- /dev/null
+++ b/bundles/remote_services/civetweb/include/civetweb.h
@@ -0,0 +1,657 @@
+/* Copyright (c) 2013-2014 the Civetweb developers
+ * Copyright (c) 2004-2013 Sergey Lyubka
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ */
+
+#ifndef CIVETWEB_HEADER_INCLUDED
+#define CIVETWEB_HEADER_INCLUDED
+
+#ifndef CIVETWEB_VERSION
+#define CIVETWEB_VERSION "1.7"
+#endif
+
+#ifndef CIVETWEB_API
+ #if defined(_WIN32)
+ #if defined(CIVETWEB_DLL_EXPORTS)
+ #define CIVETWEB_API __declspec(dllexport)
+ #elif defined(CIVETWEB_DLL_IMPORTS)
+ #define CIVETWEB_API __declspec(dllimport)
+ #else
+ #define CIVETWEB_API
+ #endif
+ #else
+ #define CIVETWEB_API
+ #endif
+#endif
+
+#include <stdio.h>
+#include <stddef.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif /* __cplusplus */
+
+struct mg_context; /* Handle for the HTTP service itself */
+struct mg_connection; /* Handle for the individual connection */
+
+
+/* This structure contains information about the HTTP request. */
+struct mg_request_info {
+ const char *request_method; /* "GET", "POST", etc */
+ const char *uri; /* URL-decoded URI */
+ const char *http_version; /* E.g. "1.0", "1.1" */
+ const char *query_string; /* URL part after '?', not including '?', or
+ NULL */
+ const char *remote_user; /* Authenticated user, or NULL if no auth
+ used */
+ char remote_addr[48]; /* Client's IP address as a string. */
+ long remote_ip; /* Client's IP address. Deprecated: use remote_addr instead */
+
+ long long content_length; /* Length (in bytes) of the request body,
+ can be -1 if no length was given. */
+ int remote_port; /* Client's port */
+ int is_ssl; /* 1 if SSL-ed, 0 if not */
+ void *user_data; /* User data pointer passed to mg_start() */
+ void *conn_data; /* Connection-specific user data */
+
+ int num_headers; /* Number of HTTP headers */
+ struct mg_header {
+ const char *name; /* HTTP header name */
+ const char *value; /* HTTP header value */
+ } http_headers[64]; /* Maximum 64 headers */
+};
+
+
+/* This structure needs to be passed to mg_start(), to let civetweb know
+ which callbacks to invoke. For a detailed description, see
+ https://github.com/bel2125/civetweb/blob/master/docs/UserManual.md */
+struct mg_callbacks {
+ /* Called when civetweb has received new HTTP request.
+ If the callback returns one, it must process the request
+ by sending valid HTTP headers and a body. Civetweb will not do
+ any further processing. Otherwise it must return zero.
+ Note that since V1.7 the "begin_request" function is called
+ before an authorization check. If an authorization check is
+ required, use a request_handler instead.
+ Return value:
+ 0: civetweb will process the request itself. In this case,
+ the callback must not send any data to the client.
+ 1: callback already processed the request. Civetweb will
+ not send any data after the callback returned. */
+ int (*begin_request)(struct mg_connection *);
+
+ /* Called when civetweb has finished processing request. */
+ void (*end_request)(const struct mg_connection *, int reply_status_code);
+
+ /* Called when civetweb is about to log a message. If callback returns
+ non-zero, civetweb does not log anything. */
+ int (*log_message)(const struct mg_connection *, const char *message);
+
+ /* Called when civetweb initializes SSL library.
+ Parameters:
+ user_data: parameter user_data passed when starting the server.
+ Return value:
+ 0: civetweb will set up the SSL certificate.
+ 1: civetweb assumes the callback already set up the certificate.
+ -1: initializing ssl fails. */
+ int (*init_ssl)(void *ssl_context, void *user_data);
+
+ /* Called when websocket request is received, before websocket handshake.
+ Return value:
+ 0: civetweb proceeds with websocket handshake.
+ 1: connection is closed immediately. */
+ int (*websocket_connect)(const struct mg_connection *);
+
+ /* Called when websocket handshake is successfully completed, and
+ connection is ready for data exchange. */
+ void (*websocket_ready)(struct mg_connection *);
+
+ /* Called when data frame has been received from the client.
+ Parameters:
+ bits: first byte of the websocket frame, see websocket RFC at
+ http://tools.ietf.org/html/rfc6455, section 5.2
+ data, data_len: payload, with mask (if any) already applied.
+ Return value:
+ 1: keep this websocket connection open.
+ 0: close this websocket connection. */
+ int (*websocket_data)(struct mg_connection *, int bits,
+ char *data, size_t data_len);
+
+ /* Called when civetweb is closing a connection. The per-context mutex is
+ locked when this is invoked. This is primarily useful for noting when
+ a websocket is closing and removing it from any application-maintained
+ list of clients. */
+ void (*connection_close)(struct mg_connection *);
+
+ /* Called when civetweb tries to open a file. Used to intercept file open
+ calls, and serve file data from memory instead.
+ Parameters:
+ path: Full path to the file to open.
+ data_len: Placeholder for the file size, if file is served from
+ memory.
+ Return value:
+ NULL: do not serve file from memory, proceed with normal file open.
+ non-NULL: pointer to the file contents in memory. data_len must be
+ initilized with the size of the memory block. */
+ const char * (*open_file)(const struct mg_connection *,
+ const char *path, size_t *data_len);
+
+ /* Called when civetweb is about to serve Lua server page, if
+ Lua support is enabled.
+ Parameters:
+ lua_context: "lua_State *" pointer. */
+ void (*init_lua)(struct mg_connection *, void *lua_context);
+
+ /* Called when civetweb has uploaded a file to a temporary directory as a
+ result of mg_upload() call.
+ Parameters:
+ file_name: full path name to the uploaded file. */
+ void (*upload)(struct mg_connection *, const char *file_name);
+
+ /* Called when civetweb is about to send HTTP error to the client.
+ Implementing this callback allows to create custom error pages.
+ Parameters:
+ status: HTTP error status code.
+ Return value:
+ 1: run civetweb error handler.
+ 0: callback already handled the error. */
+ int (*http_error)(struct mg_connection *, int status);
+
+ /* Called after civetweb context has been created, before requests
+ are processed.
+ Parameters:
+ ctx: context handle */
+ void (*init_context)(struct mg_context * ctx);
+
+ /* Called when civetweb context is deleted.
+ Parameters:
+ ctx: context handle */
+ void (*exit_context)(struct mg_context * ctx);
+};
+
+
+/* Start web server.
+
+ Parameters:
+ callbacks: mg_callbacks structure with user-defined callbacks.
+ options: NULL terminated list of option_name, option_value pairs that
+ specify Civetweb configuration parameters.
+
+ Side-effects: on UNIX, ignores SIGCHLD and SIGPIPE signals. If custom
+ processing is required for these, signal handlers must be set up
+ after calling mg_start().
+
+
+ Example:
+ const char *options[] = {
+ "document_root", "/var/www",
+ "listening_ports", "80,443s",
+ NULL
+ };
+ struct mg_context *ctx = mg_start(&my_func, NULL, options);
+
+ Refer to https://github.com/bel2125/civetweb/blob/master/docs/UserManual.md
+ for the list of valid option and their possible values.
+
+ Return:
+ web server context, or NULL on error. */
+CIVETWEB_API struct mg_context *mg_start(const struct mg_callbacks *callbacks,
+ void *user_data,
+ const char **configuration_options);
+
+
+/* Stop the web server.
+
+ Must be called last, when an application wants to stop the web server and
+ release all associated resources. This function blocks until all Civetweb
+ threads are stopped. Context pointer becomes invalid. */
+CIVETWEB_API void mg_stop(struct mg_context *);
+
+
+/* mg_request_handler
+
+ Called when a new request comes in. This callback is URI based
+ and configured with mg_set_request_handler().
+
+ Parameters:
+ conn: current connection information.
+ cbdata: the callback data configured with mg_set_request_handler().
+ Returns:
+ 0: the handler could not handle the request, so fall through.
+ 1: the handler processed the request. */
+typedef int (* mg_request_handler)(struct mg_connection *conn, void *cbdata);
+
+
+/* mg_set_request_handler
+
+ Sets or removes a URI mapping for a request handler.
+
+ URI's are ordered and prefixed URI's are supported. For example,
+ consider two URIs: /a/b and /a
+ /a matches /a
+ /a/b matches /a/b
+ /a/c matches /a
+
+ Parameters:
+ ctx: server context
+ uri: the URI to configure
+ handler: the callback handler to use when the URI is requested.
+ If NULL, the URI will be removed.
+ cbdata: the callback data to give to the handler when it s requested. */
+CIVETWEB_API void mg_set_request_handler(struct mg_context *ctx, const char *uri, mg_request_handler handler, void *cbdata);
+
+
+/* Get the value of particular configuration parameter.
+ The value returned is read-only. Civetweb does not allow changing
+ configuration at run time.
+ If given parameter name is not valid, NULL is returned. For valid
+ names, return value is guaranteed to be non-NULL. If parameter is not
+ set, zero-length string is returned. */
+CIVETWEB_API const char *mg_get_option(const struct mg_context *ctx, const char *name);
+
+
+/* Get context from connection. */
+CIVETWEB_API struct mg_context *mg_get_context(struct mg_connection *conn);
+
+
+/* Get user data passed to mg_start from context. */
+CIVETWEB_API void *mg_get_user_data(struct mg_context *ctx);
+
+
+#if defined(MG_LEGACY_INTERFACE)
+/* Return array of strings that represent valid configuration options.
+ For each option, option name and default value is returned, i.e. the
+ number of entries in the array equals to number_of_options x 2.
+ Array is NULL terminated. */
+/* Deprecated: Use mg_get_valid_options instead. */
+CIVETWEB_API const char **mg_get_valid_option_names(void);
+#endif
+
+
+struct mg_option {
+ const char * name;
+ int type;
+ const char * default_value;
+};
+
+enum {
+ CONFIG_TYPE_UNKNOWN = 0x0,
+ CONFIG_TYPE_NUMBER = 0x1,
+ CONFIG_TYPE_STRING = 0x2,
+ CONFIG_TYPE_FILE = 0x3,
+ CONFIG_TYPE_DIRECTORY = 0x4,
+ CONFIG_TYPE_BOOLEAN = 0x5,
+ CONFIG_TYPE_EXT_PATTERN = 0x6
+};
+
+
+/* Return array of struct mg_option, representing all valid configuration
+ options of civetweb.c.
+ The array is terminated by a NULL name option. */
+CIVETWEB_API const struct mg_option *mg_get_valid_options(void);
+
+
+/* Get the list of ports that civetweb is listening on.
+ size is the size of the ports int array and ssl int array to fill.
+ It is the caller's responsibility to make sure ports and ssl each
+ contain at least size int elements worth of memory to write into.
+ Return value is the number of ports and ssl information filled in.
+ The value returned is read-only. Civetweb does not allow changing
+ configuration at run time. */
+CIVETWEB_API size_t mg_get_ports(const struct mg_context *ctx, size_t size, int* ports, int* ssl);
+
+
+/* Add, edit or delete the entry in the passwords file.
+
+ This function allows an application to manipulate .htpasswd files on the
+ fly by adding, deleting and changing user records. This is one of the
+ several ways of implementing authentication on the server side. For another,
+ cookie-based way please refer to the examples/chat in the source tree.
+
+ If password is not NULL, entry is added (or modified if already exists).
+ If password is NULL, entry is deleted.
+
+ Return:
+ 1 on success, 0 on error. */
+CIVETWEB_API int mg_modify_passwords_file(const char *passwords_file_name,
+ const char *domain,
+ const char *user,
+ const char *password);
+
+
+/* Return information associated with the request. */
+CIVETWEB_API struct mg_request_info *mg_get_request_info(struct mg_connection *);
+
+
+/* Send data to the client.
+ Return:
+ 0 when the connection has been closed
+ -1 on error
+ >0 number of bytes written on success */
+CIVETWEB_API int mg_write(struct mg_connection *, const void *buf, size_t len);
+
+
+/* Send data to a websocket client wrapped in a websocket frame. Uses mg_lock
+ to ensure that the transmission is not interrupted, i.e., when the
+ application is proactively communicating and responding to a request
+ simultaneously.
+
+ Send data to a websocket client wrapped in a websocket frame.
+ This function is available when civetweb is compiled with -DUSE_WEBSOCKET
+
+ Return:
+ 0 when the connection has been closed
+ -1 on error
+ >0 number of bytes written on success */
+CIVETWEB_API int mg_websocket_write(struct mg_connection* conn, int opcode,
+ const char *data, size_t data_len);
+
+
+/* Blocks until unique access is obtained to this connection. Intended for use
+ with websockets only.
+ Invoke this before mg_write or mg_printf when communicating with a
+ websocket if your code has server-initiated communication as well as
+ communication in direct response to a message. */
+CIVETWEB_API void mg_lock_connection(struct mg_connection* conn);
+CIVETWEB_API void mg_unlock_connection(struct mg_connection* conn);
+
+#if defined(MG_LEGACY_INTERFACE)
+#define mg_lock mg_lock_connection
+#define mg_unlock mg_unlock_connection
+#endif
+
+/* Lock server context. This lock may be used to protect ressources
+ that are shared between different connection/worker threads. */
+CIVETWEB_API void mg_lock_context(struct mg_context* ctx);
+CIVETWEB_API void mg_unlock_context(struct mg_context* ctx);
+
+
+/* Opcodes, from http://tools.ietf.org/html/rfc6455 */
+enum {
+ WEBSOCKET_OPCODE_CONTINUATION = 0x0,
+ WEBSOCKET_OPCODE_TEXT = 0x1,
+ WEBSOCKET_OPCODE_BINARY = 0x2,
+ WEBSOCKET_OPCODE_CONNECTION_CLOSE = 0x8,
+ WEBSOCKET_OPCODE_PING = 0x9,
+ WEBSOCKET_OPCODE_PONG = 0xa
+};
+
+
+/* Macros for enabling compiler-specific checks forprintf-like arguments. */
+#undef PRINTF_FORMAT_STRING
+#if defined(_MSC_VER) && _MSC_VER >= 1400
+#include <sal.h>
+#if defined(_MSC_VER) && _MSC_VER > 1400
+#define PRINTF_FORMAT_STRING(s) _Printf_format_string_ s
+#else
+#define PRINTF_FORMAT_STRING(s) __format_string s
+#endif
+#else
+#define PRINTF_FORMAT_STRING(s) s
+#endif
+
+#ifdef __GNUC__
+#define PRINTF_ARGS(x, y) __attribute__((format(printf, x, y)))
+#else
+#define PRINTF_ARGS(x, y)
+#endif
+
+/* Send data to the client usingprintf() semantics.
+ Works exactly like mg_write(), but allows to do message formatting. */
+CIVETWEB_API int mg_printf(struct mg_connection *,
+ PRINTF_FORMAT_STRING(const char *fmt), ...) PRINTF_ARGS(2, 3);
+
+
+/* Send contents of the entire file together with HTTP headers. */
+CIVETWEB_API void mg_send_file(struct mg_connection *conn, const char *path);
+
+
+/* Read data from the remote end, return number of bytes read.
+ Return:
+ 0 connection has been closed by peer. No more data could be read.
+ < 0 read error. No more data could be read from the connection.
+ > 0 number of bytes read into the buffer. */
+CIVETWEB_API int mg_read(struct mg_connection *, void *buf, size_t len);
+
+
+/* Get the value of particular HTTP header.
+
+ This is a helper function. It traverses request_info->http_headers array,
+ and if the header is present in the array, returns its value. If it is
+ not present, NULL is returned. */
+CIVETWEB_API const char *mg_get_header(const struct mg_connection *, const char *name);
+
+
+/* Get a value of particular form variable.
+
+ Parameters:
+ data: pointer to form-uri-encoded buffer. This could be either POST data,
+ or request_info.query_string.
+ data_len: length of the encoded data.
+ var_name: variable name to decode from the buffer
+ dst: destination buffer for the decoded variable
+ dst_len: length of the destination buffer
+
+ Return:
+ On success, length of the decoded variable.
+ On error:
+ -1 (variable not found).
+ -2 (destination buffer is NULL, zero length or too small to hold the
+ decoded variable).
+
+ Destination buffer is guaranteed to be '\0' - terminated if it is not
+ NULL or zero length. */
+CIVETWEB_API int mg_get_var(const char *data, size_t data_len,
+ const char *var_name, char *dst, size_t dst_len);
+
+
+/* Get a value of particular form variable.
+
+ Parameters:
+ data: pointer to form-uri-encoded buffer. This could be either POST data,
+ or request_info.query_string.
+ data_len: length of the encoded data.
+ var_name: variable name to decode from the buffer
+ dst: destination buffer for the decoded variable
+ dst_len: length of the destination buffer
+ occurrence: which occurrence of the variable, 0 is the first, 1 the
+ second...
+ this makes it possible to parse a query like
+ b=x&a=y&a=z which will have occurrence values b:0, a:0 and a:1
+
+ Return:
+ On success, length of the decoded variable.
+ On error:
+ -1 (variable not found).
+ -2 (destination buffer is NULL, zero length or too small to hold the
+ decoded variable).
+
+ Destination buffer is guaranteed to be '\0' - terminated if it is not
+ NULL or zero length. */
+CIVETWEB_API int mg_get_var2(const char *data, size_t data_len,
+ const char *var_name, char *dst, size_t dst_len, size_t occurrence);
+
+
+/* Fetch value of certain cookie variable into the destination buffer.
+
+ Destination buffer is guaranteed to be '\0' - terminated. In case of
+ failure, dst[0] == '\0'. Note that RFC allows many occurrences of the same
+ parameter. This function returns only first occurrence.
+
+ Return:
+ On success, value length.
+ On error:
+ -1 (either "Cookie:" header is not present at all or the requested
+ parameter is not found).
+ -2 (destination buffer is NULL, zero length or too small to hold the
+ value). */
+CIVETWEB_API int mg_get_cookie(const char *cookie, const char *var_name,
+ char *buf, size_t buf_len);
+
+
+/* Download data from the remote web server.
+ host: host name to connect to, e.g. "foo.com", or "10.12.40.1".
+ port: port number, e.g. 80.
+ use_ssl: wether to use SSL connection.
+ error_buffer, error_buffer_size: error message placeholder.
+ request_fmt,...: HTTP request.
+ Return:
+ On success, valid pointer to the new connection, suitable for mg_read().
+ On error, NULL. error_buffer contains error message.
+ Example:
+ char ebuf[100];
+ struct mg_connection *conn;
+ conn = mg_download("google.com", 80, 0, ebuf, sizeof(ebuf),
+ "%s", "GET / HTTP/1.0\r\nHost: google.com\r\n\r\n");
+ */
+CIVETWEB_API struct mg_connection *mg_download(const char *host, int port, int use_ssl,
+ char *error_buffer, size_t error_buffer_size,
+ PRINTF_FORMAT_STRING(const char *request_fmt),
+ ...) PRINTF_ARGS(6, 7);
+
+
+/* Close the connection opened by mg_download(). */
+CIVETWEB_API void mg_close_connection(struct mg_connection *conn);
+
+
+/* File upload functionality. Each uploaded file gets saved into a temporary
+ file and MG_UPLOAD event is sent.
+ Return number of uploaded files. */
+CIVETWEB_API int mg_upload(struct mg_connection *conn, const char *destination_dir);
+
+
+/* Convenience function -- create detached thread.
+ Return: 0 on success, non-0 on error. */
+typedef void * (*mg_thread_func_t)(void *);
+CIVETWEB_API int mg_start_thread(mg_thread_func_t f, void *p);
+
+
+/* Return builtin mime type for the given file name.
+ For unrecognized extensions, "text/plain" is returned. */
+CIVETWEB_API const char *mg_get_builtin_mime_type(const char *file_name);
+
+
+/* Return Civetweb version. */
+CIVETWEB_API const char *mg_version(void);
+
+
+/* URL-decode input buffer into destination buffer.
+ 0-terminate the destination buffer.
+ form-url-encoded data differs from URI encoding in a way that it
+ uses '+' as character for space, see RFC 1866 section 8.2.1
+ http://ftp.ics.uci.edu/pub/ietf/html/rfc1866.txt
+ Return: length of the decoded data, or -1 if dst buffer is too small. */
+CIVETWEB_API int mg_url_decode(const char *src, int src_len, char *dst,
+ int dst_len, int is_form_url_encoded);
+
+
+/* URL-encode input buffer into destination buffer.
+ returns the length of the resulting buffer or -1
+ is the buffer is too small. */
+CIVETWEB_API int mg_url_encode(const char *src, char *dst, size_t dst_len);
+
+
+/* MD5 hash given strings.
+ Buffer 'buf' must be 33 bytes long. Varargs is a NULL terminated list of
+ ASCIIz strings. When function returns, buf will contain human-readable
+ MD5 hash. Example:
+ char buf[33];
+ mg_md5(buf, "aa", "bb", NULL); */
+CIVETWEB_API char *mg_md5(char buf[33], ...);
+
+
+/* Print error message to the opened error log stream.
+ This utilizes the provided logging configuration.
+ conn: connection
+ fmt: format string without the line return
+ ...: variable argument list
+ Example:
+ mg_cry(conn,"i like %s", "logging"); */
+CIVETWEB_API void mg_cry(struct mg_connection *conn,
+ PRINTF_FORMAT_STRING(const char *fmt), ...) PRINTF_ARGS(2, 3);
+
+
+/* utility method to compare two buffers, case incensitive. */
+CIVETWEB_API int mg_strncasecmp(const char *s1, const char *s2, size_t len);
+
+/* Connect to a websocket as a client
+ Parameters:
+ host: host to connect to, i.e. "echo.websocket.org" or "192.168.1.1" or "localhost"
+ port: server port
+ use_ssl: make a secure connection to server
+ error_buffer, error_buffer_size: buffer for an error message
+ path: server path you are trying to connect to, i.e. if connection to localhost/app, path should be "/app"
+ origin: value of the Origin HTTP header
+ data_func: callback that should be used when data is received from the server
+ user_data: user supplied argument
+
+ Return:
+ On success, valid mg_connection object.
+ On error, NULL. Se error_buffer for details.
+*/
+
+typedef int (*websocket_data_func)(struct mg_connection *, int bits,
+ char *data, size_t data_len);
+
+typedef void (*websocket_close_func)(struct mg_connection *);
+
+CIVETWEB_API struct mg_connection *mg_connect_websocket_client(const char *host, int port, int use_ssl,
+ char *error_buffer, size_t error_buffer_size,
+ const char *path, const char *origin,
+ websocket_data_func data_func, websocket_close_func close_func,
+ void * user_data);
+
+/* Connect to a TCP server as a client (can be used to connect to a HTTP server)
+ Parameters:
+ host: host to connect to, i.e. "www.wikipedia.org" or "192.168.1.1" or "localhost"
+ port: server port
+ use_ssl: make a secure connection to server
+ error_buffer, error_buffer_size: buffer for an error message
+
+ Return:
+ On success, valid mg_connection object.
+ On error, NULL. Se error_buffer for details.
+*/
+CIVETWEB_API struct mg_connection *mg_connect_client(const char *host, int port, int use_ssl,
+ char *error_buffer, size_t error_buffer_size);
+
+
+enum {
+ TIMEOUT_INFINITE = -1
+};
+
+/* Wait for a response from the server
+ Parameters:
+ conn: connection
+ ebuf, ebuf_len: error message placeholder.
+ timeout: time to wait for a response in milliseconds (if < 0 then wait forever)
+
+ Return:
+ On success, >= 0
+ On error/timeout, < 0
+*/
+CIVETWEB_API int mg_get_response(struct mg_connection *conn, char *ebuf, size_t ebuf_len, int timeout);
+
+
+#ifdef __cplusplus
+}
+#endif /* __cplusplus */
+
+#endif /* CIVETWEB_HEADER_INCLUDED */