| /* |
| * |
| * Copyright (c) 2013-2017 Nest Labs, Inc. |
| * All rights reserved. |
| * |
| * Licensed 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. |
| */ |
| |
| /** |
| * @file |
| * Declarations for the Weave Service Directory Profile and the |
| * corresponding protocol. See ServiceDirectory.cpp for more |
| * details and the document: |
| * |
| * Nest Weave - Service Directory Protocol |
| * |
| * for a protocol description. |
| */ |
| |
| #ifndef _WSD_PROFILE_H |
| #define _WSD_PROFILE_H |
| |
| #include <Weave/Core/WeaveCore.h> |
| #include <Weave/Core/WeaveMessageLayer.h> |
| #include <Weave/Profiles/ProfileCommon.h> |
| |
| #include <Weave/Support/NLDLLUtil.h> |
| |
| #include <Weave/Support/logging/WeaveLogging.h> |
| #include <Weave/Support/ErrorStr.h> |
| |
| #if WEAVE_CONFIG_ENABLE_SERVICE_DIRECTORY |
| |
| /** |
| * @namespace nl::Weave::Profiles::ServiceDirectory |
| * |
| * @brief |
| * This namespace includes all interfaces within Weave for the |
| * Weave Service Directory profile, which includes the |
| * corresponding, protocol of the same name. |
| */ |
| |
| namespace nl { |
| namespace Weave { |
| namespace Profiles { |
| namespace ServiceDirectory { |
| |
| /** |
| * Weave message types used in this profile |
| * |
| */ |
| enum |
| { |
| kMsgType_ServiceEndpointQuery = 0x00, ///< Service Endpoint Query message type |
| kMsgType_ServiceEndpointResponse = 0x01 ///< Service Endpoint Response message type |
| }; |
| |
| enum |
| { |
| kConnectRequestPoolSize = 4, ///< the number of simultaneous connect requests |
| }; |
| |
| /** |
| * Masks for the control byte of the service endpoint response frame |
| * |
| */ |
| enum |
| { |
| kMask_DirectoryLen = 0x0F, ///< Length of the directory |
| kMask_Redirect = 0x10, ///< Redirect flag |
| kMask_SuffixTablePresent = 0x20, ///< Suffix table present flag |
| kMask_TimeFieldsPresent = 0x40, ///< Time fields present flag |
| }; |
| |
| /** |
| * Masks and values for the control byte of the directory |
| * list field of the service endpoint response frame. |
| * |
| */ |
| enum |
| { |
| kMask_HostPortListLen = 0x07, ///< Length of the host/port list |
| kMask_DirectoryEntryType = 0xC0, ///< Entry Type |
| kDirectoryEntryType_SingleNode = 0x00, ///< A zero value means this entry is a node ID |
| kDirectoryEntryType_HostPortList = 0x40, ///< This entry is a list of host/port pairs |
| }; |
| |
| /** |
| * Masks and values for the control byte in each host/port |
| * list item |
| * |
| */ |
| enum |
| { |
| kMask_HostIdType = 0x03, ///< The type of host ID |
| kHostIdType_FullyQualified = 0x00, ///< The host ID is all there |
| kHostIdType_Composite = 0x01, ///< The host ID needs to be matched with a suffix |
| kMask_SuffixIndexPresent = 0x04, ///< A suffix index is present |
| kMask_PortIdPresent = 0x08 ///< A port ID is present |
| }; |
| |
| /** |
| * Status code |
| * |
| */ |
| enum |
| { |
| kStatus_DirectoryUnavailable = 0x0051 ///< Directory is not available |
| }; |
| |
| /** |
| * Manager states |
| * |
| */ |
| enum |
| { |
| kServiceMgrState_Initial = 0, |
| kServiceMgrState_Resolving = 1, |
| kServiceMgrState_Waiting = 2, |
| kServiceMgrState_Resolved = 3 |
| }; |
| |
| #define kServiceEndpoint_Directory (0x18B4300200000001ull) ///< Directory profile endpoint |
| #define kServiceEndpoint_SoftwareUpdate (0x18B4300200000002ull) ///< Software update profile endpoint |
| #define kServiceEndpoint_Data_Management (0x18B4300200000003ull) ///< Core Weave data management protocol endpoint |
| #define kServiceEndpoint_Log_Upload (0x18B4300200000004ull) ///< Bulk data transfer profile endpoint for log uploads |
| #define kServiceEndpoint_TimeService (0x18B4300200000005ull) ///< Time service endpoint |
| #define kServiceEndpoint_ServiceProvisioning (0x18B4300200000010ull) ///< Service provisioning profile endpoint |
| #define kServiceEndpoint_WeaveTunneling (0x18B4300200000011ull) ///< Weave tunneling endpoint |
| #define kServiceEndpoint_CoreRouter (0x18B4300200000012ull) ///< Core router endpoint |
| #define kServiceEndpoint_FileDownload (0x18B4300200000013ull) ///< File download profile endpoint |
| #define kServiceEndpoint_Bastion (0x18B4300200000014ull) ///< Nest Bastion service endpoint |
| |
| /** |
| * @class WeaveServiceManager |
| * |
| * @brief The manager object for the Weave service directory. |
| * |
| * The Weave service manager is the main interface for |
| * applications to the directory service. As such, it hides the |
| * complications inherent in looking up the directory entry |
| * associated with a service endpoint, doing DNS lookup on one or |
| * more of the host names found there, attempting to connect, |
| * securing the connection and so on. It may also manage a cache |
| * of service directory information. |
| */ |
| class NL_DLL_EXPORT WeaveServiceManager |
| { |
| public: |
| |
| /** |
| * @typedef RootDirectoryAccessor |
| * |
| * @brief An accessor function for the root directory info. |
| * |
| * You gotta start somewhere and with the service directory |
| * you gotta start with a stub directory that contains the |
| * address of a server you can hit to get at everything |
| * else. Since the disposition and provenance of this |
| * information is likely to vary from device to device, we |
| * provide an accessor callback here. |
| * |
| * @param [out] aDirectory A pointer to a buffer to write |
| * the directory information. |
| * |
| * @param [in] aLength The length of the given buffer in bytes. |
| * |
| * @return #WEAVE_NO_ERROR on success, otherwise the loading process |
| * would be aborted. |
| */ |
| typedef WEAVE_ERROR(*RootDirectoryAccessor)(uint8_t *aDirectory, uint16_t aLength); |
| |
| /** |
| * @typedef StatusHandler |
| * |
| * @brief A handler for error and status conditions. |
| * |
| * A user of the service manager may be informed of problems in trying |
| * to execute a connect request in one of two ways. It may receive a |
| * status report from the service or it may recieve an internally |
| * generated WEAVE_ERROR. In either case, the information comes through |
| * this callback. |
| * |
| * @param [in] anAppState A pointer to an application object that was |
| * passed in to the corresponding conect() call. |
| * |
| * @param [in] anError An Weave error code indicating error happened |
| * in the process of trying to execute the connect request. This |
| * shall be #WEAVE_NO_ERROR in the case where no error arose and a |
| * status report is available. |
| * |
| * @param [in] aStatusReport A pointer to a status report generated |
| * by the remote directory service. This argument shall be NULL in |
| * the case where there was no status report and an internal error |
| * is passed in the previous argument. |
| * |
| */ |
| typedef void (*StatusHandler)(void * anAppState, WEAVE_ERROR anError, StatusReport *aStatusReport); |
| |
| /** |
| * @typedef OnServiceEndpointQueryEndWithTimeInfo |
| * |
| * @brief An application callback to deliver time values from a service |
| * directory response. |
| * |
| * This is called when we get time information from service directory |
| * query response Note this callback would only happen if a response is |
| * successfully parsed and time information is included |
| * |
| * @param [in] timeQueryReceiptMsec The number of msec since POSIX epoch, |
| * when the query was received at server side. |
| * |
| * @param [in] timeProcessMsec The number of msec spent on processing |
| * this query. |
| */ |
| typedef void (*OnServiceEndpointQueryEndWithTimeInfo)(uint64_t timeQueryReceiptMsec, uint32_t timeProcessMsec); |
| |
| /** |
| * @typedef OnServiceEndpointQueryBegin |
| * |
| * @brief An application callback to mark the time of an outgoing service |
| * directory query. |
| * |
| * This is called when we are about to send out service endpoint query |
| * request. This is used to match with OnServiceEndpointQueryEnd to |
| * compensate for message flight time. |
| * |
| */ |
| typedef void (*OnServiceEndpointQueryBegin)(void); |
| |
| WeaveServiceManager(void); |
| ~WeaveServiceManager(void); |
| |
| WEAVE_ERROR init(WeaveExchangeManager *aExchangeMgr, |
| uint8_t *aCache, |
| uint16_t aCacheLen, |
| RootDirectoryAccessor aAccessor, |
| WeaveAuthMode aDirAuthMode = kWeaveAuthMode_Unauthenticated, |
| OnServiceEndpointQueryBegin aServiceEndpointQueryBegin = NULL, |
| OnServiceEndpointQueryEndWithTimeInfo aServiceEndpointQueryEndWithTimeInfo = NULL); |
| |
| WEAVE_ERROR connect(uint64_t aServiceEp, |
| WeaveAuthMode aAuthMode, |
| void *aAppState, |
| StatusHandler aStatusHandler, |
| WeaveConnection::ConnectionCompleteFunct aConnectionCompleteHandler, |
| const uint32_t aConnectTimeoutMsecs = 0, |
| const InterfaceId aConnectIntf = INET_NULL_INTERFACEID); |
| |
| WEAVE_ERROR lookup(uint64_t aServiceEp, uint8_t *aControlByte, uint8_t **aDirectoryEntry); |
| |
| WEAVE_ERROR replaceOrAddCacheEntry(uint16_t port, |
| const char *hostName, |
| uint8_t hostLen, |
| uint64_t serviceEndpointId); |
| |
| void cancel(uint64_t aServiceEp, void *aAppState); |
| |
| void unresolve(WEAVE_ERROR aError); |
| void unresolve(void); |
| |
| void reset(WEAVE_ERROR aError); |
| void reset(void); |
| |
| void relocate(WEAVE_ERROR aError); |
| void relocate(void); |
| |
| // Handler methods for the query/response transaction |
| |
| void onConnectionComplete(WEAVE_ERROR aError); |
| void onConnectionClosed(WEAVE_ERROR aError); |
| void onResponseReceived(uint32_t aProfileId, uint8_t aMsgType, PacketBuffer *aMsg); |
| void onResponseTimeout(void); |
| |
| // Clear cache and reset state so that the next connect request |
| // goes to the service directory endpoint first |
| void clearCache(void); |
| |
| enum |
| { |
| /** |
| * @brief |
| * Number of milliseconds a response must be received for the |
| * directory query before the exchange context times out. |
| */ |
| kWeave_DefaultSendTimeout = 15000 |
| }; |
| |
| /** |
| * @class ConnectRequest |
| * |
| * @brief This class represents a single transaction managed by the service manager. |
| */ |
| class ConnectRequest |
| { |
| public: |
| |
| WEAVE_ERROR init(WeaveServiceManager *aManager, |
| const uint64_t &aServiceEp, |
| WeaveAuthMode aAuthMode, |
| void *aAppState, |
| StatusHandler aStatusHandler, |
| WeaveConnection::ConnectionCompleteFunct aCompleteHandler, |
| const uint32_t aConnectTimeoutMsecs, |
| const InterfaceId aConnIntf); |
| |
| void free(void); |
| |
| void finalize(void); |
| |
| /** |
| * This function tests if this connect request is currently in use to |
| * connect to a particular service endpoint for a particualr |
| * application entity. |
| * |
| * @param[in] aServiceEp A service endpoint ID to be compared with |
| * what this connect request holds. |
| * |
| * @param[in] aAppState A pointer to application state, which is |
| * used to compare with what this connect request holds. |
| * |
| * @return true if the test passes, false otherwise. |
| */ |
| inline bool isAllocatedTo(const uint64_t &aServiceEp, void *aAppState) |
| { |
| return (mServiceEp == aServiceEp && mAppState == aAppState); |
| } |
| |
| /** |
| * This function tests if the connect request is not currently |
| * allocated. |
| * |
| * @return true if the test passes, false otherwise. |
| */ |
| inline bool isFree(void) |
| { |
| return (mServiceEp == 0 && !mAppState); |
| } |
| |
| void onConnectionComplete(WEAVE_ERROR aError); |
| |
| // data members (basically the connect call arguments) |
| |
| uint64_t mServiceEp; |
| WeaveAuthMode mAuthMode; |
| void *mAppState; |
| |
| /// A connection to stash here while it's awaiting completion. |
| WeaveConnection *mConnection; |
| |
| uint32_t mConnectTimeoutMsecs; ///< the timeout for the Connect call to succeed or return an error. |
| InterfaceId mConnIntf; ///< the interface over which the connection is to be set up. |
| |
| /// A pointer to a function which would be called when a status report is |
| /// received. |
| StatusHandler mStatusHandler; |
| |
| /// A pointer to a function which would be called when a connection to |
| /// destination service endpoint has been completed. |
| WeaveConnection::ConnectionCompleteFunct mConnectionCompleteHandler; |
| }; |
| |
| private: |
| |
| struct Extent |
| { |
| uint8_t *base; |
| size_t length; |
| }; |
| |
| void freeConnectRequests(void); |
| void finalizeConnectRequests(void); |
| ConnectRequest *getAvailableRequest(void); |
| |
| WEAVE_ERROR lookupAndConnect(WeaveConnection *aConnection, |
| uint64_t aServiceEp, |
| WeaveAuthMode aAuthMode, |
| void *aAppState, |
| WeaveConnection::ConnectionCompleteFunct aHandler, |
| const uint32_t aConnectTimeoutMsecs = 0, |
| const InterfaceId aConnectIntf = INET_NULL_INTERFACEID); |
| |
| WEAVE_ERROR cacheDirectory(MessageIterator &, uint8_t, uint8_t *&); |
| WEAVE_ERROR cacheSuffixes(MessageIterator &, uint8_t, uint8_t *&); |
| WEAVE_ERROR calculateEntryLength(uint8_t *entryStart, uint8_t entryCtrlByte, uint16_t *entryLen); |
| /* |
| * A group of methods that clear up working state and free |
| * resources - generally in the case of a failure. one of |
| * them calls the error handler and the other calls the |
| * status handler. |
| * |
| */ |
| |
| void fail(WEAVE_ERROR aError); |
| void transactionsErrorOut(WEAVE_ERROR); |
| void transactionsReportStatus(StatusReport &aReport); |
| void cleanupExchangeContext(void); |
| void cleanupExchangeContext(WEAVE_ERROR aErr); |
| void clearWorkingState(void); |
| |
| /** |
| * This method clears the cache state of the manager including the |
| * "relocated" flag. |
| */ |
| inline void clearCacheState(void) |
| { |
| mCacheState = kServiceMgrState_Initial; |
| mWasRelocated = false; |
| } |
| |
| WEAVE_ERROR handleTimeInfo(MessageIterator &itMsg); |
| |
| // data members |
| |
| ConnectRequest mConnectRequestPool[kConnectRequestPoolSize]; |
| WeaveExchangeManager *mExchangeManager; ///< the exchange manager to use for everything |
| WeaveConnection *mConnection; ///< a connection to stash here while it's awaiting completion |
| ExchangeContext *mExchangeContext; ///< the exchange context specifically for directory profile exchanges |
| RootDirectoryAccessor mAccessor; ///< how to get at the root directory |
| Extent mDirectory; ///< the working directory |
| Extent mSuffixTable; ///< the (optional) suffix table |
| Extent mCache; ///< all of this stuff needs to be cached somewhere in memory |
| uint8_t mCacheState; ///< and the state of the cache | initial, resolving, resolved | |
| bool mWasRelocated; ///< true iff the service manager has been relocated once. |
| WeaveAuthMode mDirAuthMode; ///< the authentication mode to use when talking to the directory service. |
| uint32_t mDirAndSuffTableSize; ///< the size of the directory and suffix table in the cache. |
| |
| /** |
| * Callback happens right before we send out the service endpoing query request |
| */ |
| OnServiceEndpointQueryBegin mServiceEndpointQueryBegin; |
| |
| /** |
| * Callback happens right after we receive a service endpoing query response with time |
| * information |
| */ |
| OnServiceEndpointQueryEndWithTimeInfo mServiceEndpointQueryEndWithTimeInfo; |
| }; |
| |
| }; // ServiceDirectory |
| }; // Profiles |
| }; // Weave |
| }; // nl |
| |
| #endif // WEAVE_CONFIG_ENABLE_SERVICE_DIRECTORY |
| #endif // _WSD_PROFILE_H |
