sam_oneal/dial-reference
1
0
Fork 0
mirror of https://github.com/Netflix/dial-reference.git synced 2026-06-08 02:49:58 +00:00
Code Issues Packages Projects Releases Wiki Activity

Add/improve function documentation and update copyright information.

Browse Source
This commit is contained in:
Wesley Miaw
2019-10-07 14:28:40 -07:00
parent bfde146144
commit 5dc0f40b2f
14 changed files with 278 additions and 30 deletions
Download Patch File Download Diff File Expand all files Collapse all files

9
server/dial_data.c
View File

@@ -1,5 +1,5 @@
/*
* Copyright (c) 2014 Netflix, Inc.
* Copyright (c) 2014-2019 Netflix, Inc.
* All rights reserved.
*
* Redistribution and use in source and binary forms, with or without
@@ -40,6 +40,13 @@ void set_dial_data_dir(const char *data_dir) {
/**
* Returns the path where data is stored for the given app.
*
* The DIAL data directory must have been already set.
*
* @param app_name application name.
* @return the location of the application path within the DIAL data
* directory or NULL if memory could not be allocated.
* @see set_dial_data_dir(const char*)
*/
static char* getAppPath(char *app_name) {
size_t name_size = strlen(app_name) + sizeof(dial_data_dir) + 1;

42
server/dial_data.h
View File

@@ -1,5 +1,5 @@
/*
* Copyright (c) 2014 Netflix, Inc.
* Copyright (c) 2014-2019 Netflix, Inc.
* All rights reserved.
*
* Redistribution and use in source and binary forms, with or without
@@ -46,6 +46,13 @@
*/
#define DIAL_DATA_URI "/dial_data"
/**
* The DIAL data key and value values cannot contain any spaces. They are
* expected to be URL-escaped strings, so any spaces would be represented as
* the '+' character. They have a max length of 255 characters.
*
* THE STRINGS key AND value POINT TO MUST BE DYNAMICALLY ALLOCATED
*/
struct DIALData_ {
struct DIALData_ *next;
char *key;
@@ -54,12 +61,45 @@ struct DIALData_ {
typedef struct DIALData_ DIALData;
#define DIAL_KEY_OR_VALUE_MAX_LEN (255)
#define DIAL_KEY_OR_VALUE_MAX_LEN_STR "255"
/**
* Store the DIAL data key/value pairs in the application data store.
*
* Will exit immediately if the data output file cannot be accessed due to
* out-of-memory or I/O errors.
*
* Keys and values are truncated to DIAL_KEY_OR_VALUE_MAX_LEN.
*
* @param app_name application name.
* @param data pointer to head of DIAL data linked list.
*/
void store_dial_data(char *app_name, DIALData *data);
/**
* Retrieve the DIAL data key/value pairs from the application data store.
*
* @param app_name application name.
* @return data pointer to head of DIAL data linked list or NULL if
* there is no valid data or if the data output file cannot be accessed
* due to out-of-memory or I/O errors.
*/
DIALData *retrieve_dial_data(char *app_name);
/**
* Set the DIAL data directory.
*
* @param data_dir the DIAL data directory path, which must include the
* trailing directory separator (e.g. '/' character).
*/
void set_dial_data_dir(const char *data_dir);
/**
* Frees the DIAL data linked list memory.
*
* @param dialData pointer to the DIAL data linked list.
*/
void free_dial_data(DIALData **dialData);
#endif /* SRC_SERVER_DIAL_DATA_H_ */

42
server/dial_server.c
View File

@@ -1,5 +1,5 @@
/*
* Copyright (c) 2014 Netflix, Inc.
* Copyright (c) 2014-2019 Netflix, Inc.
* All rights reserved.
*
* Redistribution and use in source and binary forms, with or without
@@ -69,14 +69,30 @@ struct DIALServer_ {
static void ds_lock(DIALServer *ds) {
pthread_mutex_lock(&ds->mux);
/**
* Acquire the DIAL server mutex.
*
* @return 1 if acquisition succeeded, 0 if it failed.
*/
}
static void ds_unlock(DIALServer *ds) {
pthread_mutex_unlock(&ds->mux);
/**
* Release the DIAL server mutex.
*
* @return 1 if release succeeded, 0 if it failed.
*/
}
// finds an app and returns a pointer to the previous element's next pointer
// if not found, return a pointer to the last element's next pointer
/**
* Finds an application in the DIAL server application linked list.
*
* @param ds the DIAL server.
* @param app_name application name.
* @return a pointer to the DIAL application; the pointer value may be NULL if
* the application was not found.
*/
static DIALApp **find_app(DIALServer *ds, const char *app_name) {
DIALApp *app;
DIALApp **ret = &ds->apps;
@@ -90,15 +106,29 @@ static DIALApp **find_app(DIALServer *ds, const char *app_name) {
}
static void url_decode_xml_encode(char *dst, char *src, size_t src_size) {
/**
* URL-unescape the string, then XML-escape it.
*
* @param dst the destination XML-escaped string. Must be large enough for
* the resulting string (technically as much as 6x the raw string
* length based on the implementation in url_lib.c).
* @param src the URL-escaped string.
* @param src_size size of the URL-escaped string, including trailing NULL.
* @return true if successful, false if out-of-memory.
*/
char *url_decoded_key = (char *) malloc(src_size + 1);
urldecode(url_decoded_key, src, src_size);
xmlencode(dst, url_decoded_key, 2 * src_size);
free(url_decoded_key);
}
/*
* A bad payload is defined to be an unprintable character or a
* non-ascii character.
/**
* Checks if a payload string contains invalid characters.
*
* @param pPayload payload string.
* @param numBytes length of payload string in bytes (excluding trailing NULL).
*
* @return 1 if the payload contains an unprintable or non-ASCII character.
*/
static int isBadPayload(const char* pPayload, int numBytes) {
int i = 0;

12
server/dial_server.h
View File

@@ -1,5 +1,5 @@
/*
* Copyright (c) 2014 Netflix, Inc.
* Copyright (c) 2014-2019 Netflix, Inc.
* All rights reserved.
*
* Redistribution and use in source and binary forms, with or without
@@ -59,7 +59,9 @@ typedef enum {
#define DIAL_MAX_PAYLOAD (4096)
/*
* The maximum additionalDataUrl length
* The maximum additionalDataUrl length.
*
* There is no value defined in the DIAL specification.
*/
#define DIAL_MAX_ADDITIONALURL (1024)
@@ -120,6 +122,8 @@ DIALServer *DIAL_create();
* Starts the DIAL server.
*
* @param[in] ds DIAL server handle
* @return true if the DIAL server was started and the DIAL server handle
* now contains a valid Mongoose context.
*/
void DIAL_start(DIALServer *ds);
@@ -141,7 +145,7 @@ void DIAL_stop(DIALServer *ds);
* @param[in] if non-0, the app supports DIALadditionalDataURL.
* @param[in] if non-NULL, specifies the CORS allowed origin for this app.
*
* @return 1 if successful, 0 otherwise
* @return 1 if successful, 0 if already registered, -1 on error.
*/
int DIAL_register_app(DIALServer *ds, const char *app_name,
struct DIALAppCallbacks *callbacks,
@@ -154,7 +158,7 @@ int DIAL_register_app(DIALServer *ds, const char *app_name,
* @param[in] ds DIAL server handle
* @param[in] app_name Name of the DIAL application
*
* @return 1 if successful, 0 otherwise
* @return 1 if successful, 0 if not found, -1 on error.
*/
int DIAL_unregister_app(DIALServer *ds, const char *app_name);

17
server/mongoose.c
View File

@@ -314,6 +314,14 @@ void mg_send_http_error(struct mg_connection *conn, int status,
conn->num_bytes_sent += mg_printf(conn, "%s", buf);
}
/**
* Create a new thread.
*
* @param ctx Mongoose context.
* @param func thread function.
* @param param thread function arguments.
* @return the return value of pthread_create.
*/
static int start_thread(struct mg_context *ctx, mg_thread_func_t func,
void *param) {
pthread_t thread_id;
@@ -839,9 +847,16 @@ static void worker_thread(struct mg_context *ctx) {
DEBUG_TRACE(("exiting"));
}
// Master thread adds accepted socket to a queue
static void produce_socket(struct mg_context *ctx, const struct socket *sp) {
(void) pthread_mutex_lock(&ctx->mutex);
/**
* Copy an accepted socket onto the queue. Blocks if the queue is full. This
* function is called from the master thread.
*
* @param ctx Mongoose context.
* @param sp the socket.
* @return true if successful, false if there was a mutex error.
*/
// If the queue is full, wait
while (ctx->sq_head - ctx->sq_tail >= (int) ARRAY_SIZE(ctx->queue)) {

24
server/nf_callbacks.c
View File

@@ -1,3 +1,27 @@
/*
* Copyright (c) 2014-2019 Netflix, Inc.
* All rights reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions are met:
*
* Redistributions of source code must retain the above copyright notice, this
* list of conditions and the following disclaimer.
* Redistributions in binary form must reproduce the above copyright notice,
* this list of conditions and the following disclaimer in the documentation
* and/or other materials provided with the distribution.
*
* THIS SOFTWARE IS PROVIDED BY NETFLIX, INC. AND CONTRIBUTORS "AS IS" AND ANY
* EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
* WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
* DISCLAIMED. IN NO EVENT SHALL NETFLIX OR CONTRIBUTORS BE LIABLE FOR ANY
* DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
* (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
* LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
* ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
* (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
* THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*/
#include <stdio.h>
#include <stdlib.h>
#include <string.h>

2
server/nf_callbacks.h
View File

@@ -1,5 +1,5 @@
/*
* Copyright (c) 2014 Netflix, Inc.
* Copyright (c) 2014-2019 Netflix, Inc.
* All rights reserved.
*
* Redistribution and use in source and binary forms, with or without

14
server/quick_ssdp.c
View File

@@ -142,6 +142,20 @@ static void get_local_address() {
}
#else
static void get_local_address() {
/**
* Returns the local hardware address (e.g. MAC address). On macOS the "en0"
* interface is used. On other platforms the first non-loopback interface is
* used.
*
* As a side-effect, the local global ip_addr is also populated.
*
* (Are these choices of interface really the right ones? Seems risky for
* multi-homed systems.)
*
* @return the local hardware address or NULL if it does not exist, cannot
* be retrieved, or out-of-memory. The caller must free the returned
* memory.
*/
struct ifconf ifc;
char buf[4096];
int s, i;

24
server/system_callbacks.c
View File

@@ -1,3 +1,27 @@
/*
* Copyright (c) 2018-2019 Netflix, Inc.
* All rights reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions are met:
*
* Redistributions of source code must retain the above copyright notice, this
* list of conditions and the following disclaimer.
* Redistributions in binary form must reproduce the above copyright notice,
* this list of conditions and the following disclaimer in the documentation
* and/or other materials provided with the distribution.
*
* THIS SOFTWARE IS PROVIDED BY NETFLIX, INC. AND CONTRIBUTORS "AS IS" AND ANY
* EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
* WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
* DISCLAIMED. IN NO EVENT SHALL NETFLIX OR CONTRIBUTORS BE LIABLE FOR ANY
* DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
* (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
* LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
* ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
* (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
* THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*/
#include <string.h>
#include <stdio.h>
#include "system_callbacks.h"

7
server/system_callbacks.h
View File

@@ -1,5 +1,5 @@
/*
* Copyright (c) 2018 Netflix, Inc.
* Copyright (c) 2018-2019 Netflix, Inc.
* All rights reserved.
*
* Redistribution and use in source and binary forms, with or without
@@ -28,6 +28,11 @@
#include "dial_server.h"
/**
*
*
* Sleep is the only supported action for 'system', and not implemented in this reference.
*/
DIALStatus system_start(DIALServer *ds, const char *appname,
const char *payload, const char* query_string,
const char *additionalDataUrl,

2
server/tests/test_dial_data.c
View File

@@ -1,5 +1,5 @@
/*
* Copyright (c) 2014 Netflix, Inc.
* Copyright (c) 2014-2019 Netflix, Inc.
* All rights reserved.
*
* Redistribution and use in source and binary forms, with or without

12
server/url_lib.c
View File

@@ -1,5 +1,5 @@
/*
* Copyright (c) 2014 Netflix, Inc.
* Copyright (c) 2014-2019 Netflix, Inc.
* All rights reserved.
*
* Redistribution and use in source and binary forms, with or without
@@ -39,6 +39,16 @@ char* smartstrcat(char* dest, char* src, size_t max_chars) {
return dest;
}
/**
* Convert a two-character hex representation into its ASCII equivalent
* and copy it into dest.
*
* @param dest the destination character buffer.
* @param a the first hex character.
* @param b the second hex character.
* @return 1 if the character was converted and copied, 0 if the hex
* characters are invalid.
*/
static int append_char_from_hex(char* dest, char a, char b) {
if ('a' <= a && a <= 'f')
a = 10 + a - 'a';

85
server/url_lib.h
View File

@@ -1,5 +1,5 @@
/*
* Copyright (c) 2014 Netflix, Inc.
* Copyright (c) 2014-2019 Netflix, Inc.
* All rights reserved.
*
* Redistribution and use in source and binary forms, with or without
@@ -31,35 +31,94 @@
#include <stddef.h>
/**
* Concatenate a maxim of max_chars characters from src into dest,
* and return a pointer to the last character in dest.
* Copy a maximum of max_chars characters from src into dest,
* and return a pointer to the terminating NULL in dest.
*
* @param dest destination buffer.
* @param src string written into the destination buffer
* @param max_chars maximum number of characters to put into the destination
* buffer, excluding the trailing NULL. Must be less than or equal to
* the number of bytes available at dest - 1.
* @return a pointer to the end of the written string (the location of the
* terminating NULL).
*/
char* smartstrcat(char* dest, char* src, size_t max_chars);
/**
* URL-unescape the source string into the destination string, up to the
* maximum number of destination characters.
*
* @param dst raw string buffer.
* @param src URL-escaped source string.
* @param max_size maximum number of characters to put into the destination
* buffer, excluding the trailing NULL. Must be less than or equal to
* sizeof(dst) - 1.
* @return the length of the raw string excluding the trailing NULL. Will be
* 0 if there were no characters to unescape or if the source string
* was malformed.
*/
int urldecode(char *dst, const char *src, size_t max_size);
/**
* XML-escape the source string into the destination string, up to the maximum
* number of destination characters.
*
* @param dst XML-escaped string buffer.
* @param src raw source string.
* @param max_size maximum number of characters to put into the destination
* buffer, excluding the trailing NULL. Must be less than or equal to
* sizeof(dst) - 1.
* @return the length of the XML-escaped string excluding the trailing NULL.
*/
void xmlencode(char *dst, const char *src, size_t max_size);
/**
* Parse the value of the parameter with the given name from a query string.
* Return the value in the query string for the requested parameter name.
*
* @param query_string the URL query string.
* @param param_name the parameter name.
* @return the parameter value or NULL if out-of-memory. The caller must free
* the returned memory.
*/
char *parse_param(char *query_string, char *param_name);
/*
* Parse the application name out of a URI, such as /app/YouTube/dial_data.
* Note: this parser assumes that the dial_data url is of the form
* /apps/<app_name>/dial_data. If your DIAL server uses a different url-path,
* you will need to adapt the method below.
/**
* Parse the application name out of the full URI, for example
* /app/YouTube/dial_data. The application name identified as the string
* appearing before the last trailing slash, possibly prefixed with a slash,
* so /apps/<app_name>/dial_data and YouTube would be the application name in
* the previous example.
*
* If your DIAL server uses a different path format you will need to change
* this method to match.
*
* @param uri the URI, there must be a trailing slash.
* @return the application name, or "unknown" if two slashes cannot be found
* or the application name is zero-length, or NULL if out-of-memory.
* The caller must free the returned memory.
*/
char *parse_app_name(const char *uri);
/*
* Parse a list of DIALData params out of a query string.
/**
* Return a linked list of DIAL data constructed from the name/value parameter
* pairs of the provided query string.
*
* This function must be called while holding a mutex and is not itself
* thread-safe.
*
* @param query_string the URL query string.
* @return the DIAL data or NULL if there is none (e.g. parse error) or out-of-
* memory. The caller must free the returned memory.
*/
DIALData *parse_params(char * query_string);
/* Returns a url-encoded version of str */
/* IMPORTANT: be sure to free() the returned string after use */
/**
* Return the URL-escaped version of the provided string, which may be as
* large as 3x the size of the provided string, plus a trailing NULL byte.
*
* @return the URL-escaped version of the provided string. The caller must
* free the returned string.
*/
char *url_encode(const char *str);
#endif // URLLIB_H_