Plugin:MirLua/Module/m database: Difference between revisions

From Miranda NG
Jump to navigation Jump to search
mNo edit summary
(Marked this version for translation)
 
(4 intermediate revisions by one other user not shown)
Line 1: Line 1:
{{PageLang|en}}
<languages/>
<translate>
<!--T:1-->
Allows you to access data and contacts in user profile database.
Allows you to access data and contacts in user profile database.
</translate>


Include module: <code>local db = require('m_database')</code>
{{Ls|MirLua/Modules/include_info}} <code>local db = require('m_database')</code>


{{Note|Parameters written in '''''bold italics''''' are obligatory.}}
__TOC__
 
<translate>
== Contacts == <!--T:2-->
</translate>
 
=== Contacts ===
<translate><!--T:3--> Iterator for list of contacts.</translate>
 
==== {{Ls|MirLua/Modules/parameters}} ====
{| class="wikitable"
|-
! scope="col" | {{Ls|MirLua/Modules/param_name}}
! scope="col" | {{Ls|MirLua/Modules/required_param}}
! scope="col" | {{Ls|Content/TableHeaders/type}}
! scope="col" | {{Ls|Content/TableHeaders/description}}
|-
! scope="row" class="MirLuaParametersTable-parameter" | name
| style="text-align:center" | {{Ls|YesNo/yes}}
| style="text-align:center" | <code>string</code>
| <translate><!--T:4--> Protocol name.</translate>
|}


==== {{Ls|MirLua/Modules/result}} ====
{{nbsp|5}}{{Ls|MirLua/Modules/type}} <code>number</code>


__TOC__
{{nbsp|5}}<translate><!--T:5--> Returns contact number. The list ends in element with <tvar|nil><code>nil</code></> value.</translate>


== Contacts ==
==== {{Ls|MirLua/Modules/example}} ====
=== Contacts ===
Iterator for list of contacts.
;Parameters
: ''name''
:: Type: '''string'''
:: Protocol name.
;Result
: Type: '''number'''
: Returns contact number. The list ends in element with '''nil''' value.
;Example
{{Content:MirLua/Example|code=
{{Content:MirLua/Example|code=
for hContact in db.Contacts('JABBER_1') do
for hContact in db.Contacts('JABBER_1') do
Line 26: Line 42:
}}
}}


<translate>
== Events == <!--T:6-->
</translate>


== Events ==
=== GetEventCount ===
=== GetEventCount ===
Number of events for a contact.
<translate><!--T:7--> Number of events for a contact.</translate>
;Parameters
 
: '''''hContact'''''
==== {{Ls|MirLua/Modules/parameters}} ====
:: Type: '''number'''
{| class="wikitable"
:: Contact number.
|-
;Result
! scope="col" | {{Ls|MirLua/Modules/param_name}}
: Type: '''number'''
! scope="col" | {{Ls|MirLua/Modules/required_param}}
: Returns number of events.
! scope="col" | {{Ls|Content/TableHeaders/type}}
;Example
! scope="col" | {{Ls|Content/TableHeaders/description}}
|-
! scope="row" class="MirLuaParametersTable-parameter" | hContact
| style="text-align:center" | {{Ls|YesNo/yes}}
| style="text-align:center" | <code>number</code>
| <translate><!--T:8--> Contact number.</translate>
|}
 
==== {{Ls|MirLua/Modules/result}} ====
{{nbsp|5}}{{Ls|MirLua/Modules/type}} <code>number</code>
 
{{nbsp|5}}<translate><!--T:9--> Returns number of events.</translate>
 
==== {{Ls|MirLua/Modules/example}} ====
{{Content:MirLua/Example|code=db.GetEventCount(hContact)}}
{{Content:MirLua/Example|code=db.GetEventCount(hContact)}}
----


=== Events ===
=== Events ===
Iterator for contact's event list from the first to the last.
<translate><!--T:10--> Iterator for contact's event list from the first to the last.</translate>
;Parameters
 
: '''''hContact'''''
==== {{Ls|MirLua/Modules/parameters}} ====
:: Type: '''number'''
{| class="wikitable"
:: Contact number.
|-
;Result
! scope="col" | {{Ls|MirLua/Modules/param_name}}
: Type: '''number'''
! scope="col" | {{Ls|MirLua/Modules/required_param}}
: Returns event number. The list ends in element with '''nil''' value.
! scope="col" | {{Ls|Content/TableHeaders/type}}
;Example
! scope="col" | {{Ls|Content/TableHeaders/description}}
|-
! scope="row" class="MirLuaParametersTable-parameter" | hContact
| style="text-align:center" | {{Ls|YesNo/yes}}
| style="text-align:center" | <code>number</code>
| <translate><!--T:11--> Contact number.</translate>
|}
 
