From e3aabeacf9e2c2a7aab608ed173a7070af266e2b Mon Sep 17 00:00:00 2001 From: Lars Op den Kamp Date: Fri, 28 Sep 2012 14:10:27 +0200 Subject: [PATCH] added xmldoc for LibCecSharp --- project/LibCecSharp.vcproj | 4 + src/LibCecSharp/LibCecSharp.cpp | 302 ++++++++++++++++++++++++++++++-- 2 files changed, 292 insertions(+), 14 deletions(-) diff --git a/project/LibCecSharp.vcproj b/project/LibCecSharp.vcproj index 39f93b5..7bce4c0 100644 --- a/project/LibCecSharp.vcproj +++ b/project/LibCecSharp.vcproj @@ -51,6 +51,7 @@ PreprocessorDefinitions="_DEBUG;_CRT_SECURE_NO_WARNINGS" RuntimeLibrary="3" UsePrecompiledHeader="0" + GenerateXMLDocumentationFiles="true" WarningLevel="3" WarnAsError="true" DebugInformationFormat="3" @@ -125,6 +126,7 @@ PreprocessorDefinitions="_DEBUG;_CRT_SECURE_NO_WARNINGS" RuntimeLibrary="3" UsePrecompiledHeader="0" + GenerateXMLDocumentationFiles="true" WarningLevel="3" WarnAsError="true" DebugInformationFormat="3" @@ -200,6 +202,7 @@ PreprocessorDefinitions="NDEBUG;_CRT_SECURE_NO_WARNINGS" RuntimeLibrary="2" UsePrecompiledHeader="0" + GenerateXMLDocumentationFiles="true" WarningLevel="3" WarnAsError="true" DebugInformationFormat="3" @@ -273,6 +276,7 @@ PreprocessorDefinitions="NDEBUG;_CRT_SECURE_NO_WARNINGS" RuntimeLibrary="2" UsePrecompiledHeader="0" + GenerateXMLDocumentationFiles="true" WarningLevel="3" WarnAsError="true" DebugInformationFormat="3" diff --git a/src/LibCecSharp/LibCecSharp.cpp b/src/LibCecSharp/LibCecSharp.cpp index 81c857f..bf33d1f 100644 --- a/src/LibCecSharp/LibCecSharp.cpp +++ b/src/LibCecSharp/LibCecSharp.cpp @@ -142,6 +142,11 @@ namespace CecSharp } public: + /// + /// Try to find all connected CEC adapters. + /// + /// The path filter for adapters. Leave empty to return all adapters. + /// The adapters that were found. array ^ FindAdapters(String ^ path) { cec_adapter *devices = new cec_adapter[10]; @@ -160,6 +165,12 @@ namespace CecSharp return adapters; } + /// + /// Open a connection to the CEC adapter. + /// + /// The COM port of the adapter + /// Connection timeout in milliseconds + /// True when a connection was opened, false otherwise. bool Open(String ^ strPort, int iTimeoutMs) { CecCallbackMethods::EnableCallbacks(m_callbacks); @@ -171,12 +182,18 @@ namespace CecSharp return bReturn; } + /// + /// Close the connection to the CEC adapter + /// void Close(void) { DisableCallbacks(); m_libCec->Close(); } + /// + /// Disable all calls to callback methods. + /// virtual void DisableCallbacks(void) override { // delete the callbacks, since these might already have been destroyed in .NET @@ -185,6 +202,11 @@ namespace CecSharp m_libCec->EnableCallbacks(NULL, NULL); } + /// + /// Enable or change the callback methods that libCEC uses to send changes to the client application. + /// + /// The new callback methods to use. + /// True when the callbacks were changed, false otherwise virtual bool EnableCallbacks(CecCallbackMethods ^ callbacks) override { if (m_libCec && CecCallbackMethods::EnableCallbacks(callbacks)) @@ -193,31 +215,59 @@ namespace CecSharp return false; } + /// + /// Sends a ping command to the adapter, to check if it's responding. + /// + /// True when the ping was succesful, false otherwise bool PingAdapter(void) { return m_libCec->PingAdapter(); } + /// + /// Start the bootloader of the CEC adapter. Closes the connection when successful. + /// + /// True when the command was sent successfully, false otherwise. bool StartBootloader(void) { return m_libCec->StartBootloader(); } + /// + /// Get the minimal version of libCEC that this version of libCEC can interface with. + /// + /// Deprecated: use LibCECConfiguration instead + /// The minimal version int GetMinLibVersion(void) { return m_libCec->GetMinLibVersion(); } + /// + /// Get the major version of libCEC. + /// + /// Deprecated: use LibCECConfiguration instead + /// The major version int GetLibVersionMajor(void) { return m_libCec->GetLibVersionMajor(); } + /// + /// Get the minor version of libCEC. + /// + /// Deprecated: use LibCECConfiguration instead + /// The minor version int GetLibVersionMinor(void) { return m_libCec->GetLibVersionMinor(); } + /// + /// Get the next log message from the buffer, if there is one. + /// + /// Deprecated: use callback methods instead + /// The next log message in the buffer, or an empty message if there is none CecLogMessage ^ GetNextLogMessage(void) { cec_log_message msg; @@ -229,6 +279,11 @@ namespace CecSharp return gcnew CecLogMessage(); } + /// + /// Get the next keypress from the buffer, if there is one. + /// + /// Deprecated: use callback methods instead + /// The next keypress in the buffer, or an empty keypress if there is none CecKeypress ^ GetNextKeypress(void) { cec_keypress key; @@ -240,6 +295,11 @@ namespace CecSharp return gcnew CecKeypress(); } + /// + /// Get the next CEC command that was received from the buffer, if there is one. + /// + /// Deprecated: use callback methods instead + /// The next CEC command in the buffer, or an empty CEC command if there is none CecCommand ^ GetNextCommand(void) { cec_command command; @@ -254,6 +314,11 @@ namespace CecSharp return gcnew CecCommand(); } + /// + /// Transmit a raw CEC command over the CEC line. + /// + /// The command to transmit + /// True when the data was sent and acked, false otherwise. bool Transmit(CecCommand ^ command) { cec_command ccommand; @@ -267,56 +332,115 @@ namespace CecSharp return m_libCec->Transmit(ccommand); } + /// + /// Change the logical address on the CEC bus of the CEC adapter. libCEC automatically assigns a logical address, and this method is only available for debugging purposes. + /// + /// The CEC adapter's new logical address. + /// True when the logical address was set successfully, false otherwise. bool SetLogicalAddress(CecLogicalAddress logicalAddress) { return m_libCec->SetLogicalAddress((cec_logical_address) logicalAddress); } + /// + /// Change the physical address (HDMI port) of the CEC adapter. libCEC will try to autodetect the physical address when connecting. If it did, it's set in libcec_configuration. + /// + /// The CEC adapter's new physical address. + /// True when the physical address was set successfully, false otherwise. bool SetPhysicalAddress(uint16_t physicalAddress) { return m_libCec->SetPhysicalAddress(physicalAddress); } + /// + /// Power on the given CEC capable devices. If CECDEVICE_BROADCAST is used, then wakeDevice in libcec_configuration will be used. + /// + /// The logical address to power on. + /// True when the command was sent succesfully, false otherwise. bool PowerOnDevices(CecLogicalAddress logicalAddress) { return m_libCec->PowerOnDevices((cec_logical_address) logicalAddress); } + /// + /// Put the given CEC capable devices in standby mode. If CECDEVICE_BROADCAST is used, then standbyDevices in libcec_configuration will be used. + /// + /// The logical address of the device to put in standby. + /// True when the command was sent succesfully, false otherwise. bool StandbyDevices(CecLogicalAddress logicalAddress) { return m_libCec->StandbyDevices((cec_logical_address) logicalAddress); } + /// + /// Sends a POLL message to a device, to check if it's present and responding. + /// + /// The device to send the message to. + /// True if the POLL was acked, false otherwise. bool PollDevice(CecLogicalAddress logicalAddress) { return m_libCec->PollDevice((cec_logical_address) logicalAddress); } + /// + /// Change the active source to a device type handled by libCEC. Use CEC_DEVICE_TYPE_RESERVED to make the default type used by libCEC active. + /// + /// The new active source. Use CEC_DEVICE_TYPE_RESERVED to use the primary type + /// True when the command was sent succesfully, false otherwise. bool SetActiveSource(CecDeviceType type) { return m_libCec->SetActiveSource((cec_device_type) type); } + /// + /// Change the deck control mode, if this adapter is registered as playback or recording device. + /// + /// The new control mode. + /// True to send the new status over the CEC line. + /// True if set, false otherwise. bool SetDeckControlMode(CecDeckControlMode mode, bool sendUpdate) { return m_libCec->SetDeckControlMode((cec_deck_control_mode) mode, sendUpdate); } + /// + /// Change the deck info, if this adapter is a playback or recording device. + /// + /// The new deck info. + /// True to send the new status over the CEC line. + /// True if set, false otherwise. bool SetDeckInfo(CecDeckInfo info, bool sendUpdate) { return m_libCec->SetDeckInfo((cec_deck_info) info, sendUpdate); } + /// + /// Broadcast a message that notifies connected CEC capable devices that this device is no longer the active source. + /// + /// True when the command was sent succesfully, false otherwise. bool SetInactiveView(void) { return m_libCec->SetInactiveView(); } + /// + /// Change the menu state. This value is already changed by libCEC automatically if a device is (de)activated. + /// + /// The new state. + /// True to send the new status over the CEC line. + /// True if set, false otherwise. bool SetMenuState(CecMenuState state, bool sendUpdate) { return m_libCec->SetMenuState((cec_menu_state) state, sendUpdate); } + /// + /// Display a message on the device with the given logical address. Not supported by most TVs. + /// + /// The logical address of the device to display the message on. + /// The duration of the message + /// The message to display. + /// True when the command was sent, false otherwise. bool SetOSDString(CecLogicalAddress logicalAddress, CecDisplayControl duration, String ^ message) { marshal_context ^ context = gcnew marshal_context(); @@ -328,16 +452,31 @@ namespace CecSharp return bReturn; } + /// + /// Enable or disable monitoring mode, for debugging purposes. If monitoring mode is enabled, libCEC won't respond to any command, but only log incoming data. + /// + /// True to enable, false to disable. + /// True when switched successfully, false otherwise. bool SwitchMonitoring(bool enable) { return m_libCec->SwitchMonitoring(enable); } + /// + /// Get the CEC version of the device with the given logical address + /// + /// The logical address of the device to get the CEC version for. + /// The version or CEC_VERSION_UNKNOWN when the version couldn't be fetched. CecVersion GetDeviceCecVersion(CecLogicalAddress logicalAddress) { return (CecVersion) m_libCec->GetDeviceCecVersion((cec_logical_address) logicalAddress); } + /// + /// Get the menu language of the device with the given logical address + /// + /// The logical address of the device to get the menu language for. + /// The requested menu language. String ^ GetDeviceMenuLanguage(CecLogicalAddress logicalAddress) { cec_menu_language lang; @@ -349,21 +488,38 @@ namespace CecSharp return gcnew String(""); } + /// + /// Get the vendor ID of the device with the given logical address. + /// + /// The logical address of the device to get the vendor ID for. + /// The vendor ID or 0 if it wasn't found. CecVendorId GetDeviceVendorId(CecLogicalAddress logicalAddress) { return (CecVendorId)m_libCec->GetDeviceVendorId((cec_logical_address) logicalAddress); } + /// + /// Get the power status of the device with the given logical address. + /// + /// The logical address of the device to get the power status for. + /// The power status or CEC_POWER_STATUS_UNKNOWN if it wasn't found. CecPowerStatus GetDevicePowerStatus(CecLogicalAddress logicalAddress) { return (CecPowerStatus) m_libCec->GetDevicePowerStatus((cec_logical_address) logicalAddress); } + /// + /// Tell libCEC to poll for active devices on the bus. + /// void RescanActiveDevices(void) { m_libCec->RescanActiveDevices(); } + /// + /// Get the logical addresses of the devices that are active on the bus, including those handled by libCEC. + /// + /// The logical addresses of the active devices CecLogicalAddresses ^ GetActiveDevices(void) { CecLogicalAddresses ^ retVal = gcnew CecLogicalAddresses(); @@ -378,77 +534,154 @@ namespace CecSharp return retVal; } + /// + /// Check whether a device is active on the bus. + /// + /// The address to check. + /// True when active, false otherwise. bool IsActiveDevice(CecLogicalAddress logicalAddress) { return m_libCec->IsActiveDevice((cec_logical_address)logicalAddress); } + /// + /// Check whether a device of the given type is active on the bus. + /// + /// The type to check. + /// True when active, false otherwise. bool IsActiveDeviceType(CecDeviceType type) { return m_libCec->IsActiveDeviceType((cec_device_type)type); } + /// + /// Changes the active HDMI port. + /// + /// The device to which this libCEC is connected. + /// The new port number. + /// True when changed, false otherwise. bool SetHDMIPort(CecLogicalAddress address, uint8_t port) { return m_libCec->SetHDMIPort((cec_logical_address)address, port); } - uint8_t VolumeUp(bool wait) + /// + /// Sends a volume up keypress to an audiosystem if it's present. + /// + /// Send a key release after the keypress. + /// The new audio status. + uint8_t VolumeUp(bool sendRelease) { - return m_libCec->VolumeUp(wait); + return m_libCec->VolumeUp(sendRelease); } - uint8_t VolumeDown(bool wait) + /// + /// Sends a volume down keypress to an audiosystem if it's present. + /// + /// Send a key release after the keypress. + /// The new audio status. + uint8_t VolumeDown(bool sendRelease) { - return m_libCec->VolumeDown(wait); + return m_libCec->VolumeDown(sendRelease); } - uint8_t MuteAudio(bool wait) + /// + /// Sends a mute keypress to an audiosystem if it's present. + /// + /// Send a key release after the keypress. + /// The new audio status. + uint8_t MuteAudio(bool sendRelease) { - return m_libCec->MuteAudio(wait); + return m_libCec->MuteAudio(sendRelease); } + /// + /// Send a keypress to a device on the CEC bus. + /// + /// The logical address of the device to send the message to. + /// The key to send. + /// True to wait for a response, false otherwise. + /// True when the keypress was acked, false otherwise. bool SendKeypress(CecLogicalAddress destination, CecUserControlCode key, bool wait) { return m_libCec->SendKeypress((cec_logical_address)destination, (cec_user_control_code)key, wait); } + /// + /// Send a key release to a device on the CEC bus. + /// + /// The logical address of the device to send the message to. + /// True to wait for a response, false otherwise. + /// True when the key release was acked, false otherwise. bool SendKeyRelease(CecLogicalAddress destination, bool wait) { return m_libCec->SendKeyRelease((cec_logical_address)destination, wait); } + /// + /// Get the OSD name of a device on the CEC bus. + /// + /// The logical address of the device to get the OSD name for. + /// The OSD name. String ^ GetDeviceOSDName(CecLogicalAddress logicalAddress) { cec_osd_name osd = m_libCec->GetDeviceOSDName((cec_logical_address) logicalAddress); return gcnew String(osd.name); } + /// + /// Get the logical address of the device that is currently the active source on the CEC bus. + /// + /// The active source or CECDEVICE_UNKNOWN when unknown. CecLogicalAddress GetActiveSource() { return (CecLogicalAddress)m_libCec->GetActiveSource(); } + /// + /// Check whether a device is currently the active source on the CEC bus. + /// + /// The logical address of the device to check. + /// True when it is the active source, false otherwise. bool IsActiveSource(CecLogicalAddress logicalAddress) { return m_libCec->IsActiveSource((cec_logical_address)logicalAddress); } - uint16_t GetDevicePhysicalAddress(CecLogicalAddress iAddress) + /// + /// Get the physical address of the device with the given logical address. + /// + /// The logical address of the device to get the physical address for. + /// The physical address or 0 if it wasn't found. + uint16_t GetDevicePhysicalAddress(CecLogicalAddress address) { - return m_libCec->GetDevicePhysicalAddress((cec_logical_address)iAddress); + return m_libCec->GetDevicePhysicalAddress((cec_logical_address)address); } - bool SetStreamPath(CecLogicalAddress iAddress) + /// + /// Sets the stream path to the device on the given logical address. + /// + /// The address to activate. + /// True when the command was sent, false otherwise. + bool SetStreamPath(CecLogicalAddress address) { - return m_libCec->SetStreamPath((cec_logical_address)iAddress); + return m_libCec->SetStreamPath((cec_logical_address)address); } - bool SetStreamPath(uint16_t iPhysicalAddress) + /// + /// Sets the stream path to the device on the given physical address. + /// + /// The address to activate. + /// True when the command was sent, false otherwise. + bool SetStreamPath(uint16_t physicalAddress) { - return m_libCec->SetStreamPath(iPhysicalAddress); + return m_libCec->SetStreamPath(physicalAddress); } + /// + /// Get the list of logical addresses that libCEC is controlling + /// + /// The list of logical addresses that libCEC is controlling CecLogicalAddresses ^GetLogicalAddresses(void) { CecLogicalAddresses ^addr = gcnew CecLogicalAddresses(); @@ -459,6 +692,11 @@ namespace CecSharp return addr; } + /// + /// Get libCEC's current configuration. + /// + /// The configuration. + /// True when the configuration was updated, false otherwise. bool GetCurrentConfiguration(LibCECConfiguration ^configuration) { libcec_configuration config; @@ -472,11 +710,20 @@ namespace CecSharp return false; } + /// + /// Check whether the CEC adapter can persist a configuration. + /// + /// True when this CEC adapter can persist the user configuration, false otherwise. bool CanPersistConfiguration(void) { return m_libCec->CanPersistConfiguration(); } + /// + /// Persist the given configuration in adapter (if supported) + /// + /// The configuration to store. + /// True when the configuration was persisted, false otherwise. bool PersistConfiguration(LibCECConfiguration ^configuration) { marshal_context ^ context = gcnew marshal_context(); @@ -489,6 +736,11 @@ namespace CecSharp return bReturn; } + /// + /// Change libCEC's configuration. + /// + /// The new configuration. + /// True when the configuration was changed successfully, false otherwise. bool SetConfiguration(LibCECConfiguration ^configuration) { marshal_context ^ context = gcnew marshal_context(); @@ -501,11 +753,22 @@ namespace CecSharp return bReturn; } + /// + /// Check whether libCEC is the active source on the bus. + /// + /// True when libCEC is the active source on the bus, false otherwise. bool IsLibCECActiveSource() { return m_libCec->IsLibCECActiveSource(); } + /// + /// Get information about the given CEC adapter. + /// + /// The COM port to which the device is connected + /// The device configuration + /// The timeout in milliseconds + /// True when the device was found, false otherwise bool GetDeviceInformation(String ^ port, LibCECConfiguration ^configuration, uint32_t timeoutMs) { bool bReturn(false); @@ -537,13 +800,13 @@ namespace CecSharp const char *retVal = m_libCec->ToString((cec_vendor_id)iVendorId); return gcnew String(retVal); } - + String ^ ToString(CecVersion iVersion) { const char *retVal = m_libCec->ToString((cec_version)iVersion); return gcnew String(retVal); } - + String ^ ToString(CecPowerStatus iState) { const char *retVal = m_libCec->ToString((cec_power_status)iState); @@ -598,12 +861,23 @@ namespace CecSharp return gcnew String(retVal); } + /// + /// Get a string with information about how libCEC was compiled. + /// + /// A string with information about how libCEC was compiled. String ^ GetLibInfo() { const char *retVal = m_libCec->GetLibInfo(); return gcnew String(retVal); } + /// + /// Calling this method will initialise the host on which libCEC is running. + /// On the RPi, it calls bcm_host_init(), which may only be called once per process, and is called by any process using + /// the video api on that system. So only call this method if libCEC is used in an application that + /// does not already initialise the video api. + /// + /// Should be called as first call to libCEC, directly after CECInitialise() and before using Open() void InitVideoStandalone() { m_libCec->InitVideoStandalone(); -- 2.34.1