URLFrame.h

00001 /* mbed Microcontroller Library
00002  * Copyright (c) 2006-2015 ARM Limited
00003  *
00004  * Licensed under the Apache License, Version 2.0 (the "License");
00005  * you may not use this file except in compliance with the License.
00006  * You may obtain a copy of the License at
00007  *
00008  *     http://www.apache.org/licenses/LICENSE-2.0
00009  *
00010  * Unless required by applicable law or agreed to in writing, software
00011  * distributed under the License is distributed on an "AS IS" BASIS,
00012  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00013  * See the License for the specific language governing permissions and
00014  * limitations under the License.
00015  */
00016 
00017 #ifndef __URLFRAME_H__
00018 #define __URLFRAME_H__
00019 
00020 #include "EddystoneTypes.h"
00021 #include <string.h>
00022 
00023 /**
00024  * Class that encapsulates data that belongs to the Eddystone-URL frame. For
00025  * more information refer to https://github.com/google/eddystone/tree/master/eddystone-url.
00026  */
00027 class URLFrame
00028 {
00029 public:
00030     /**
00031      * Construct a new instance of this class.
00032      */
00033     URLFrame(void);
00034     
00035     /**
00036      * Construct the raw bytes of the Eddystone-URL frame from an unencoded URL
00037      * (a null terminated string) that will be directly used in the advertising
00038      * packets.
00039      *
00040      * @param[in] rawFrame
00041      *              Pointer to the location where the raw frame will be stored.
00042      * @param[in] advPowerLevel
00043      *              Power level value included in the raw frame.
00044      * @param[in] rawURL
00045      *              A null terminated string containing the URL
00046      */
00047     void setUnencodedUrlData(uint8_t* rawFrame, int8_t advTxPower, const char *rawUrl);
00048     
00049     /**
00050      * Clear frame (intervally indicated by length = 0 )
00051      */
00052     void clearFrame(uint8_t* frame);
00053     
00054     /**
00055      * Construct the raw bytes of the Eddystone-URL frame from an encoded URL 
00056      * plus length information
00057      *
00058      * @param[in] rawFrame
00059      *              Pointer to the location where the raw frame will be stored.
00060      * @param[in] advPowerLevel
00061      *              Power level value included in the raw frame.
00062      * @param[in] encodedUrlData
00063      *              A pointer to the encoded URL bytes.
00064      * @param[in] encodedUrlLen
00065      *              The length in bytes of the encoded URL
00066      */
00067     void setData(uint8_t* rawFrame, int8_t advPowerLevel, const uint8_t* encodedUrlData, uint8_t encodedUrlLen);
00068     
00069     /**
00070      * Get the URL frame data from the Eddystone-URL frame.
00071      * 
00072      * @param[in] rawFrame
00073      *              Pointer to the location where the raw frame will be stored.
00074      *
00075      * @return A pointer to the bytes of the Eddystone-URL frame data.
00076      */
00077     uint8_t* getData(uint8_t* rawFrame);
00078     
00079     /**
00080      * Get the length of the URL frame data from the Eddystone-UID frame.
00081      * 
00082      * @param[in] rawFrame
00083      *              Pointer to the location where the raw frame will be stored.
00084      *
00085      * @return The size in bytes of the Eddystone-URL frame.
00086      */
00087     uint8_t getDataLength(uint8_t* rawFrame);
00088 
00089     /**
00090      * Get the URL Adv data from the Eddystone-URLframe.
00091      * This is the full service data included in the BLE service data params
00092      * 
00093      * @param[in] rawFrame
00094      *              Pointer to the location where the raw frame will be stored.
00095      *
00096      * @return A pointer to the bytes of the Eddystone-URLAdv frame data.
00097      */
00098     uint8_t* getAdvFrame(uint8_t* rawFrame);
00099     
00100     /**
00101      * Get the length of the URLAdv data from the Eddystone-URL frame.
00102      * 
00103      * @param[in] rawFrame
00104      *              Pointer to the location where the raw frame will be stored.
00105      *
00106      * @return The size in bytes of the Eddystone-URL Adv frame data.
00107      */
00108     uint8_t getAdvFrameLength(uint8_t* rawFrame);
00109 
00110     /**
00111      * Get just the encoded URL data from the Eddystone-URL frame.
00112      * 
00113      * @param[in] rawFrame
00114      *              Pointer to the location where the raw frame will be stored.
00115      *
00116      * @return A pointer to the bytes of the encoded URL in the Eddystone-URL
00117      * frame.
00118      */
00119     uint8_t* getEncodedUrl(uint8_t* rawFrame);
00120     
00121     /**
00122      * Get the length of just the encoded URL data from the Eddystone-URL frame.
00123      * 
00124      * @param[in] rawFrame
00125      *              Pointer to the location where the raw frame will be stored.
00126      *
00127      * @return The size in bytes of the encoded URL in the Eddystone-URL frame.
00128      */
00129     uint8_t getEncodedUrlLength(uint8_t* rawFrame);
00130     
00131     /**
00132      * Set the Adv TX Power in the frame. This is necessary because the adv
00133      * Tx Power might be updated independent of the data bytes
00134      * 
00135      * @param[in] rawFrame
00136      *              Pointer to the location where the raw frame will be stored.
00137      * @param[in] advPowerLevel
00138      *              Power level value included in the raw frame.
00139      *
00140      */
00141     void setAdvTxPower(uint8_t* rawFrame, int8_t advTxPower);
00142 
00143     /**
00144      *  The byte ID of an Eddystone-URL frame.
00145      */
00146     static const uint8_t FRAME_TYPE_URL     = 0x10;
00147 
00148 private:
00149     static const uint8_t FRAME_LEN_OFFSET = 0;
00150     static const uint8_t EDDYSTONE_UUID_LEN = 2;
00151     static const uint8_t URL_DATA_OFFSET = 3;
00152     static const uint8_t ADV_FRAME_OFFSET = 1;
00153     static const uint8_t URL_VALUE_OFFSET = 5;
00154     static const uint8_t URL_HEADER_LEN = 4;
00155     static const uint8_t URL_TXPOWER_OFFSET = 4;
00156 
00157     /**
00158      * Helper function that encodes a URL null terminated string into the HTTP
00159      * URL Encoding required in Eddystone-URL frames. Refer to
00160      * https://github.com/google/eddystone/blob/master/eddystone-url/README.md#eddystone-url-http-url-encoding.
00161      *
00162      * @param[in] encodedUrlData
00163      *              The encoded bytes of the URL
00164      * @param[in] rawUrl
00165      *              The null terminated string containing a URL to encode.
00166      * @return Length of the encodedData in bytes
00167      */
00168     uint8_t encodeURL(uint8_t* encodedUrlData, const char* rawUrl);
00169 
00170     /**
00171      * The minimum size (in bytes) of an Eddystone-URL frame.
00172      */
00173     static const uint8_t FRAME_MIN_SIZE_URL = 2;
00174     
00175     /**
00176      * The max size (in bytes) of an Eddystone-URL frame.
00177      */
00178     static const uint8_t ENCODED_BUF_SIZE = 32;
00179     
00180     /**
00181     * Offset for playload in a rawFrame UID
00182     */
00183     static const uint8_t MAX_URL_DATA = 18;
00184 };
00185 
00186 #endif /* __URLFRAME_H__ */