==== {{Ls|MirLua/Modules/result}} ====
{{nbsp|5}}{{Ls|MirLua/Modules/type}} <code>number</code>
 
{{nbsp|5}}<translate><!--T:12--> Returns event number. The list ends in element with <tvar|nil><code>nil</code></> value.</translate>
 
==== {{Ls|MirLua/Modules/example}} ====
{{Content:MirLua/Example|code=for hEvent in db.Events(hContact) do
{{Content:MirLua/Example|code=for hEvent in db.Events(hContact) do
   local event = totable(hEvent, "DBEVENTINFO")
   local event = totable(hEvent, "DBEVENTINFO")
Line 55: Line 100:
end
end
}}
}}
----


=== EventsFromEnd ===
=== EventsFromEnd ===
Iterator for contact's event list from the last to the first.
<translate><!--T:13--> Iterator for contact's event list from the last to the first.</translate>
;Parameters
 
: '''''hContact'''''
==== {{Ls|MirLua/Modules/parameters}} ====
:: Type: '''number'''
{| class="wikitable"
:: Contact number.
|-
;Result
! scope="col" | {{Ls|MirLua/Modules/param_name}}
: Type: '''number'''
! scope="col" | {{Ls|MirLua/Modules/required_param}}
: Returns event number. The list ends in element with '''nil''' value.
! scope="col" | {{Ls|Content/TableHeaders/type}}
;Example
! scope="col" | {{Ls|Content/TableHeaders/description}}
|-
! scope="row" class="MirLuaParametersTable-parameter" | hContact
| style="text-align:center" | {{Ls|YesNo/yes}}
| style="text-align:center" | <code>number</code>
| <translate><!--T:14--> Contact number.</translate>
|}
 
==== {{Ls|MirLua/Modules/result}} ====
{{nbsp|5}}{{Ls|MirLua/Modules/type}} <code>number</code>
 
{{nbsp|5}}<translate><!--T:15--> Returns event number. The list ends in element with <tvar|nil><code>nil</code></> value.</translate>
 
==== {{Ls|MirLua/Modules/example}} ====
{{Content:MirLua/Example|code=
{{Content:MirLua/Example|code=
for hEvent in db.EventsFromEnd(hContact) do
for hEvent in db.EventsFromEnd(hContact) do
Line 73: Line 132:
}}
}}


<translate>
== Settings == <!--T:16-->
</translate>


== Settings ==
=== GetSetting ===
=== GetSetting ===
Returns value of a setting.
<translate><!--T:17--> Returns value of a setting.</translate>
;Parameters
 
: ''hContact''
==== {{Ls|MirLua/Modules/parameters}} ====
:: Type: '''number'''
{| class="wikitable"
:: Contact number or '''nil'''.
|-
: '''''module'''''
! scope="col" | {{Ls|MirLua/Modules/param_name}}
:: Type: '''string'''
! scope="col" | {{Ls|MirLua/Modules/required_param}}
:: Module name.
! scope="col" | {{Ls|Content/TableHeaders/type}}
: '''''setting'''''
! scope="col" | {{Ls|Content/TableHeaders/description}}
:: Type: '''string'''
|-
:: Setting name.
! scope="row" class="MirLuaParametersTable-parameter" | hContact
: ''value''
| style="text-align:center" | {{Ls|YesNo/yes}}
:: Type: '''number''', '''string'''
| style="text-align:center" | <code>number</code>
:: Default value.
| <translate><!--T:18--> Contact number or <tvar|nil><code>nil</code></>.</translate>
;Result
|-
: Type: '''number'''
! scope="row" class="MirLuaParametersTable-parameter" | module
: Returns value of a setting or default value or '''nil'''.
| style="text-align:center" | {{Ls|YesNo/yes}}
;Example
| style="text-align:center" | <code>string</code>
| <translate><!--T:19--> Module name.</translate>
|-
! scope="row" class="MirLuaParametersTable-parameter" | setting
| style="text-align:center" | {{Ls|YesNo/yes}}
| style="text-align:center" | <code>string</code>
| <translate><!--T:20--> Setting name.</translate>
|-
! scope="row" class="MirLuaParametersTable-parameter" | value
| style="text-align:center" | {{Ls|YesNo/no}}
| style="text-align:center" | <code>number</code>, <code>string</code>
| <translate><!--T:21--> Default value.</translate>
|}
 
