[This is preliminary documentation and is subject to change. Blank topics are included as placeholders.]

Returns information about the analog devices you can manage using Microsoft Communications Server 2010. An analog device is a telephone (or fax machine) that is connected to the Public Switched Telephone Network.

Syntax

Get-CsAnalogDevice [-Identity] <UserIdParameter>] [-Filter <String>] [-LdapFilter <String>] [-OU <OUIdParameter>] [-DomainController <Fqdn>] [-Credential <PSCredential>] [-ResultSize <Unlimited`1>] [-Verbose] [-Debug] [-ErrorAction <ActionPreference>] [-WarningAction <ActionPreference>] [-ErrorVariable <String>] [-WarningVariable <String>] [-OutVariable <String>] [-OutBuffer <Int32>]

Parameters

Parameter Required Type Description

Identity

Required

User ID Parameter

Unique identifier for the analog device. Analog devices are identified using the Active Directory distinguished name of the associated contact object. Analog devices, by default, use a GUID (globally unique identifier) as their common name; that means devices will typically have an Identity similar to this: CN={ce84964a-c4da-4622-ad34-c54ff3ed361f},OU=Redmond,DC=Litwareinc,DC=com.

Note. By using the –DN parameter when calling New-CsAnalogDevice, administrators can give analog devices a more user-friendly common name (e.g., Building 14 Lobby as opposed to {ce84964a-c4da-4622-ad34-c54ff3ed361f}).

Filter

Optional

String

Enables you to limit the returned data by filtering on Microsoft Communications Server-specific attributes. For example, you can limit returned data to analog device contact objects that have been assigned a specific voice policy, or contacts that have not been assigned a specific voice policy.

The -Filter parameter uses the same Windows PowerShell filtering syntax that is used by the Where-Object cmdlet. For example, a filter that returns only fax machines would look like this, with AnalogFax representing the Active Directory Domain Services attribute, -eq representing the comparison operator (equal to), and $True (a built-in Windows PowerShell variable) representing the filter value:

{AnalogFax -eq $True}

For details, see the about_communications_server_filters Help topic.

LdapFilter

Optional

String

Enables you to limit the returned data by filtering on generic Active Directory Domain Services attributes (that is, attributes that are not specific to Microsoft Communications Server). For example, you can limit returned data to contact objects that have been assigned to a specific department or are located in a specific building.

The -LDAPFilter parameter uses the LDAP query language when creating filters. For example, a filter that returns only contact objects representing analog devices in the city of Redmond would look like this:

-LDAPFilter "l=Redmond"

In the preceding filter, "l" represents the Active Directory Domain Services attribute (locality); "=" represents the comparison operator (equal to); and "Redmond" represents the filter value.

For details, see the about_ldap_filters Help topic.

OU

Optional

Active Directory distinguished name

Enables you to limit the retrieved information to contact objects found in a specific Active Directory Domain Services organizational unit (OU). This returns data from both the specified OU and any of its child OUs. For example, if the Finance OU has two child OUS - AccountsPayable and AccountsReceivable – common area phone information will be returned from each of these OUs.

When specifying an OU, use the distinguished name of that container; for example: OU=Finance,dc=litwareinc,dc=com.

DomainController

Optional

String

Enables you to connect to the specified domain controller in order to retrieve contact information. To connect to a particular domain controller, include the -DomainController parameter followed by the computer name (for example, atl-mcs-001) or its fully qualified domain name (for example, atl-mcs-001.litwareinc.com).

Credential

Optional

PS Credential object

Enables you to run the Get-CsAnalogDevice cmdlet under alternate credentials. This might be required if the account you used to log on to the Windows does not have the necessary privileges required to work with contact objects.

To use the -Credential parameter you must first create a PSCredential object using the Get-Credential cmdlet. For details, see the Get-Credential cmdlet Help topic.

ResultSize

Optional

Integer

Enables you to limit the number of records returned by a command. For example, to return seven analog devices (regardless of how many analog devices are in your forest) include the -ResultSize parameter and set the parameter value to 7. Note that there is no way to guarantee which 7 phones will be returned. If you set the ResultSize to 7 but you have only three analog devices in your forest, the command will return those three devices and then complete without error.

The result size can be set to any whole number between 0 and 2147483647, inclusive. If set to 0 the command will run, but no data will be returned.

Detailed Description

Analog devices include telephones, fax machines, modems, and TTY/TTD (Teletype/Telecommunication Devices for the Deaf) devices that are connected to the Public Switched Telephone Network (PSTN). Unlike devices that take advantage of Enterprise Voice (Microsoft’s implementation of Voice over IP), analog devices do not transmit information using digital packets; instead, information is transmitted using a continuous signal. This signal is commonly referred to as an analog signal; hence the term "analog devices.")

Many organizations still are heavily invested in analog devices. In order to enable administrators to manage analog devices, Microsoft Communications Server lets you associate analog devices with Active Directory contact objects. After a device has been associated with a contact object you can then manage the analog device by assigning policies and dial plans to the contact.

Get-CsAnalogDevice provides a way for you to retrieve information about the analog devices configured for use in your organization. If you call Get-CsAnalogDevice without any parameters, the cmdlet will return information about all your analog devices. Optional parameters provide different ways for you to filter information; for example, you can return all the devices that have contact objects in a specified OU; all the contacts objects located in a specified building; etc.

Return Types

Get-CsAnalogDevice returns instances of the Microsoft.Rtc.Management.ADConnect.Schema.OCSADAnalogDeviceContact object.

Examples

-------------------------- Example 1 ------------------------

Copy Code
Get-CsAnalogDevice

The command shown in Example 1 returns a collection of all the analog devices currently configured for use in the organization. This is done by calling Get-CsAnalogDevice without any parameters.

-------------------------- Example 2 ------------------------

Copy Code
Get-CsAnalogDevice | Select-Object DisplayName, LineUri

In Example 2, only two property values - DisplayName and LineUri - are returned for all the analog devices in the organization. To carry out this task, the command first calls Get-CsAnalogDevice without any parameters; this returns all the property values for all the analog devices in the organization. This collection is then piped to the Select-Object cmdlet, which picks out - and shows onscreen - only the values for the DisplayName and the LineUri properties.

-------------------------- Example 3 ------------------------

Copy Code
Get-CsAnalogDevice -Filter {DisplayName -eq "Building 14 Receptionist"}

Example 3 returns information about the analog device that has the Active Directory display name Building 14 Receptionist. To do this, the command calls Get-CsAnalogDevice and the -Filter parameter; the filter value {DisplayName -eq "Building 14 Receptionist"} limits the returned objects to analog devices where the DisplayName property is equal to (-eq) "Building 14 Receptionist".

-------------------------- Example 4 ------------------------

Copy Code
Get-CsAnalogDevice -Filter {Gateway -eq "192.168.0.240"}

The preceding command returns all the analog devices configured for the gateway 192.168.0.240. This is done by calling Get-CsAnalogDevice and including the -Filter parameter; the filter value "192.168.0.240" ensures that the only objects returned are analog devices where the Gateway property is equal to (-eq) 192.168.0.240.

-------------------------- Example 5 ------------------------

Copy Code
Get-CsAnalogDevice -Filter {AnalogFax -eq $True}

The command shown in Example 5 returns information about all the analog fax machines in the organization. To perform this task, the command calls Get-CsAnalogDevice along with the -Filter parameter. The filter value {AnalogFax -eq $True} limits the returned objects to fax machines: analog devices where the AnalogFax property is equal to (-eq) True ($True).

-------------------------- Example 6 ------------------------

Copy Code
Get-CsAnalogDevice -Filter {LineUri -eq "tel:+14255556001"}

In Example 6, a single analog device is returned: the device that has a LineUri (phone number) equal to (-eq) tel:+14255556001.

-------------------------- Example 7 ------------------------

Copy Code
Get-CsAnalogDevice -Filter {LineUri -like "tel:+1425555*"}

Example 7 returns all the analog devices that have an area code of 425 and the phone prefix 555. To carry out this task, Get-CsAnalogDevice is used along with the -Filter parameter; the filter value {LineUri -like "tel:+1425555*"} limits the returned data to devices where the LineUri property begins with the characters "tel:+1425555". That’s equivalent to a phone number that begins with these characters: 1425555.

-------------------------- Example 8 ------------------------

Copy Code
Get-CsAnalogDevice -OU "ou=Telecommunications,dc=litwareinc,dc=com"

The preceding command returns a collection of all the analog devices that have a contact object in the Telecommunications OU in Active Directory. To do this, Get-CsAnalogDevice is called along with the -OU parameter; the parameter value limits the returned objects to analog devices that have contacts objects in the OU with the distinguished name ou=Telecommunications,dc=litwareinc,dc=com.