==== {{Ls|MirLua/Modules/result}} ====
{{nbsp|5}}{{Ls|MirLua/Modules/type}} <code>number</code>
 
{{nbsp|5}}<translate><!--T:22--> Returns value of a setting or default value or <tvar|nil><code>nil</code></>.</translate>
 
==== {{Ls|MirLua/Modules/example}} ====
{{Content:MirLua/Example|code=db.GetSetting(nil, 'test', 'some')}}
{{Content:MirLua/Example|code=db.GetSetting(nil, 'test', 'some')}}
----


=== Settings ===
=== Settings ===
Iterator for module (group of settings).
<translate><!--T:23--> Iterator for module (group of settings).</translate>
;Parameters
 
: ''hContact''
==== {{Ls|MirLua/Modules/parameters}} ====
:: Type: '''number'''
{| class="wikitable"
:: Contact number or '''nil'''.
|-
: '''''module'''''
! scope="col" | {{Ls|MirLua/Modules/param_name}}
:: Type: '''string'''
! scope="col" | {{Ls|MirLua/Modules/required_param}}
:: Module name.
! scope="col" | {{Ls|Content/TableHeaders/type}}
;Result
! scope="col" | {{Ls|Content/TableHeaders/description}}
: Type: '''number'''
|-
: Returns module name. The list ends in element with '''nil''' value.
! scope="row" class="MirLuaParametersTable-parameter" | hContact
;Example
| style="text-align:center" | {{Ls|YesNo/yes}}
| style="text-align:center" | <code>number</code>
| <translate><!--T:24--> Contact number or <tvar|nil><code>nil</code></>.</translate>
|-
! scope="row" class="MirLuaParametersTable-parameter" | module
| style="text-align:center" | {{Ls|YesNo/yes}}
| style="text-align:center" | <code>string</code>
| <translate><!--T:25--> Module name.</translate>
|}
 
==== {{Ls|MirLua/Modules/result}} ====
{{nbsp|5}}{{Ls|MirLua/Modules/type}} <code>number</code>
 
{{nbsp|5}}<translate><!--T:26--> Returns module name. The list ends in element with <tvar|nil><code>nil</code></> value.</translate>
 
==== {{Ls|MirLua/Modules/example}} ====
{{Content:MirLua/Example|code=
{{Content:MirLua/Example|code=
for setting in db.Settings(nil, 'CList') do
for setting in db.Settings(nil, 'CList') do
Line 116: Line 212:
end
end
}}
}}
----


=== WriteSetting ===
=== WriteSetting ===
Saves a value to database.
<translate><!--T:27--> Saves a value to database.</translate>
;Parameters
 
: ''hContact''
==== {{Ls|MirLua/Modules/parameters}} ====
:: Type: '''number'''
{| class="wikitable"
:: Contact number or '''nil'''.
|-
: '''''module'''''
! scope="col" | {{Ls|MirLua/Modules/param_name}}
:: Type: '''string'''
! scope="col" | {{Ls|MirLua/Modules/required_param}}
:: Module name.
! scope="col" | {{Ls|Content/TableHeaders/type}}
: '''''setting'''''
! scope="col" | {{Ls|Content/TableHeaders/description}}
:: Type: '''string'''
|-
:: Setting name.
! scope="row" class="MirLuaParametersTable-parameter" | hContact
;Result
| style="text-align:center" | {{Ls|YesNo/yes}}
: Type: '''boolean'''
| style="text-align:center" | <code>number</code>
: Returns '''true''' in case of success, else '''false'''.
| <translate><!--T:28--> Contact number or <tvar|nil><code>nil</code></>.</translate>
;Example
|-
! scope="row" class="MirLuaParametersTable-parameter" | module
| style="text-align:center" | {{Ls|YesNo/yes}}
| style="text-align:center" | <code>string</code>
| <translate><!--T:29--> Module name.</translate>
|-
! scope="row" class="MirLuaParametersTable-parameter" | setting
| style="text-align:center" | {{Ls|YesNo/yes}}
| style="text-align:center" | <code>string</code>
| <translate><!--T:30--> Setting name.</translate>
|-
! scope="row" class="MirLuaParametersTable-parameter" | value
| style="text-align:center" | {{Ls|YesNo/yes}}
| style="text-align:center" | <code>boolean</code>, <code>number</code>, <code>string</code>, <code>table</code> <translate><!--T:31--> (array of bytes)</translate>
| <translate><!--T:32--> Setting value.</translate>
|-
! scope="row" class="MirLuaParametersTable-parameter" | type
| style="text-align:center" | {{Ls|YesNo/no}}
| style="text-align:center" | <code>number</code>
| <translate><!--T:33--> Type of setting. Takes values:</translate>
* 1 = DBVT_BYTE
* 2 = DBVT_WORD
* 4 = DBVT_DWORD
* 252 = DBVT_WCHAR
* 253 = DBVT_UTF8
* 254 = DBVT_BLOB
* 255 = DBVT_ASCIIZ
|}
 
==== {{Ls|MirLua/Modules/result}} ====
{{nbsp|5}}{{Ls|MirLua/Modules/type}} <code>boolean</code>
 
{{nbsp|5}}<translate><!--T:34--> Returns <tvar|true><code>true</code></> on success, otherwise <tvar|false><code>false</code></>.</translate>
 
==== {{Ls|MirLua/Modules/example}} ====
{{Content:MirLua/Example|code=db.WriteSetting(nil, 'test', 'some', true)}}
{{Content:MirLua/Example|code=db.WriteSetting(nil, 'test', 'some', true)}}
----


=== DeleteSetting ===
=== DeleteSetting ===
Deletes a setting.
<translate><!--T:35--> Deletes a setting.</translate>
;Parameters
 
: ''hContact''
==== {{Ls|MirLua/Modules/parameters}} ====
:: Type: '''number'''
{| class="wikitable"
:: Contact number or '''nil'''.
|-
: '''''module'''''
! scope="col" | {{Ls|MirLua/Modules/param_name}}
:: Type: '''string'''
! scope="col" | {{Ls|MirLua/Modules/required_param}}
:: Module name.
! scope="col" | {{Ls|Content/TableHeaders/type}}
: '''''setting'''''
! scope="col" | {{Ls|Content/TableHeaders/description}}
:: Type: '''string'''
|-
:: Setting name.
! scope="row" class="MirLuaParametersTable-parameter" | hContact
;Result
| style="text-align:center" | {{Ls|YesNo/yes}}
: Type: '''boolean'''
| style="text-align:center" | <code>number</code>
: Returns '''true''' in case of success, else '''false'''.
| <translate><!--T:36--> Contact number or <tvar|nil><code>nil</code></>.</translate>
;Example
|-
! scope="row" class="MirLuaParametersTable-parameter" | module
| style="text-align:center" | {{Ls|YesNo/yes}}
| style="text-align:center" | <code>string</code>
| <translate><!--T:37--> Module name.</translate>
|-
! scope="row" class="MirLuaParametersTable-parameter" | setting
| style="text-align:center" | {{Ls|YesNo/yes}}
| style="text-align:center" | <code>string</code>
| <translate><!--T:38--> Setting name.</translate>
|}
 
==== {{Ls|MirLua/Modules/result}} ====
{{nbsp|5}}{{Ls|MirLua/Modules/type}} <code>boolean</code>
 
{{nbsp|5}}<translate><!--T:39--> Returns <tvar|true><code>true</code></> on success, otherwise <tvar|false><code>false</code></>.</translate>
 
==== {{Ls|MirLua/Modules/example}} ====
{{Content:MirLua/Example|code=db.DeleteSetting(nil, 'test', 'some')}}
{{Content:MirLua/Example|code=db.DeleteSetting(nil, 'test', 'some')}}
----


=== DeleteModule ===
=== DeleteModule ===
Deletes a module (group of settings).
<translate><!--T:40--> Deletes a module (group of settings).</translate>
;Parameters
 
: ''hContact''
==== {{Ls|MirLua/Modules/parameters}} ====
:: Type: '''number'''
{| class="wikitable"
:: Contact number or '''nil'''.
|-
: '''''module'''''
! scope="col" | {{Ls|MirLua/Modules/param_name}}
:: Type: '''string'''
! scope="col" | {{Ls|MirLua/Modules/required_param}}
:: Module name.
! scope="col" | {{Ls|Content/TableHeaders/type}}
;Result
! scope="col" | {{Ls|Content/TableHeaders/description}}
: Type: '''boolean'''
|-
: Returns '''true''' in case of success, else '''false'''.
! scope="row" class="MirLuaParametersTable-parameter" | hContact
;Example
| style="text-align:center" | {{Ls|YesNo/yes}}
| style="text-align:center" | <code>number</code>
| <translate><!--T:41--> Contact number or <tvar|nil><code>nil</code></>.</translate>
|-
! scope="row" class="MirLuaParametersTable-parameter" | module
| style="text-align:center" | {{Ls|YesNo/yes}}
| style="text-align:center" | <code>string</code>
| <translate><!--T:42--> Module name.</translate>
|}
 
==== {{Ls|MirLua/Modules/result}} ====
{{nbsp|5}}{{Ls|MirLua/Modules/type}} <code>boolean</code>
 
{{nbsp|5}}<translate><!--T:43--> Returns <tvar|true><code>true</code></> on success, otherwise <tvar|false><code>false</code></>.</translate>
 
==== {{Ls|MirLua/Modules/example}} ====
{{Content:MirLua/Example|code=db.DeleteModule(nil, 'test')}}
{{Content:MirLua/Example|code=db.DeleteModule(nil, 'test')}}
[[Category:Tutorials (en)]]

Latest revision as of 02:03, 10 February 2022

Other languages:
  • English

Allows you to access data and contacts in user profile database.

Include module: local db = require('m_database')

Contacts

Contacts

Iterator for list of contacts.

Parameters

Parameter name Required Type Description
name Yes string Protocol name.

Result

     Type: number

     Returns contact number. The list ends in element with nil value.

Example

for hContact in db.Contacts('JABBER_1') do
  print(db.GetSetting(hContact, 'JABBER_1', 'Nick'))
end

Events

GetEventCount

Number of events for a contact.

Parameters

Parameter name Required Type Description
hContact Yes number Contact number.

Result

     Type: number

     Returns number of events.

Example

db.GetEventCount(hContact)

Events

Iterator for contact's event list from the first to the last.

Parameters

Parameter name Required Type Description
hContact Yes number Contact number.

Result

     Type: number

     Returns event number. The list ends in element with nil value.

Example

for hEvent in db.Events(hContact) do
  local event = totable(hEvent, "DBEVENTINFO")
  print(event.Timestamp, event.Blob)
end

EventsFromEnd

Iterator for contact's event list from the last to the first.

Parameters

Parameter name Required Type Description
hContact Yes number Contact number.

Result

     Type: number

     Returns event number. The list ends in element with nil value.

Example

for hEvent in db.EventsFromEnd(hContact) do
  local event = totable(hEvent, "DBEVENTINFO")
  print(event.Timestamp, event.Blob)
end

Settings

GetSetting

Returns value of a setting.

Parameters

Parameter name Required Type Description
hContact Yes number Contact number or nil.
module Yes string Module name.
setting Yes string Setting name.
value No number, string Default value.

Result

     Type: number

     Returns value of a setting or default value or nil.

Example

db.GetSetting(nil, 'test', 'some')

Settings

Iterator for module (group of settings).

Parameters

Parameter name Required Type Description
hContact Yes number Contact number or nil.
module Yes string Module name.

Result

     Type: number

     Returns module name. The list ends in element with nil value.

Example

for setting in db.Settings(nil, 'CList') do
  local message = string.format("%s/%s = ", 'CList', setting, ...)
   .. db.GetSetting(nil, 'CList', setting)
  print(message)
end

WriteSetting

Saves a value to database.

Parameters

Parameter name Required Type Description
hContact Yes number Contact number or nil.
module Yes string Module name.
setting Yes string Setting name.
value Yes boolean, number, string, table (array of bytes) Setting value.
type No number Type of setting. Takes values:
  • 1 = DBVT_BYTE
  • 2 = DBVT_WORD
  • 4 = DBVT_DWORD
  • 252 = DBVT_WCHAR
  • 253 = DBVT_UTF8
  • 254 = DBVT_BLOB
  • 255 = DBVT_ASCIIZ

Result

     Type: boolean

     Returns true on success, otherwise false.

Example

db.WriteSetting(nil, 'test', 'some', true)

DeleteSetting

Deletes a setting.

Parameters

Parameter name Required Type Description
hContact Yes number Contact number or nil.
module Yes string Module name.
setting Yes string Setting name.

Result

     Type: boolean

     Returns true on success, otherwise false.

Example

db.DeleteSetting(nil, 'test', 'some')

DeleteModule

Deletes a module (group of settings).

Parameters

Parameter name Required Type Description
hContact Yes number Contact number or nil.
module Yes string Module name.

Result

     Type: boolean

     Returns true on success, otherwise false.

Example

db.DeleteModule(nil, 'test')
Retrieved from "https://wiki.miranda-ng.org/index.php?title=Plugin:MirLua/Module/m_database&oldid=41202"